/usr/bin/diffoscope --timeout 7200 --html /srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/libgnatcoll_21.0.0-4.diffoscope.html --text /srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/libgnatcoll_21.0.0-4.diffoscope.txt --json /srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/libgnatcoll_21.0.0-4.diffoscope.json --profile=- /srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/b1/libgnatcoll_21.0.0-4_arm64.changes /srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/b2/libgnatcoll_21.0.0-4

⊟

14.7 MB

/srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/b1/libgnatcoll_21.0.0-4_arm64.changes vs.

/srv/reproducible-results/rbuild-debian/r-b-build.DDpJ2nCv/b2/libgnatcoll_21.0.0-4_arm64.changes ¶

⊟

678 B

Files ¶

⊟

346 KB

libgnatcoll-doc_21.0.0-4_all.deb ¶

⊟

452 B

file list ¶

⊟

512 B

control.tar.xz ¶

⊟

484 B

control.tar ¶

⊟

414 B

./control ¶

⊟

48.0 B

./md5sums ¶

⊟

30.0 B

./md5sums ¶

Files differ

⊟

345 KB

data.tar.xz ¶

⊟

345 KB

data.tar ¶

⊟

14.2 KB

file list ¶

⊟

97.8 KB

⊟

97.7 KB

⊟

97.7 KB

⊟

5.01 KB

⊟

2.1 KB

⊟

3.73 KB

⊟

1.46 KB

⊟

7.56 KB

⊟

3.31 KB

⊟

1.66 KB

⊟

875 B

⊟

1.96 KB

⊟

809 B

⊟

2.29 KB

⊟

738 B

⊟

5.02 KB

⊟

1.72 KB

⊟

5.19 KB

⊟

2.73 KB

⊟

1.91 KB

⊟

597 B

⊟

55.1 KB

⊟

25.2 KB

⊟

2.57 KB

⊟

1.25 KB

⊟

17.3 KB

⊟

7.91 KB

⊟

7.52 KB

⊟

3.87 KB

⊟

36.1 KB

⊟

16.1 KB

⊟

3.34 KB

⊟

1.49 KB

⊟

13.1 KB

⊟

6.62 KB

⊟

2.04 KB

⊟

45.0 B

⊟

1.12 KB

⊟

45.0 B

⊟

2.74 KB

⊟

2.64 KB

⊟

45.0 B

⊟

617 B

⊟

519 B

⊟

45.0 B

⊟

769 B

⊟

45.0 B

⊟

796 B

⊟

45.0 B

⊟

1.47 KB

⊟

45.0 B

⊟

2.05 KB

⊟

1.96 KB

⊟

45.0 B

⊟

700 B

⊟

596 B

⊟

45.0 B

⊟

20.5 KB

⊟

20.4 KB

⊟

45.0 B

⊟

1.15 KB

⊟

45.0 B

⊟

6.64 KB

⊟

6.54 KB

⊟

45.0 B

⊟

3.07 KB

⊟

45.0 B

⊟

13.9 KB

⊟

13.8 KB

⊟

45.0 B

⊟

1.37 KB

⊟

45.0 B

⊟

5.15 KB

⊟

5.06 KB

⊟

45.0 B

⊟

1.56 KB

libgnatcoll19_21.0.0-4_arm64.deb ¶

⊟

98.0 B

control.tar.xz ¶

⊟

70.0 B

control.tar ¶

⊟

48.0 B

./md5sums ¶

⊟

30.0 B

./md5sums ¶

Files differ

⊟

1.4 KB

data.tar.xz ¶

⊟

1.38 KB

data.tar ¶

⊟

1.36 KB

./usr/lib/aarch64-linux-gnu/libgnatcoll.so.19 ¶

File has been modified after NT_GNU_BUILD_ID has been applied.

⊟

430 B

readelf --wide --notes {} ¶

⊟

811 B

readelf --wide --decompress --hex-dump=.gnu_debuglink {} ¶

error from `readelf --wide --decompress --hex-dump=.gnu_debuglink {}`: readelf: Error: no .dynamic section in the dynamic segment

⊟

14.3 MB

libgnatcoll19-dbgsym_21.0.0-4_arm64.deb ¶

⊟

367 B

file list ¶

⊟

628 B

control.tar.xz ¶

⊟

600 B

control.tar ¶

⊟

352 B

./control ¶

⊟

226 B

./md5sums ¶

⊟

30.0 B

./md5sums ¶

Files differ

⊟

178 B

line order ¶

⊟

14.3 MB

data.tar.xz ¶

⊟

14.3 MB

data.tar ¶

⊟

1.39 KB

file list ¶

⊟

14.3 MB

./usr/lib/debug/.build-id/74/1ce70cae34ead8cba4b6704c2dfe9056571d39.debug vs.

./usr/lib/debug/.build-id/31/7aec252cb5a2c24a2d3a59b7970742b7060f18.debug ¶

File has been modified after NT_GNU_BUILD_ID has been applied. Files 2% similar despite different names

⊟

870 B

readelf --wide --file-header {} ¶

⊟

3.12 KB

readelf --wide --sections {} ¶

⊟

430 B

readelf --wide --notes {} ¶

⊟

13.5 MB

readelf --wide --debug-dump=info {} ¶

⊟

8.25 KB

strings --all --bytes=8 {} ¶

⊟

786 KB

readelf --wide --decompress --string-dump=.debug_str {} ¶


Offset 1, 5 lines modified		Offset 1, 5 lines modified

1	·d0f60c37451c5a632eb360f1e1c14207·515324·doc·optional·libgnatcoll-doc_21.0.0-4_all.deb
2	·a~~55d~~d~~161a~~2d~~eef~~d~~95e86e80~~35a~~ffa9~~6~~2·318306~~4·debug·optional·libgnatcoll19-d~~bgs~~ym_21.0.0-4_arm64.deb	1	·23fda4cb2d47c4dc7c0c5ae359320674·546124·doc·optional·libgnatcoll-doc_21.0.0-4_all.deb
		2	·520aebbd73a2a565db24c5b4094e20b3·3183088·debug·optional·libgnatcoll19-dbgsym_21.0.0-4_arm64.deb
3	·51918aaf481f6ddbdda4124d5e7bada6·2167196·libdevel·optional·libgnatcoll19-dev_21.0.0-4_arm64.deb	3	·51918aaf481f6ddbdda4124d5e7bada6·2167196·libdevel·optional·libgnatcoll19-dev_21.0.0-4_arm64.deb
4	·~~9e1~~b~~f146~~42~~c9d35829506e~~e189~~505d~~eb·1340348·libs·optional·libgnatcoll19_21.0.0-4_arm64.deb	4	·8d56bbebf451f8403f3aa9e78bdd1eb7·1340348·libs·optional·libgnatcoll19_21.0.0-4_arm64.deb


Offset 1, 3 lines modified		Offset 1, 3 lines modified
1	-rw-r--r--···0········0········0········4·2020-12-22·09:58:09.000000·debian-binary	1	-rw-r--r--···0········0········0········4·2020-12-22·09:58:09.000000·debian-binary
2	-rw-r--r--···0········0········0·····3380·2020-12-22·09:58:09.000000·control.tar.xz	2	-rw-r--r--···0········0········0·····3388·2020-12-22·09:58:09.000000·control.tar.xz
3	-rw-r--r--···0········0········0···5~~11752~~·2020-12-22·09:58:09.000000·data.tar.xz	3	-rw-r--r--···0········0········0···542544·2020-12-22·09:58:09.000000·data.tar.xz


Offset 1, 13 lines modified		Offset 1, 13 lines modified
1	Package:·libgnatcoll-doc	1	Package:·libgnatcoll-doc
2	Source:·libgnatcoll	2	Source:·libgnatcoll
3	Version:·21.0.0-4	3	Version:·21.0.0-4
4	Architecture:·all	4	Architecture:·all
5	Maintainer:·Nicolas·Boulenguez·<nicolas@debian.org>	5	Maintainer:·Nicolas·Boulenguez·<nicolas@debian.org>
6	Installed-Size:·1122	6	Installed-Size:·1151
7	Depends:·libjs-sphinxdoc·(>=·2.4.3-5~)	7	Depends:·libjs-sphinxdoc·(>=·2.4.3-5~)
8	Suggests:·gnat	8	Suggests:·gnat
9	Built-Using:·sphinx·(=·3.4.3-2)	9	Built-Using:·sphinx·(=·3.4.3-2)
10	Section:·doc	10	Section:·doc
11	Priority:·optional	11	Priority:·optional
12	Multi-Arch:·foreign	12	Multi-Arch:·foreign
13	Homepage:·https://github.com/AdaCore/gnatcoll-core	13	Homepage:·https://github.com/AdaCore/gnatcoll-core


Offset 59, 168 lines modified		Offset 59, 174 lines modified
59	11	59	11
60	18	60	18
61	18	61	18
62	18	62	18

63	4	63	4

		64	Traces:·Logging·information
64	Strings:·high-performance·strings
65	4.1·Small·string·optimization·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
66	4.2·Ch~~aracte~~r~~·types·.·.~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	65	4.1·Configuring·traces·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
67	4.3·Configuring·the·size·of·small·strings·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
68	4.4·Task~~·safety~~·~~.·.·.·.·.·.·.~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	66	4.2·Using·the·traces·module·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		67	4.2.1
		68	Logging·unexpected·exceptions·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		69	4.2.2
		70	Checking·whether·the·handle·is·active·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
69	4.5·Copy·~~on·w~~rite·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	71	4.3·Log·decorators·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		72	4.4·Defining·custom·stream·types·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
70	4.6·~~Growth·s~~t~~rategy·.~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	73	4.5·Logging·to·syslog·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
71	4.7·S~~ubstr~~i~~ngs·.~~·~~.·.·.·.·.~~·.~~·.·.·.·.~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	74	4.6·Dynamically·disabling·features·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
72	4.8·API·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.

73	19	75	19
74	19	76	19
75	20
76	20
77	21
78	21
79	21	77	21
80	22	78	22
		79	22
81	23	80	23
		81	24

82	5

83	Memory:·Monitoring·memory·usage

84	25	82	25
		83	26

85	6	84	5

86	~~Mmap:·Read~~i~~ng·and·W~~r~~iting~~·Files	85	Strings:·high-performance·strings
		86	5.1·Small·string·optimization·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		87	5.2·Character·types·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		88	5.3·Configuring·the·size·of·small·strings·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		89	5.4·Task·safety·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		90	5.5·Copy·on·write·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		91	5.6·Growth·strategy·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		92	5.7·Substrings·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		93	5.8·API·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.

87	27	94	27

88	7

89	Boyer-Moore:·Searching·strings
		95	27
		96	28
		97	28
		98	29
		99	29
		100	29
		101	30
90	31	102	31

91	8	103	6

92	~~Paragraph·f~~illing:·form~~atting·t~~ext	104	Memory:·Monitoring·memory·usage

93	33	105	33
		106	i

94	9	107	.7

95	~~Tem~~p~~lat~~e~~s:·~~generating·~~text~~	108	Mmap:·Reading·and·Writing·Files

96	35	109	35

		110	8
97	10·Email:·Processing·email·messages

98	37

99	i

		111	Boyer-Moore:·Searching·strings
100	\xc10.1
101	10.2
102	10.3
103	10.4

104	Message·formats·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
105	Parsing·messages·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
106	Parsing·mailboxes·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
107	Creating·messages·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.

108	37
109	38
110	38
111	39	112	39

		113	9

		114	Paragraph·filling:·formatting·text
112	11·Ravenscar:·patterns·for·multitasking
113	11.1·Tasks·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
114	11.2·Servers·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
115	11.3·Timers·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.

116	41
117	41
118	41
119	41	115	41

120	12·~~Stor~~age~~·Pool~~s:·controlling~~·memory~~·~~manage~~ment	116	10·Templates:·generating·text

121	43	117	43

122	13·~~VFS:·Manipulat~~ing·Files	118	11·Email:·Processing·email·messages
123	13.1·Files~~yst~~e~~ms·abs~~t~~raction~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	119	11.1·Message·formats·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
124	13.~~1.1·f~~ile·names·~~encoding~~·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	120	11.2·Parsing·messages·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
		121	11.3·Parsing·mailboxes·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
125	13.2·~~Remo~~t~~e·fil~~esys~~tem~~s·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.	122	11.4·Creating·messages·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
126	13.2.1·Filesystem·factory·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.·.
Max diff block lines reached; 94531/99995 bytes (94.54%) of diff not shown.


Offset 50, 31 lines modified		Offset 50, 31 lines modified
50	<p>The·package·<strong>GNATCOLL.Boyer_Moore</strong>·provides·one·such·optimize·algorithm,	50	<p>The·package·<strong>GNATCOLL.Boyer_Moore</strong>·provides·one·such·optimize·algorithm,
51	although·there·exists·several·others·which·might·be·more·efficient·depending	51	although·there·exists·several·others·which·might·be·more·efficient·depending
52	on·the·pattern.</p>	52	on·the·pattern.</p>
53	<p>It·deals·with·string·searching,·and·does·not·handle·regular·expressions·for	53	<p>It·deals·with·string·searching,·and·does·not·handle·regular·expressions·for
54	instance.</p>	54	instance.</p>
55	<p>This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but·does	55	<p>This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but·does
56	not·need·to·perform·any·specific·analysis·of·the·string·to·be·searched.	56	not·need·to·perform·any·specific·analysis·of·the·string·to·be·searched.
57	Its·execution·time·can·be·sub-linear:·it·doesn't·need·to·actually·check	57	Its·execution·time·can·be·sub-linear:·it·doesn’t·need·to·actually·check
58	every·character·of·the·string·to·be·searched,·and·will·skip·over·some·of	58	every·character·of·the·string·to·be·searched,·and·will·skip·over·some·of
59	them.·The·worst·case·for·this·algorithm·has·been·proved·to·need·approximately	59	them.·The·worst·case·for·this·algorithm·has·been·proved·to·need·approximately
60	3·*·N·comparisons,·hence·the·algorithm·has·a·complexity·of·O(n).</p>	60	3·*·N·comparisons,·hence·the·algorithm·has·a·complexity·of·O(n).</p>
61	<p>The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that·provides	61	<p>The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that·provides
62	more·context·as·to·how·many·characters·can·be·skipped·when·a·non-matching	62	more·context·as·to·how·many·characters·can·be·skipped·when·a·non-matching
63	character·is·found..</p>	63	character·is·found..</p>
64	<p>We·will·not·go·into·the·details·of·the·algorithm,·although·a·general	64	<p>We·will·not·go·into·the·details·of·the·algorithm,·although·a·general
65	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-Moore	65	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-Moore
66	computes·how·many·characters·can·be·skipped·if·an·incorrect·match·is	66	computes·how·many·characters·can·be·skipped·if·an·incorrect·match·is
67	found·at·that·point,·depending·on·which·character·was·read.	67	found·at·that·point,·depending·on·which·character·was·read.
68	In·addition,·this·algorithm·tries·to·match·the·key·starting·from·its·end,	68	In·addition,·this·algorithm·tries·to·match·the·key·starting·from·its·end,
69	which·in·general·provides·a·greater·number·of·characters·to·skip.</p>	69	which·in·general·provides·a·greater·number·of·characters·to·skip.</p>
70	<p>For·instance,·if·you·are·looking·for·~~&quot~~;ABC~~&quot~~;·in·the·string·~~&quot~~;ABDEFG~~&quot~~;·at·the	70	<p>For·instance,·if·you·are·looking·for·“ABC”·in·the·string·“ABDEFG”·at·the
71	first·position,·the·algorithm·will·compare·~~&quot~~;C~~&quot~~;·and·~~&quot~~;D~~&quot~~;.·Since·~~&quot~~;D~~&quot~~;·does·not	71	first·position,·the·algorithm·will·compare·“C”·and·“D”.·Since·“D”·does·not
72	appear·in·the·key·~~&quot~~;ABC~~&quot~~;,·it·knows·that·it·can·immediately·skip·3·characters	72	appear·in·the·key·“ABC”,·it·knows·that·it·can·immediately·skip·3·characters
73	and·start·the·search·after·~~&quot~~;D~~&quot~~;.</p>	73	and·start·the·search·after·“D”.</p>
74	<p>Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:</p>	74	<p>Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:</p>
75	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>	75	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>
76	··<span·class="no">Str</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="kt">String</span>·<span·class="p">:=</span>·<span·class="s">"ABDEABCFGABC"</span><span·class="p">;</span>	76	··<span·class="no">Str</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="kt">String</span>·<span·class="p">:=</span>·<span·class="s">"ABDEABCFGABC"</span><span·class="p">;</span>
77	··<span·class="n">Key</span>·<span·class="p">:</span>·<span·class="n">Pattern</span><span·class="p">;</span>	77	··<span·class="n">Key</span>·<span·class="p">:</span>·<span·class="n">Pattern</span><span·class="p">;</span>
78	··<span·class="n">Index</span>·<span·class="p">:</span>·<span·class="kt">Integer</span><span·class="p">;</span>	78	··<span·class="n">Index</span>·<span·class="p">:</span>·<span·class="kt">Integer</span><span·class="p">;</span>
79	<span·class="kr">begin</span>	79	<span·class="kr">begin</span>
80	··<span·class="n">Compile</span>·<span·class="p">(</span><span·class="n">Key</span><span·class="p">,</span>·<span·class="s">"ABC"</span><span·class="p">);</span>	80	··<span·class="n">Compile</span>·<span·class="p">(</span><span·class="n">Key</span><span·class="p">,</span>·<span·class="s">"ABC"</span><span·class="p">);</span>


Offset 21, 31 lines modified		Offset 21, 31 lines modified
21	The·package·GNATCOLL.Boyer_Moore·provides·one·such·optimize·algorithm,·although	21	The·package·GNATCOLL.Boyer_Moore·provides·one·such·optimize·algorithm,·although
22	there·exists·several·others·which·might·be·more·efficient·depending·on·the	22	there·exists·several·others·which·might·be·more·efficient·depending·on·the
23	pattern.	23	pattern.
24	It·deals·with·string·searching,·and·does·not·handle·regular·expressions·for	24	It·deals·with·string·searching,·and·does·not·handle·regular·expressions·for
25	instance.	25	instance.
26	This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but·does·not	26	This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but·does·not
27	need·to·perform·any·specific·analysis·of·the·string·to·be·searched.·Its	27	need·to·perform·any·specific·analysis·of·the·string·to·be·searched.·Its
28	execution·time·can·be·sub-linear:·it·doesn't·need·to·actually·check·every	28	execution·time·can·be·sub-linear:·it·doesnât·need·to·actually·check·every
29	character·of·the·string·to·be·searched,·and·will·skip·over·some·of·them.·The	29	character·of·the·string·to·be·searched,·and·will·skip·over·some·of·them.·The
30	worst·case·for·this·algorithm·has·been·proved·to·need·approximately·3·*·N	30	worst·case·for·this·algorithm·has·been·proved·to·need·approximately·3·*·N
31	comparisons,·hence·the·algorithm·has·a·complexity·of·O(n).	31	comparisons,·hence·the·algorithm·has·a·complexity·of·O(n).
32	The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that·provides	32	The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that·provides
33	more·context·as·to·how·many·characters·can·be·skipped·when·a·non-matching	33	more·context·as·to·how·many·characters·can·be·skipped·when·a·non-matching
34	character·is·found..	34	character·is·found..
35	We·will·not·go·into·the·details·of·the·algorithm,·although·a·general	35	We·will·not·go·into·the·details·of·the·algorithm,·although·a·general
36	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-Moore	36	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-Moore
37	computes·how·many·characters·can·be·skipped·if·an·incorrect·match·is·found·at	37	computes·how·many·characters·can·be·skipped·if·an·incorrect·match·is·found·at
38	that·point,·depending·on·which·character·was·read.·In·addition,·this·algorithm	38	that·point,·depending·on·which·character·was·read.·In·addition,·this·algorithm
39	tries·to·match·the·key·starting·from·its·end,·which·in·general·provides·a	39	tries·to·match·the·key·starting·from·its·end,·which·in·general·provides·a
40	greater·number·of·characters·to·skip.	40	greater·number·of·characters·to·skip.
41	For·instance,·if·you·are·looking·for·"ABC"·in·the·string·"ABDEFG~~"·at·the~~·~~fir~~st	41	For·instance,·if·you·are·looking·for·âABCâ·in·the·string·âABDEFGâ·at
42	position,·the·algorithm·will·compare·"C"·and·"D".·Since·"D"·does·not·appear·in
43	the·key·"ABC",·it·knows·that·it·can·immediately·skip·3·characters·and·start·the
44	search·a~~fter~~·"D".	42	the·first·position,·the·algorithm·will·compare·âCâ·and·âDâ.·Since
		43	âDâ·does·not·appear·in·the·key·âABCâ,·it·knows·that·it·can·immediately
		44	skip·3·characters·and·start·the·search·after·âDâ.
45	Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:	45	Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:
46	declare	46	declare
47	··Str·:·constant·String·:=·"ABDEABCFGABC";	47	··Str·:·constant·String·:=·"ABDEABCFGABC";
48	··Key·:·Pattern;	48	··Key·:·Pattern;
49	··Index·:·Integer;	49	··Index·:·Integer;
50	begin	50	begin
51	··Compile·(Key,·"ABC");	51	··Compile·(Key,·"ABC");


Offset 66, 15 lines modified		Offset 66, 15 lines modified
66	</dd>	66	</dd>
67	<dt><em>PROCESSORS</em></dt><dd><p>Parallel·compilation·(default·is·0,·which·uses·all·available·cores)</p>	67	<dt><em>PROCESSORS</em></dt><dd><p>Parallel·compilation·(default·is·0,·which·uses·all·available·cores)</p>
68	</dd>	68	</dd>
69	<dt><em>TARGET</em></dt><dd><p>For·cross-compilation,·auto-detected·for·native·platforms</p>	69	<dt><em>TARGET</em></dt><dd><p>For·cross-compilation,·auto-detected·for·native·platforms</p>
70	</dd>	70	</dd>
71	<dt><em>SOURCE_DIR</em></dt><dd><p>For·out-of-tree·build</p>	71	<dt><em>SOURCE_DIR</em></dt><dd><p>For·out-of-tree·build</p>
72	</dd>	72	</dd>
73	<dt><em>ENABLE_SHARED</em></dt><dd><p>Controls·whether·shared·and·static-pic·library·variants·should·be·built:·yes·(default)·or·no.·If·you·only·intend·to·use·static·libraries,·specify·'no'.</p>	73	<dt><em>ENABLE_SHARED</em></dt><dd><p>Controls·whether·shared·and·static-pic·library·variants·should·be·built:·yes·(default)·or·no.·If·you·only·intend·to·use·static·libraries,·specify·‘no’.</p>
74	</dd>	74	</dd>
75	</dl>	75	</dl>
76	<p>Module-specific:</p>	76	<p>Module-specific:</p>
77	<dl·class="simple">	77	<dl·class="simple">
78	<dt><em>GNATCOLL_MMAP</em></dt><dd><p>Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where·embedded·MMAP·implementation·is·always·provided.</p>	78	<dt><em>GNATCOLL_MMAP</em></dt><dd><p>Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where·embedded·MMAP·implementation·is·always·provided.</p>
79	</dd>	79	</dd>
80	<dt><em>GNATCOLL_MADVISE</em></dt><dd><p>Whether·MADVISE:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where·MADVISE·functionality·is·unavailable</p>	80	<dt><em>GNATCOLL_MADVISE</em></dt><dd><p>Whether·MADVISE:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where·MADVISE·functionality·is·unavailable</p>
Offset 101, 15 lines modified		Offset 101, 15 lines modified
101	</pre></div>	101	</pre></div>
102	</div>	102	</div>
103	<p>Note·that·this·command·does·not·try·to·recompile·GNATColl,·so·you·must·build	103	<p>Note·that·this·command·does·not·try·to·recompile·GNATColl,·so·you·must·build
104	it·first.·This·command·will·install·all·library·variants·that·were·built.</p>	104	it·first.·This·command·will·install·all·library·variants·that·were·built.</p>
105	<p>Your·application·can·now·use·the·GNATColl·code·through·a·project·file,·by	105	<p>Your·application·can·now·use·the·GNATColl·code·through·a·project·file,·by
106	adding·a·<code·class="docutils·literal·notranslate"><span·class="pre">with</span></code>·clause·to·<code·class="file·docutils·literal·notranslate"><span·class="pre">gnatcoll.gpr</span></code>.</p>	106	adding·a·<code·class="docutils·literal·notranslate"><span·class="pre">with</span></code>·clause·to·<code·class="file·docutils·literal·notranslate"><span·class="pre">gnatcoll.gpr</span></code>.</p>
107	<p>If·you·wish·to·install·in·a·different·location·than·was·specified·at	107	<p>If·you·wish·to·install·in·a·different·location·than·was·specified·at
108	configure·time,·you·can·override·the·~~&quot~~;prefix~~&quot~~;·variable·from·the·command·line,	108	configure·time,·you·can·override·the·“prefix”·variable·from·the·command·line,
109	for·instance:</p>	109	for·instance:</p>
110	<div·class="highlight-default·notranslate"><div·class="highlight"><pre><span></span><span·class="n">make</span>·<span·class="n">prefix</span><span·class="o">=/</span><span·class="n">alternate</span><span·class="o">/</span><span·class="n">directory</span>·<span·class="n">install</span>	110	<div·class="highlight-default·notranslate"><div·class="highlight"><pre><span></span><span·class="n">make</span>·<span·class="n">prefix</span><span·class="o">=/</span><span·class="n">alternate</span><span·class="o">/</span><span·class="n">directory</span>·<span·class="n">install</span>
111	</pre></div>	111	</pre></div>
112	</div>	112	</div>
113	<p>This·does·not·require·any·recompilation.</p>	113	<p>This·does·not·require·any·recompilation.</p>
114	</div>	114	</div>
115	</div>	115	</div>


Offset 40, 15 lines modified		Offset 40, 15 lines modified
40	··TARGET	40	··TARGET
41	······For·cross-compilation,·auto-detected·for·native·platforms	41	······For·cross-compilation,·auto-detected·for·native·platforms
42	··SOURCE_DIR	42	··SOURCE_DIR
43	······For·out-of-tree·build	43	······For·out-of-tree·build
44	··ENABLE_SHARED	44	··ENABLE_SHARED
45	······Controls·whether·shared·and·static-pic·library·variants·should·be·built:	45	······Controls·whether·shared·and·static-pic·library·variants·should·be·built:
46	······yes·(default)·or·no.·If·you·only·intend·to·use·static·libraries,·specify	46	······yes·(default)·or·no.·If·you·only·intend·to·use·static·libraries,·specify
47	······'no'.	47	······ânoâ.
48	Module-specific:	48	Module-specific:
49	··GNATCOLL_MMAP	49	··GNATCOLL_MMAP
50	······Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect·on	50	······Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect·on
51	······Windows·where·embedded·MMAP·implementation·is·always·provided.	51	······Windows·where·embedded·MMAP·implementation·is·always·provided.
52	··GNATCOLL_MADVISE	52	··GNATCOLL_MADVISE
53	······Whether·MADVISE:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where	53	······Whether·MADVISE:·yes·(default)·or·no;·this·has·no·effect·on·Windows·where
54	······MADVISE·functionality·is·unavailable	54	······MADVISE·functionality·is·unavailable
Offset 63, 15 lines modified		Offset 63, 15 lines modified
63	Installing·the·library·is·done·with·the·following·command:	63	Installing·the·library·is·done·with·the·following·command:
64	make·install	64	make·install
65	Note·that·this·command·does·not·try·to·recompile·GNATColl,·so·you·must·build·it	65	Note·that·this·command·does·not·try·to·recompile·GNATColl,·so·you·must·build·it
66	first.·This·command·will·install·all·library·variants·that·were·built.	66	first.·This·command·will·install·all·library·variants·that·were·built.
67	Your·application·can·now·use·the·GNATColl·code·through·a·project·file,·by	67	Your·application·can·now·use·the·GNATColl·code·through·a·project·file,·by
68	adding·a·with·clause·to·gnatcoll.gpr.	68	adding·a·with·clause·to·gnatcoll.gpr.
69	If·you·wish·to·install·in·a·different·location·than·was·specified·at·configure	69	If·you·wish·to·install·in·a·different·location·than·was·specified·at·configure
70	time,·you·can·override·the·"prefix"·variable·from·the·command·line,·for	70	time,·you·can·override·the·âprefixâ·variable·from·the·command·line,·for
71	instance:	71	instance:
72	make·prefix=/alternate/directory·install	72	make·prefix=/alternate/directory·install
73	This·does·not·require·any·recompilation.	73	This·does·not·require·any·recompilation.
74	[Logo]	74	[Logo]
75	**·Table_of_Contents·**	75	**·Table_of_Contents·**
76	····*·2._Building_GNATColl	76	····*·2._Building_GNATColl
77	··········o·2.1._Configuring_the_build_environment	77	··········o·2.1._Configuring_the_build_environment


Offset 49, 29 lines modified		Offset 49, 29 lines modified
49	cases.</p>	49	cases.</p>
50	<p>There·are·lots·of·possible·formats·for·such·configuration·files:·you·could	50	<p>There·are·lots·of·possible·formats·for·such·configuration·files:·you·could
51	chose·to·use·an·XML·file·(but·these·are·in·general·hard·to·edit·manually),	51	chose·to·use·an·XML·file·(but·these·are·in·general·hard·to·edit·manually),
52	a·binary·file,·or·any·other·format.·One·format·that·is·found·very·often·is	52	a·binary·file,·or·any·other·format.·One·format·that·is·found·very·often·is
53	the·one·used·by·a·lot·of·Windows·applications·(the·<code·class="file·docutils·literal·notranslate"><span·class="pre">.ini</span></code>·file·format).</p>	53	the·one·used·by·a·lot·of·Windows·applications·(the·<code·class="file·docutils·literal·notranslate"><span·class="pre">.ini</span></code>·file·format).</p>
54	<p><cite>GNATCOLL.Config</cite>·is·independent·from·the·actual·format·you·are·using,	54	<p><cite>GNATCOLL.Config</cite>·is·independent·from·the·actual·format·you·are·using,
55	and·you·can·add·your·own·parsers·compatible·with·the·<cite>GNATCOLL.Config</cite>	55	and·you·can·add·your·own·parsers·compatible·with·the·<cite>GNATCOLL.Config</cite>
56	API.·Out·of·the·box,·support·is·provided·for·<code·class="file·docutils·literal·notranslate"><span·class="pre">.ini</span></code>·files,·so·let's	56	API.·Out·of·the·box,·support·is·provided·for·<code·class="file·docutils·literal·notranslate"><span·class="pre">.ini</span></code>·files,·so·let’s
57	detail·this·very·simply·format:</p>	57	detail·this·very·simply·format:</p>
58	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span>#·A·single-line·comment	58	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span>#·A·single-line·comment
59	[Section1]	59	[Section1]
60	key1·=·value	60	key1·=·value
61	key2=value2	61	key2=value2

62	[Section2]	62	[Section2]
63	key1·=·value3	63	key1·=·value3
64	</pre></div>	64	</pre></div>
65	</div>	65	</div>
66	<p>Comments·are·(by·default)·started·with·<cite>'#'</cite>·signs,·but·you·can	66	<p>Comments·are·(by·default)·started·with·<cite>‘#’</cite>·signs,·but·you·can
67	configure·that·and·use·any·prefix·you·want.·The·<cite>(key,·value)</cite>·pairs	67	configure·that·and·use·any·prefix·you·want.·The·<cite>(key,·value)</cite>·pairs
68	are·then·organized·into·optional·sections·(if·you·do·not·start·a·section	68	are·then·organized·into·optional·sections·(if·you·do·not·start·a·section
69	before·the·first·key,·that·key·will·be·considered·as·part·of·the·<cite>~~"&quo~~t;</cite>	69	before·the·first·key,·that·key·will·be·considered·as·part·of·the·<cite>“”</cite>
70	section).·A·section·then·extends·until·the·start·of·the·next·section.</p>	70	section).·A·section·then·extends·until·the·start·of·the·next·section.</p>
71	<p>The·values·associated·with·the·various·keys·can·be·strings,·integers·or	71	<p>The·values·associated·with·the·various·keys·can·be·strings,·integers·or
72	booleans.·Spaces·on·the·left·and·right·of·the·values·and·keys·are·trimmed,	72	booleans.·Spaces·on·the·left·and·right·of·the·values·and·keys·are·trimmed,
73	and·therefore·irrelevant.</p>	73	and·therefore·irrelevant.</p>
74	<p>Support·is·providing·for·interpreting·the·values·as·file·or·directory	74	<p>Support·is·providing·for·interpreting·the·values·as·file·or·directory
75	names.·In·such·a·case,·if·a·relative·name·is·specified·in·the·configuration	75	names.·In·such·a·case,·if·a·relative·name·is·specified·in·the·configuration
76	file·it·will·be·assumed·to·be·relative·to·the·location·of·the·configuration	76	file·it·will·be·assumed·to·be·relative·to·the·location·of·the·configuration
Offset 114, 19 lines modified		Offset 114, 19 lines modified
114	<span·class="n">Put_Line</span>·<span·class="p">(</span><span·class="n">Config</span><span·class="p">.</span><span·class="n">Get</span>·<span·class="p">(</span><span·class="s">"section.key"</span><span·class="p">));</span>··<span·class="c1">--··Ada05·dotted·notation</span>	114	<span·class="n">Put_Line</span>·<span·class="p">(</span><span·class="n">Config</span><span·class="p">.</span><span·class="n">Get</span>·<span·class="p">(</span><span·class="s">"section.key"</span><span·class="p">));</span>··<span·class="c1">--··Ada05·dotted·notation</span>
115	</pre></div>	115	</pre></div>
116	</div>	116	</div>
117	<p>Again,·the·values·are·by·default·read·as·strings,·but·you·can·interpret	117	<p>Again,·the·values·are·by·default·read·as·strings,·but·you·can·interpret
118	them·as·integers,·booleans·or·files.</p>	118	them·as·integers,·booleans·or·files.</p>
119	<p>A·third·layer·is·provided·in·<cite>GNATCOLL.Config</cite>.·This·solves·the·issue	119	<p>A·third·layer·is·provided·in·<cite>GNATCOLL.Config</cite>.·This·solves·the·issue
120	of·possible·typos·in·code:·in·the·above·example,·we·could·have·made·a·typo	120	of·possible·typos·in·code:·in·the·above·example,·we·could·have·made·a·typo
121	when·writting·<cite>~~&quot~~;section.key~~&quot~~;</cite>.·That·would·only·be·detected·at·run	121	when·writting·<cite>“section.key”</cite>.·That·would·only·be·detected·at·run
122	time.·Another·issue·is·that·we·might·decide·to·rename·the·key·in·the	122	time.·Another·issue·is·that·we·might·decide·to·rename·the·key·in·the
123	configuration·file.·We·would·then·have·to·go·through·all·the·application	123	configuration·file.·We·would·then·have·to·go·through·all·the·application
124	code·to·find·all·the·places·where·this·key·is·references·(and·that·can't	124	code·to·find·all·the·places·where·this·key·is·references·(and·that·can’t
125	be·based·on·cross-references·generated·by·the·compiler,·since·that's·inside	125	be·based·on·cross-references·generated·by·the·compiler,·since·that’s·inside
126	a·string).</p>	126	a·string).</p>
127	<p>To·solve·this·issue,·it·is·possible·to·declare·a·set·of·constants·that	127	<p>To·solve·this·issue,·it·is·possible·to·declare·a·set·of·constants·that
128	represent·the·keys,·and·then·use·these·to·access·the·values,·solving·the	128	represent·the·keys,·and·then·use·these·to·access·the·values,·solving·the
129	two·problems·above:</p>	129	two·problems·above:</p>
130	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="no">Section_Key1</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Config_Key</span>·<span·class="p">:=</span>·<span·class="n">Create</span>·<span·class="p">(</span><span·class="s">"Key1"</span><span·class="p">,</span>·<span·class="s">"Section"</span><span·class="p">);</span>	130	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="no">Section_Key1</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Config_Key</span>·<span·class="p">:=</span>·<span·class="n">Create</span>·<span·class="p">(</span><span·class="s">"Key1"</span><span·class="p">,</span>·<span·class="s">"Section"</span><span·class="p">);</span>
131	<span·class="no">Section_Key2</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Config_Key</span>·<span·class="p">:=</span>·<span·class="n">Create</span>·<span·class="p">(</span><span·class="s">"Key2"</span><span·class="p">,</span>·<span·class="s">"Section"</span><span·class="p">);</span>	131	<span·class="no">Section_Key2</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Config_Key</span>·<span·class="p">:=</span>·<span·class="n">Create</span>·<span·class="p">(</span><span·class="s">"Key2"</span><span·class="p">,</span>·<span·class="s">"Section"</span><span·class="p">);</span>


Offset 19, 27 lines modified		Offset 19, 27 lines modified
19	interactively.·However,·it·is·possible·to·use·them·for·both·cases.	19	interactively.·However,·it·is·possible·to·use·them·for·both·cases.
20	There·are·lots·of·possible·formats·for·such·configuration·files:·you·could	20	There·are·lots·of·possible·formats·for·such·configuration·files:·you·could
21	chose·to·use·an·XML·file·(but·these·are·in·general·hard·to·edit·manually),·a	21	chose·to·use·an·XML·file·(but·these·are·in·general·hard·to·edit·manually),·a
22	binary·file,·or·any·other·format.·One·format·that·is·found·very·often·is·the	22	binary·file,·or·any·other·format.·One·format·that·is·found·very·often·is·the
23	one·used·by·a·lot·of·Windows·applications·(the·.ini·file·format).	23	one·used·by·a·lot·of·Windows·applications·(the·.ini·file·format).
24	GNATCOLL.Configis·independent·from·the·actual·format·you·are·using,·and·you·can	24	GNATCOLL.Configis·independent·from·the·actual·format·you·are·using,·and·you·can
25	add·your·own·parsers·compatible·with·theGNATCOLL.ConfigAPI.·Out·of·the·box,	25	add·your·own·parsers·compatible·with·theGNATCOLL.ConfigAPI.·Out·of·the·box,
26	support·is·provided·for·.ini·files,·so·let's·detail·this·very·simply·format:	26	support·is·provided·for·.ini·files,·so·letâs·detail·this·very·simply·format:
27	#·A·single-line·comment	27	#·A·single-line·comment
28	[Section1]	28	[Section1]
29	key1·=·value	29	key1·=·value
30	key2=value2	30	key2=value2

31	[Section2]	31	[Section2]
32	key1·=·value3	32	key1·=·value3
33	Comments·are·(by·default)·started·with'#'signs,·but·you·can·configure·that~~·and~~	33	Comments·are·(by·default)·started·withâ#âsigns,·but·you·can·configure·that
34	use·any·prefix·you·want.·The(key,·value)pairs·are·then·organized·in~~to·op~~tio~~nal~~	34	and·use·any·prefix·you·want.·The(key,·value)pairs·are·then·organized·into
35	sections·(if·you·do·not·start·a·section·before·the·first·key,·that·key~~·will·be~~	35	optional·sections·(if·you·do·not·start·a·section·before·the·first·key,·that·key
36	considered·as·part·of·the""section).·A·section·then·extends·until~~·the·start·of~~	36	will·be·considered·as·part·of·theââsection).·A·section·then·extends·until
37	the·next·section.	37	the·start·of·the·next·section.
38	The·values·associated·with·the·various·keys·can·be·strings,·integers·or	38	The·values·associated·with·the·various·keys·can·be·strings,·integers·or
39	booleans.·Spaces·on·the·left·and·right·of·the·values·and·keys·are·trimmed,·and	39	booleans.·Spaces·on·the·left·and·right·of·the·values·and·keys·are·trimmed,·and
40	therefore·irrelevant.	40	therefore·irrelevant.
41	Support·is·providing·for·interpreting·the·values·as·file·or·directory·names.·In	41	Support·is·providing·for·interpreting·the·values·as·file·or·directory·names.·In
42	such·a·case,·if·a·relative·name·is·specified·in·the·configuration·file·it·will	42	such·a·case,·if·a·relative·name·is·specified·in·the·configuration·file·it·will
43	be·assumed·to·be·relative·to·the·location·of·the·configuration·file·(by	43	be·assumed·to·be·relative·to·the·location·of·the·configuration·file·(by
44	default,·but·you·can·also·configure·that).	44	default,·but·you·can·also·configure·that).
Offset 76, 19 lines modified		Offset 76, 19 lines modified
76	end;	76	end;

77	Put_Line·(Config.Get·("section.key"));··--··Ada05·dotted·notation	77	Put_Line·(Config.Get·("section.key"));··--··Ada05·dotted·notation
78	Again,·the·values·are·by·default·read·as·strings,·but·you·can·interpret·them·as	78	Again,·the·values·are·by·default·read·as·strings,·but·you·can·interpret·them·as
79	integers,·booleans·or·files.	79	integers,·booleans·or·files.
80	A·third·layer·is·provided·inGNATCOLL.Config.·This·solves·the·issue·of·possible	80	A·third·layer·is·provided·inGNATCOLL.Config.·This·solves·the·issue·of·possible
81	typos·in·code:·in·the·above·example,·we·could·have·made·a·typo·when	81	typos·in·code:·in·the·above·example,·we·could·have·made·a·typo·when
82	writting"section.key".·That·would·only·be·detected·at·run·time.·Another~~·issue~~	82	writtingâsection.keyâ.·That·would·only·be·detected·at·run·time.·Another
83	is·that·we·might·decide·to·rename·the·key·in·the·configuration·file.·We~~·would~~	83	issue·is·that·we·might·decide·to·rename·the·key·in·the·configuration·file.·We
84	then·have·to·go·through·all·the·application·code·to·find·all·the·places~~·where~~	84	would·then·have·to·go·through·all·the·application·code·to·find·all·the·places
85	this·key·is·references·(and·that·can't·be·based·on·cross-references~~·generated~~	85	where·this·key·is·references·(and·that·canât·be·based·on·cross-references
86	by·the·compiler,·since·that's·inside·a·string).	86	generated·by·the·compiler,·since·thatâs·inside·a·string).
87	To·solve·this·issue,·it·is·possible·to·declare·a·set·of·constants·that	87	To·solve·this·issue,·it·is·possible·to·declare·a·set·of·constants·that
88	represent·the·keys,·and·then·use·these·to·access·the·values,·solving·the·two	88	represent·the·keys,·and·then·use·these·to·access·the·values,·solving·the·two
89	problems·above:	89	problems·above:
90	Section_Key1·:·constant·Config_Key·:=·Create·("Key1",·"Section");	90	Section_Key1·:·constant·Config_Key·:=·Create·("Key1",·"Section");
91	Section_Key2·:·constant·Config_Key·:=·Create·("Key2",·"Section");	91	Section_Key2·:·constant·Config_Key·:=·Create·("Key2",·"Section");

92	Put_Line·(Section_Key1.Get);	92	Put_Line·(Section_Key1.Get);


Offset 169, 15 lines modified		Offset 169, 15 lines modified
169	</div>	169	</div>
170	<div·class="section"·id="creating-messages">	170	<div·class="section"·id="creating-messages">
171	<h2><span·class="section-number">11.4.·</span>Creating·messages<a·class="headerlink"·href="#creating-messages"·title="Permalink·to·this·headline">¶</a></h2>	171	<h2><span·class="section-number">11.4.·</span>Creating·messages<a·class="headerlink"·href="#creating-messages"·title="Permalink·to·this·headline">¶</a></h2>
172	<p>The·subprograms·in·<cite>GNATCOLL.Email</cite>·can·also·be·used·to·create·a·message	172	<p>The·subprograms·in·<cite>GNATCOLL.Email</cite>·can·also·be·used·to·create·a·message
173	from·scratch.·Alternatively,·if·you·have·already·parsed·a·message,·you	173	from·scratch.·Alternatively,·if·you·have·already·parsed·a·message,·you
174	can·alter·it,·or·easily·generate·a·reply·to·it·(using·the·<cite>Reply_To</cite>	174	can·alter·it,·or·easily·generate·a·reply·to·it·(using·the·<cite>Reply_To</cite>
175	subprogram.·The·latter·will·preset·some·headers,·so·that·message·threading	175	subprogram.·The·latter·will·preset·some·headers,·so·that·message·threading
176	is·preserved·in·the·user's·mailers.</p>	176	is·preserved·in·the·user’s·mailers.</p>
177	</div>	177	</div>
178	</div>	178	</div>


179	············<div·class="clearer"></div>	179	············<div·class="clearer"></div>
180	··········</div>	180	··········</div>
181	········</div>	181	········</div>


Offset 118, 15 lines modified		Offset 118, 15 lines modified
118	returned·might·be·null·if·the·mailbox·was·corrupted·and·the·message·could·not	118	returned·might·be·null·if·the·mailbox·was·corrupted·and·the·message·could·not
119	be·parsed.·There·are·still·chances·that·the·next·message·will·be·readable,·so	119	be·parsed.·There·are·still·chances·that·the·next·message·will·be·readable,·so
120	only·the·current·message·should·be·ignored.	120	only·the·current·message·should·be·ignored.
121	***·11.4.·Creating·messagesÂ¶·***	121	***·11.4.·Creating·messagesÂ¶·***
122	The·subprograms·inGNATCOLL.Emailcan·also·be·used·to·create·a·message·from	122	The·subprograms·inGNATCOLL.Emailcan·also·be·used·to·create·a·message·from
123	scratch.·Alternatively,·if·you·have·already·parsed·a·message,·you·can·alter·it,	123	scratch.·Alternatively,·if·you·have·already·parsed·a·message,·you·can·alter·it,
124	or·easily·generate·a·reply·to·it·(using·theReply_Tosubprogram.·The·latter·will	124	or·easily·generate·a·reply·to·it·(using·theReply_Tosubprogram.·The·latter·will
125	preset·some·headers,·so·that·message·threading·is·preserved·in·the·user's	125	preset·some·headers,·so·that·message·threading·is·preserved·in·the·userâs
126	mailers.	126	mailers.
127	[Logo]	127	[Logo]
128	**·Table_of_Contents·**	128	**·Table_of_Contents·**
129	····*·11._Email:_Processing_email_messages	129	····*·11._Email:_Processing_email_messages
130	··········o·11.1._Message_formats	130	··········o·11.1._Message_formats
131	··········o·11.2._Parsing_messages	131	··········o·11.2._Parsing_messages
132	··········o·11.3._Parsing_mailboxes	132	··········o·11.3._Parsing_mailboxes


Offset 39, 15 lines modified		Offset 39, 15 lines modified
39	······<div·class="documentwrapper">	39	······<div·class="documentwrapper">
40	········<div·class="bodywrapper">	40	········<div·class="bodywrapper">
41	··········<div·class="body"·role="main">	41	··········<div·class="body"·role="main">
42	············	42	············
43	··<div·class="section"·id="paragraph-filling-formatting-text">	43	··<div·class="section"·id="paragraph-filling-formatting-text">
44	<h1><span·class="section-number">9.·</span><strong>Paragraph·filling</strong>:·formatting·text<a·class="headerlink"·href="#paragraph-filling-formatting-text"·title="Permalink·to·this·headline">¶</a></h1>	44	<h1><span·class="section-number">9.·</span><strong>Paragraph·filling</strong>:·formatting·text<a·class="headerlink"·href="#paragraph-filling-formatting-text"·title="Permalink·to·this·headline">¶</a></h1>
45	<span·class="target"·id="index-0"></span><span·class="target"·id="index-1"></span><p·id="index-2">The·package·<cite>GNATCOLL.Paragraph_Filling</cite>·provides·several·algorithms·for	45	<span·class="target"·id="index-0"></span><span·class="target"·id="index-1"></span><p·id="index-2">The·package·<cite>GNATCOLL.Paragraph_Filling</cite>·provides·several·algorithms·for
46	filling·paragraphs---formatting·them·to·take·up·the·minimal·number·of·lines·and	46	filling·paragraphs—formatting·them·to·take·up·the·minimal·number·of·lines·and
47	to·look·better.·<cite>Knuth_Fill</cite>·is·based·on·an·algorithm·invented·by·Donald	47	to·look·better.·<cite>Knuth_Fill</cite>·is·based·on·an·algorithm·invented·by·Donald
48	Knuth,·and·used·in·TeX.·<cite>Pretty_Fill</cite>·uses·a·different·algorithm,·which	48	Knuth,·and·used·in·TeX.·<cite>Pretty_Fill</cite>·uses·a·different·algorithm,·which
49	was·judged·by·some·to·produce·more·aesthetically·pleasing·output.</p>	49	was·judged·by·some·to·produce·more·aesthetically·pleasing·output.</p>
50	<p>More·detailed·documentation·may·be·found·in·the·comments·in·the·package·spec.</p>	50	<p>More·detailed·documentation·may·be·found·in·the·comments·in·the·package·spec.</p>
51	</div>	51	</div>


Offset 10, 15 lines modified		Offset 10, 15 lines modified
10	····*·index	10	····*·index
11	····*·next·\|	11	····*·next·\|
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·9.·Paragraph·filling:·formatting·text	14	····*·9.·Paragraph·filling:·formatting·text
15	****·9.·Paragraph·filling:·formatting·textÂ¶·****	15	****·9.·Paragraph·filling:·formatting·textÂ¶·****
16	The·packageGNATCOLL.Paragraph_Fillingprovides·several·algorithms·for·filling	16	The·packageGNATCOLL.Paragraph_Fillingprovides·several·algorithms·for·filling
17	paragraphs~~---~~formatting·them·to·take·up·the·minimal·number·of·lines·and·to·look	17	paragraphsâformatting·them·to·take·up·the·minimal·number·of·lines·and·to·look
18	better.Knuth_Fillis·based·on·an·algorithm·invented·by·Donald·Knuth,·and·used·in	18	better.Knuth_Fillis·based·on·an·algorithm·invented·by·Donald·Knuth,·and·used·in
19	TeX.Pretty_Filluses·a·different·algorithm,·which·was·judged·by·some·to·produce	19	TeX.Pretty_Filluses·a·different·algorithm,·which·was·judged·by·some·to·produce
20	more·aesthetically·pleasing·output.	20	more·aesthetically·pleasing·output.
21	More·detailed·documentation·may·be·found·in·the·comments·in·the·package·spec.	21	More·detailed·documentation·may·be·found·in·the·comments·in·the·package·spec.
22	[Logo]	22	[Logo]
23	*·Previous·topic·*	23	*·Previous·topic·*
24	8._Boyer-Moore:_Searching_strings	24	8._Boyer-Moore:_Searching_strings


Offset 1, 13 lines modified		Offset 1, 13 lines modified
1	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./	1	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./
2	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/	2	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/
3	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/	3	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/
4	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/	4	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/
5	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/	5	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/
6	-rw-r--r--···0·root·········(0)·root·········(0)···326311·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/GNATColl.pdf.gz	6	-rw-r--r--···0·root·········(0)·root·········(0)···356019·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/GNATColl.pdf.gz
7	-rw-r--r--···0·root·········(0)·root·········(0)·····4344·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/changelog.Debian.gz	7	-rw-r--r--···0·root·········(0)·root·········(0)·····4344·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/changelog.Debian.gz
8	-rw-r--r--···0·root·········(0)·root·········(0)·····4838·2020-12-12·16:09:31.000000·./usr/share/doc/libgnatcoll-doc/copyright	8	-rw-r--r--···0·root·········(0)·root·········(0)·····4838·2020-12-12·16:09:31.000000·./usr/share/doc/libgnatcoll-doc/copyright
9	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/examples/	9	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/examples/
10	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/	10	drwxr-xr-x···0·root·········(0)·root·········(0)········0·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/
11	-rw-r--r--···0·root·········(0)·root·········(0)······993·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64-demo	11	-rw-r--r--···0·root·········(0)·root·········(0)······993·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64-demo
12	-rw-r--r--···0·root·········(0)·root·········(0)·····5238·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64_coder.adb	12	-rw-r--r--···0·root·········(0)·root·········(0)·····5238·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64_coder.adb
13	-rw-r--r--···0·root·········(0)·root·········(0)·······97·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64_coder.gpr	13	-rw-r--r--···0·root·········(0)·root·········(0)·······97·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/examples/coders/base64_coder.gpr
Offset 52, 67 lines modified		Offset 52, 67 lines modified
52	-rw-r--r--···0·root·········(0)·root·········(0)······894·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/html/_static/favicon.ico	52	-rw-r--r--···0·root·········(0)·root·········(0)······894·2020-05-22·09:28:15.000000·./usr/share/doc/libgnatcoll-doc/html/_static/favicon.ico
53	-rw-r--r--···0·root·········(0)·root·········(0)······286·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/file.png	53	-rw-r--r--···0·root·········(0)·root·········(0)······286·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/file.png
54	-rw-r--r--···0·root·········(0)·root·········(0)·······90·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/minus.png	54	-rw-r--r--···0·root·········(0)·root·········(0)·······90·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/minus.png
55	-rw-r--r--···0·root·········(0)·root·········(0)······120·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/navigation.png	55	-rw-r--r--···0·root·········(0)·root·········(0)······120·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/navigation.png
56	-rw-r--r--···0·root·········(0)·root·········(0)·······90·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/plus.png	56	-rw-r--r--···0·root·········(0)·root·········(0)·······90·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/plus.png
57	-rw-r--r--···0·root·········(0)·root·········(0)·····4780·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/pygments.css	57	-rw-r--r--···0·root·········(0)·root·········(0)·····4780·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/pygments.css
58	-rw-r--r--···0·root·········(0)·root·········(0)·····6236·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/sphinxdoc.css	58	-rw-r--r--···0·root·········(0)·root·········(0)·····6236·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/_static/sphinxdoc.css
59	-rw-r--r--···0·root·········(0)·root·········(0)·····8329·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/boyer_moore.html	59	-rw-r--r--···0·root·········(0)·root·········(0)·····8289·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/boyer_moore.html
60	-rw-r--r--···0·root·········(0)·root·········(0)·····9~~200~~·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/building.html	60	-rw-r--r--···0·root·········(0)·root·········(0)·····9198·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/building.html
61	-rw-r--r--···0·root·········(0)·root·········(0)····12020·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/config.html	61	-rw-r--r--···0·root·········(0)·root·········(0)····12018·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/config.html
62	-rw-r--r--···0·root·········(0)·root·········(0)····14976·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/email.html	62	-rw-r--r--···0·root·········(0)·root·········(0)····14978·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/email.html
63	-rw-r--r--···0·root·········(0)·root·········(0)·····5021·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/filling.html	63	-rw-r--r--···0·root·········(0)·root·········(0)·····5021·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/filling.html
64	-rw-r--r--···0·root·········(0)·root·········(0)····11369·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/genindex.html	64	-rw-r--r--···0·root·········(0)·root·········(0)····11369·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/genindex.html
65	-rw-r--r--···0·root·········(0)·root·········(0)·····8338·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/geometry.html	65	-rw-r--r--···0·root·········(0)·root·········(0)·····8338·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/geometry.html
66	-rw-r--r--···0·root·········(0)·root·········(0)····13869·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/index.html	66	-rw-r--r--···0·root·········(0)·root·········(0)····13869·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/index.html
67	-rw-r--r--···0·root·········(0)·root·········(0)·····5720·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/intro.html	67	-rw-r--r--···0·root·········(0)·root·········(0)·····5720·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/intro.html
68	-rw-r--r--···0·root·········(0)·root·········(0)····15148·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/json.html	68	-rw-r--r--···0·root·········(0)·root·········(0)····15138·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/json.html
69	-rw-r--r--···0·root·········(0)·root·········(0)····12353·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/memory.html	69	-rw-r--r--···0·root·········(0)·root·········(0)····12353·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/memory.html
70	-rw-r--r--···0·root·········(0)·root·········(0)····16047·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/mmap.html	70	-rw-r--r--···0·root·········(0)·root·········(0)····16055·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/mmap.html
71	-rw-r--r--···0·root·········(0)·root·········(0)·····1614·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/objects.inv	71	-rw-r--r--···0·root·········(0)·root·········(0)·····1614·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/objects.inv
72	-rw-r--r--···0·root·········(0)·root·········(0)·····6013·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/pools.html	72	-rw-r--r--···0·root·········(0)·root·········(0)·····6013·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/pools.html
73	-rw-r--r--···0·root·········(0)·root·········(0)····18091·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/projects.html	73	-rw-r--r--···0·root·········(0)·root·········(0)····18091·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/projects.html
74	-rw-r--r--···0·root·········(0)·root·········(0)·····4999·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/promises.html	74	-rw-r--r--···0·root·········(0)·root·········(0)·····4999·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/promises.html
75	-rw-r--r--···0·root·········(0)·root·········(0)·····7200·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/ravenscar.html	75	-rw-r--r--···0·root·········(0)·root·········(0)·····7200·2020-12-22·09:58:09.000000·./usr/share/doc/libgnatcoll-doc/html/ravenscar.html


Offset 41, 15 lines modified		Offset 41, 15 lines modified
41	··········<div·class="body"·role="main">	41	··········<div·class="body"·role="main">
42	············	42	············
43	··<div·class="section"·id="geometry-primitive-geometric-operations">	43	··<div·class="section"·id="geometry-primitive-geometric-operations">
44	<h1><span·class="section-number">16.·</span><strong>Geometry</strong>:·primitive·geometric·operations<a·class="headerlink"·href="#geometry-primitive-geometric-operations"·title="Permalink·to·this·headline">¶</a></h1>	44	<h1><span·class="section-number">16.·</span><strong>Geometry</strong>:·primitive·geometric·operations<a·class="headerlink"·href="#geometry-primitive-geometric-operations"·title="Permalink·to·this·headline">¶</a></h1>
45	<p>GNATColl·provides·the·package·<cite>GNATCOLL.Geometry</cite>.·This	45	<p>GNATColl·provides·the·package·<cite>GNATCOLL.Geometry</cite>.·This
46	package·includes·a·number·of·primitive·operations·on·geometric·figures	46	package·includes·a·number·of·primitive·operations·on·geometric·figures
47	like·points,·segments,·lines,·circles,·rectangles·and·polygons.	47	like·points,·segments,·lines,·circles,·rectangles·and·polygons.
48	In·particular,·you·can·compute·their·intersections,·the·distances,...</p>	48	In·particular,·you·can·compute·their·intersections,·the·distances,…</p>
49	<p>This·package·is·generic,·so·that·you·can·specify·the·type·of·coordinates	49	<p>This·package·is·generic,·so·that·you·can·specify·the·type·of·coordinates
50	you·wish·to·handle:</p>	50	you·wish·to·handle:</p>
51	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>	51	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>
52	···<span·class="kd">package</span>·<span·class="nc">Float_Geometry</span>·<span·class="kr">is·new</span>·<span·class="nc">GNATCOLL.Geometry</span>·<span·class="p">(</span>Float<span·class="p">);</span>	52	···<span·class="kd">package</span>·<span·class="nc">Float_Geometry</span>·<span·class="kr">is·new</span>·<span·class="nc">GNATCOLL.Geometry</span>·<span·class="p">(</span>Float<span·class="p">);</span>
53	···<span·class="kn">use</span>·<span·class="nn">Float_Geometry</span><span·class="p">;</span>	53	···<span·class="kn">use</span>·<span·class="nn">Float_Geometry</span><span·class="p">;</span>

54	···<span·class="no">P1</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Point</span>·<span·class="p">:=</span>·<span·class="p">(</span><span·class="mf">1.0</span><span·class="p">,</span>·<span·class="mf">1.0</span><span·class="p">);</span>	54	···<span·class="no">P1</span>·<span·class="p">:</span>·<span·class="kr">constant</span>·<span·class="n">Point</span>·<span·class="p">:=</span>·<span·class="p">(</span><span·class="mf">1.0</span><span·class="p">,</span>·<span·class="mf">1.0</span><span·class="p">);</span>


Offset 12, 15 lines modified		Offset 12, 15 lines modified
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·16.·Geometry:·primitive·geometric·operations	14	····*·16.·Geometry:·primitive·geometric·operations
15	****·16.·Geometry:·primitive·geometric·operationsÂ¶·****	15	****·16.·Geometry:·primitive·geometric·operationsÂ¶·****
16	GNATColl·provides·the·packageGNATCOLL.Geometry.·This·package·includes·a·number	16	GNATColl·provides·the·packageGNATCOLL.Geometry.·This·package·includes·a·number
17	of·primitive·operations·on·geometric·figures·like·points,·segments,·lines,	17	of·primitive·operations·on·geometric·figures·like·points,·segments,·lines,
18	circles,·rectangles·and·polygons.·In·particular,·you·can·compute·their	18	circles,·rectangles·and·polygons.·In·particular,·you·can·compute·their
19	intersections,·the·distances,~~...~~	19	intersections,·the·distances,â¦
20	This·package·is·generic,·so·that·you·can·specify·the·type·of·coordinates·you	20	This·package·is·generic,·so·that·you·can·specify·the·type·of·coordinates·you
21	wish·to·handle:	21	wish·to·handle:
22	declare	22	declare
23	···package·Float_Geometry·is·new·GNATCOLL.Geometry·(Float);	23	···package·Float_Geometry·is·new·GNATCOLL.Geometry·(Float);
24	···use·Float_Geometry;	24	···use·Float_Geometry;

25	···P1·:·constant·Point·:=·(1.0,·1.0);	25	···P1·:·constant·Point·:=·(1.0,·1.0);


Offset 11, 15 lines modified		Offset 11, 15 lines modified
11	····*·next·\|	11	····*·next·\|
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·21.·JSON:·handling·JSON·data	14	····*·21.·JSON:·handling·JSON·data
15	****·21.·JSON:·handling·JSON·dataÂ¶·****	15	****·21.·JSON:·handling·JSON·dataÂ¶·****
16	JSON·is·a·format·often·used·on·the·web·to·communicate·between·a·server·and·a	16	JSON·is·a·format·often·used·on·the·web·to·communicate·between·a·server·and·a
17	browser,·or·between·servers.·It·plays·a·similar·role·to·XML,·but·it·has·a·much	17	browser,·or·between·servers.·It·plays·a·similar·role·to·XML,·but·it·has·a·much
18	lighter·syntax.·On·the·other·hand,·it·doesn't·provide·advanced·features·like	18	lighter·syntax.·On·the·other·hand,·it·doesnât·provide·advanced·features·like
19	validation,·which·XML·provides.	19	validation,·which·XML·provides.
20	The·GNATCOLL.JSON·package·provides·an·Ada·API·to·decode·JSON·data·from·strings	20	The·GNATCOLL.JSON·package·provides·an·Ada·API·to·decode·JSON·data·from·strings
21	and·to·encode·that·data·back·to·strings.·It·also·allows·one·to·create·and	21	and·to·encode·that·data·back·to·strings.·It·also·allows·one·to·create·and
22	modify·JSON·data.	22	modify·JSON·data.
23	***·21.1.·API·overviewÂ¶·***	23	***·21.1.·API·overviewÂ¶·***
24	The·entry·point·for·this·API·is·the·JSON_Value·data·type.·JSON·values·can·be	24	The·entry·point·for·this·API·is·the·JSON_Value·data·type.·JSON·values·can·be
25	any·of:	25	any·of:
Offset 65, 17 lines modified		Offset 65, 17 lines modified
65	···My_Obj.Set_Field·("field1",·Create·(1));	65	···My_Obj.Set_Field·("field1",·Create·(1));
66	···My_Obj.Set_Field·("name",·"theName");	66	···My_Obj.Set_Field·("name",·"theName");

67	···--··Now·serialize·it.·The·call·below·will·display:	67	···--··Now·serialize·it.·The·call·below·will·display:
68	···--····{"field1":·1,·"name":·"thename"}	68	···--····{"field1":·1,·"name":·"thename"}
69	···Put_Line·(My_Obj.Write);	69	···Put_Line·(My_Obj.Write);
70	end·JSON_Test;	70	end·JSON_Test;
71	The·above·uses·the·Ada·2005·"dot·notation"·to·call·primitive·operations	71	The·above·uses·the·Ada·2005·âdot·notationâ·to·call·primitive·operations
72	(.Set_Field,·.Write),·but·naturally·the·more·traditional·"prefix·notation"~~·is~~	72	(.Set_Field,·.Write),·but·naturally·the·more·traditional·âprefix·notationâ
73	also·available:	73	is·also·available:
74	Set_Field·(My_Obj,·"field1",·Create·(1));	74	Set_Field·(My_Obj,·"field1",·Create·(1));
75	It·is·also·possible·to·create·JSON·arrays.·These·are·not·tagged·types,·so·the	75	It·is·also·possible·to·create·JSON·arrays.·These·are·not·tagged·types,·so·the
76	prefix·notation·has·to·be·used.·Here·is·a·further·example·that·sets·another	76	prefix·notation·has·to·be·used.·Here·is·a·further·example·that·sets·another
77	field·in·the·object·we·had·before·(My_Obj):	77	field·in·the·object·we·had·before·(My_Obj):
78	declare	78	declare
79	···--··Create·a·JSON·array	79	···--··Create·a·JSON·array
80	···My_Arr·:·JSON_Array·:=·Empty_Array;	80	···My_Arr·:·JSON_Array·:=·Empty_Array;


Offset 65, 29 lines modified		Offset 65, 29 lines modified
65	by·the·system.·To·modify·the·file,·you·just·modify·the·contents·of·the	65	by·the·system.·To·modify·the·file,·you·just·modify·the·contents·of·the
66	memory,·and·do·not·worry·about·writing·the·file·back·to·the·disk.</p>	66	memory,·and·do·not·worry·about·writing·the·file·back·to·the·disk.</p>
67	<p>When·your·application·does·not·need·to·read·the·whole·contents·of·the·file,	67	<p>When·your·application·does·not·need·to·read·the·whole·contents·of·the·file,
68	the·speed·up·can·be·several·orders·of·magnitude·faster·than·<cite>read()</cite>.	68	the·speed·up·can·be·several·orders·of·magnitude·faster·than·<cite>read()</cite>.
69	Even·when·you·need·to·read·the·whole·contents,·using·<cite>mmap()</cite>·is	69	Even·when·you·need·to·read·the·whole·contents,·using·<cite>mmap()</cite>·is
70	still·two·or·three·times·faster,·which·is·especially·interesting·on·big	70	still·two·or·three·times·faster,·which·is·especially·interesting·on·big
71	files.</p>	71	files.</p>
72	<p>GNATColl's·<cite>GNATCOLL.Mmap</cite>·package·provides·a·high-level·abstraction	72	<p>GNATColl’s·<cite>GNATCOLL.Mmap</cite>·package·provides·a·high-level·abstraction
73	on·top·of·the·<cite>mmap</cite>·system·call.·As·for·most·other·packages·in	73	on·top·of·the·<cite>mmap</cite>·system·call.·As·for·most·other·packages·in
74	GNATColl,·it·also·nicely·handles·the·case·where·your·system·does·not	74	GNATColl,·it·also·nicely·handles·the·case·where·your·system·does·not
75	actually·support·<cite>mmap</cite>,·and·will·in·that·case·fallback·on·using	75	actually·support·<cite>mmap</cite>,·and·will·in·that·case·fallback·on·using
76	<cite>read</cite>·and·<cite>write</cite>·transparently.·In·such·a·case,·your·application	76	<cite>read</cite>·and·<cite>write</cite>·transparently.·In·such·a·case,·your·application
77	will·perform·a·little·slower,·but·you·do·not·have·to·modify·your·code·to	77	will·perform·a·little·slower,·but·you·do·not·have·to·modify·your·code·to
78	adapt·it·to·the·new·system.</p>	78	adapt·it·to·the·new·system.</p>
79	<p>Due·to·the·low-level·C·API·that·is·needed·underneath,·the·various·subprograms	79	<p>Due·to·the·low-level·C·API·that·is·needed·underneath,·the·various·subprograms
80	in·this·package·do·not·directly·manipulate·Ada·strings·with·valid·bounds.	80	in·this·package·do·not·directly·manipulate·Ada·strings·with·valid·bounds.
81	Instead,·a·new·type·<cite>Str_Access</cite>·was·defined.·It·does·not·contain·the	81	Instead,·a·new·type·<cite>Str_Access</cite>·was·defined.·It·does·not·contain·the
82	bounds·of·the·string,·and·therefore·you·cannot·use·the·usual	82	bounds·of·the·string,·and·therefore·you·cannot·use·the·usual
83	<cite>'First</cite>·and·<cite>'Last</cite>·attributes·on·that·string.·But·there·are·other	83	<cite>‘First</cite>·and·<cite>‘Last</cite>·attributes·on·that·string.·But·there·are·other
84	subprograms·that·provide·those·values.</p>	84	subprograms·that·provide·those·values.</p>
85	<p>Here·is·how·to·read·a·whole·file·at·once.·This·is·what·your·code·will·use	85	<p>Here·is·how·to·read·a·whole·file·at·once.·This·is·what·your·code·will·use
86	in·most·cases,·unless·you·expect·to·read·files·bigger·than·<cite>Integer'Last</cite>	86	in·most·cases,·unless·you·expect·to·read·files·bigger·than·<cite>Integer’Last</cite>
87	bytes·long.·In·such·cases·you·need·to·read·chunks·of·the·file·separately.	87	bytes·long.·In·such·cases·you·need·to·read·chunks·of·the·file·separately.
88	The·<cite>mmap</cite>·system·call·is·such·that·its·performance·does·not·depend·on	88	The·<cite>mmap</cite>·system·call·is·such·that·its·performance·does·not·depend·on
89	the·size·of·the·file·your·are·mapping.·Of·course,·this·could·be·a·problem·if	89	the·size·of·the·file·your·are·mapping.·Of·course,·this·could·be·a·problem·if
90	<cite>GNATCOLL.Mmap</cite>·falls·back·on·calling·<cite>read</cite>,·since·in·that·case·it	90	<cite>GNATCOLL.Mmap</cite>·falls·back·on·calling·<cite>read</cite>,·since·in·that·case·it
91	needs·to·allocate·as·much·memory·as·your·file.·Therefore·in·some·cases·you	91	needs·to·allocate·as·much·memory·as·your·file.·Therefore·in·some·cases·you
92	will·also·want·to·only·read·chunks·of·the·file·at·once:</p>	92	will·also·want·to·only·read·chunks·of·the·file·at·once:</p>
93	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>	93	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>


Offset 34, 33 lines modified		Offset 34, 33 lines modified
34	actual·contents·is·temporarily·mapped·in·memory·by·the·system.·To·modify·the	34	actual·contents·is·temporarily·mapped·in·memory·by·the·system.·To·modify·the
35	file,·you·just·modify·the·contents·of·the·memory,·and·do·not·worry·about	35	file,·you·just·modify·the·contents·of·the·memory,·and·do·not·worry·about
36	writing·the·file·back·to·the·disk.	36	writing·the·file·back·to·the·disk.
37	When·your·application·does·not·need·to·read·the·whole·contents·of·the·file,·the	37	When·your·application·does·not·need·to·read·the·whole·contents·of·the·file,·the
38	speed·up·can·be·several·orders·of·magnitude·faster·thanread().·Even·when·you	38	speed·up·can·be·several·orders·of·magnitude·faster·thanread().·Even·when·you
39	need·to·read·the·whole·contents,·usingmmap()is·still·two·or·three·times·faster,	39	need·to·read·the·whole·contents,·usingmmap()is·still·two·or·three·times·faster,
40	which·is·especially·interesting·on·big·files.	40	which·is·especially·interesting·on·big·files.
41	GNATColl'sGNATCOLL.Mmappackage·provides·a·high-level·abstraction·on·top·of	41	GNATCollâsGNATCOLL.Mmappackage·provides·a·high-level·abstraction·on·top·of
42	themmapsystem·call.·As·for·most·other·packages·in·GNATColl,·it·also·nicely	42	themmapsystem·call.·As·for·most·other·packages·in·GNATColl,·it·also·nicely
43	handles·the·case·where·your·system·does·not·actually·supportmmap,·and·will·in	43	handles·the·case·where·your·system·does·not·actually·supportmmap,·and·will·in
44	that·case·fallback·on·usingreadandwritetransparently.·In·such·a·case,·your	44	that·case·fallback·on·usingreadandwritetransparently.·In·such·a·case,·your
45	application·will·perform·a·little·slower,·but·you·do·not·have·to·modify·your	45	application·will·perform·a·little·slower,·but·you·do·not·have·to·modify·your
46	code·to·adapt·it·to·the·new·system.	46	code·to·adapt·it·to·the·new·system.
47	Due·to·the·low-level·C·API·that·is·needed·underneath,·the·various·subprograms	47	Due·to·the·low-level·C·API·that·is·needed·underneath,·the·various·subprograms
48	in·this·package·do·not·directly·manipulate·Ada·strings·with·valid·bounds.	48	in·this·package·do·not·directly·manipulate·Ada·strings·with·valid·bounds.
49	Instead,·a·new·typeStr_Accesswas·defined.·It·does·not·contain·the·bounds·of·the	49	Instead,·a·new·typeStr_Accesswas·defined.·It·does·not·contain·the·bounds·of·the
50	string,·and·therefore·you·cannot·use·the·usual'Firstand'Lastattributes·on~~·that~~	50	string,·and·therefore·you·cannot·use·the·usualâFirstandâLastattributes·on
51	string.·But·there·are·other·subprograms·that·provide·those·values.	51	that·string.·But·there·are·other·subprograms·that·provide·those·values.
52	Here·is·how·to·read·a·whole·file·at·once.·This·is·what·your·code·will·use·in	52	Here·is·how·to·read·a·whole·file·at·once.·This·is·what·your·code·will·use·in
53	most·cases,·unless·you·expect·to·read·files·bigger·thanInteger'Lastbytes~~·long.~~	53	most·cases,·unless·you·expect·to·read·files·bigger·thanIntegerâLastbytes
54	In·such·cases·you·need·to·read·chunks·of·the·file·separately.~~·Themmapsystem~~	54	long.·In·such·cases·you·need·to·read·chunks·of·the·file·separately.
55	call·is·such·that·its·performance·does·not·depend·on·the·size·o~~f·the·~~f~~ile·your~~	55	Themmapsystem·call·is·such·that·its·performance·does·not·depend·on·the·size·of
56	are·mapping.·Of·course,·this·could·be·a·problem·ifGNATCOLL.Mmapfalls·back·on
57	callingread,·since·in·that·case·it·needs·to·allocate·as·much·memory·as·your
58	file.·Therefore·in·some·cases·you·will·also·want·to·only·read·chunks·of·the
59	file·at·once:	56	the·file·your·are·mapping.·Of·course,·this·could·be·a·problem
		57	ifGNATCOLL.Mmapfalls·back·on·callingread,·since·in·that·case·it·needs·to
		58	allocate·as·much·memory·as·your·file.·Therefore·in·some·cases·you·will·also
		59	want·to·only·read·chunks·of·the·file·at·once:
60	declare	60	declare
61	···File·:·Mapped_File;	61	···File·:·Mapped_File;
62	···Reg··:·Mapped_Region;	62	···Reg··:·Mapped_Region;
63	···Str··:·Long.Str_Access;	63	···Str··:·Long.Str_Access;
64	begin	64	begin
65	···File·:=·Open_Read·("/tmp/file_on_disk");	65	···File·:=·Open_Read·("/tmp/file_on_disk");
66	···Reg·:=·Read·(File);··--··map·the·whole·file	66	···Reg·:=·Read·(File);··--··map·the·whole·file


Offset 117, 15 lines modified		Offset 117, 15 lines modified

117	<span·class="kd">type</span>·<span·class="kt">My_Type</span>·<span·class="kr">is</span>·<span·class="kr">new</span>·<span·class="n">Weak_Refcounted</span>·<span·class="kr">with</span><span·class="p">...;</span>	117	<span·class="kd">type</span>·<span·class="kt">My_Type</span>·<span·class="kr">is</span>·<span·class="kr">new</span>·<span·class="n">Weak_Refcounted</span>·<span·class="kr">with</span><span·class="p">...;</span>

118	<span·class="kd">package</span>·<span·class="nc">Pointers</span>·<span·class="kr">is·new</span>·<span·class="nc">Weakref_Pointers</span>·<span·class="p">(</span>My_Type<span·class="p">);</span>	118	<span·class="kd">package</span>·<span·class="nc">Pointers</span>·<span·class="kr">is·new</span>·<span·class="nc">Weakref_Pointers</span>·<span·class="p">(</span>My_Type<span·class="p">);</span>
119	</pre></div>	119	</pre></div>
120	</div>	120	</div>
121	<p>The·above·code·can·be·used·instead·of·the·code·in·the·first·example,·and	121	<p>The·above·code·can·be·used·instead·of·the·code·in·the·first·example,·and
122	provides·the·same·capability·(smart·pointers,·reference·counted·types,...).	122	provides·the·same·capability·(smart·pointers,·reference·counted·types,…).
123	However,·the·type·<cite>My_Type</cite>·is·slightly·bigger,·but·can·be·used·to	123	However,·the·type·<cite>My_Type</cite>·is·slightly·bigger,·but·can·be·used·to
124	create·weak·references:</p>	124	create·weak·references:</p>
125	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="n">WR</span>·<span·class="p">:</span>·<span·class="n">Weak_Ref</span><span·class="p">;</span>	125	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="n">WR</span>·<span·class="p">:</span>·<span·class="n">Weak_Ref</span><span·class="p">;</span>

126	<span·class="kr">declare</span>	126	<span·class="kr">declare</span>
127	···<span·class="n">R</span>···<span·class="p">:</span>·<span·class="n">Ref</span><span·class="p">;</span>	127	···<span·class="n">R</span>···<span·class="p">:</span>·<span·class="n">Ref</span><span·class="p">;</span>
128	···<span·class="n">Tmp</span>·<span·class="p">:</span>·<span·class="n">My_Type</span>·<span·class="p">:=</span>·<span·class="p">...;</span>	128	···<span·class="n">Tmp</span>·<span·class="p">:</span>·<span·class="n">My_Type</span>·<span·class="p">:=</span>·<span·class="p">...;</span>


Offset 78, 15 lines modified		Offset 78, 15 lines modified
78	with·GNATCOLL.Refcount.Weakref;	78	with·GNATCOLL.Refcount.Weakref;
79	use·GNATCOLL.Refcount.Weakref;	79	use·GNATCOLL.Refcount.Weakref;

80	type·My_Type·is·new·Weak_Refcounted·with...;	80	type·My_Type·is·new·Weak_Refcounted·with...;

81	package·Pointers·is·new·Weakref_Pointers·(My_Type);	81	package·Pointers·is·new·Weakref_Pointers·(My_Type);
82	The·above·code·can·be·used·instead·of·the·code·in·the·first·example,·and	82	The·above·code·can·be·used·instead·of·the·code·in·the·first·example,·and
83	provides·the·same·capability·(smart·pointers,·reference·counted·types,~~...~~).	83	provides·the·same·capability·(smart·pointers,·reference·counted·types,â¦).
84	However,·the·typeMy_Typeis·slightly·bigger,·but·can·be·used·to·create·weak	84	However,·the·typeMy_Typeis·slightly·bigger,·but·can·be·used·to·create·weak
85	references:	85	references:
86	WR·:·Weak_Ref;	86	WR·:·Weak_Ref;

87	declare	87	declare
88	···R···:·Ref;	88	···R···:·Ref;
89	···Tmp·:·My_Type·:=·...;	89	···Tmp·:·My_Type·:=·...;


Offset 13, 20 lines modified		Offset 13, 20 lines modified
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·3.·Scripts:·Embedding·script·languages	14	····*·3.·Scripts:·Embedding·script·languages
15	****·3.·Scripts:·Embedding·script·languagesÂ¶·****	15	****·3.·Scripts:·Embedding·script·languagesÂ¶·****
16	In·a·lot·of·contexts,·you·want·to·give·the·possibility·to·users·to·extend·your	16	In·a·lot·of·contexts,·you·want·to·give·the·possibility·to·users·to·extend·your
17	application.·This·can·be·done·in·several·ways:·define·an·Ada·API·from·which	17	application.·This·can·be·done·in·several·ways:·define·an·Ada·API·from·which
18	they·can·build·dynamically·loadable·modules,·provide·the·whole·source·code·to	18	they·can·build·dynamically·loadable·modules,·provide·the·whole·source·code·to
19	your·application·and·let·users·recompile·it,·interface·with·a·simpler·scripting	19	your·application·and·let·users·recompile·it,·interface·with·a·simpler·scripting
20	languages,~~...~~	20	languages,â¦
21	Dynamically·loadable·modules·can·be·loaded·on·demand,·as·their·name·indicate.	21	Dynamically·loadable·modules·can·be·loaded·on·demand,·as·their·name·indicate.
22	However,·they·generally·require·a·relatively·complex·environment·to·build,·and	22	However,·they·generally·require·a·relatively·complex·environment·to·build,·and
23	are·somewhat·less·portable.·But·when·your·users·are·familiar·with·Ada,·they	23	are·somewhat·less·portable.·But·when·your·users·are·familiar·with·Ada,·they
24	provide·a·programming·environment·in·which·they·are·comfortable.·As·usual,	24	provide·a·programming·environment·in·which·they·are·comfortable.·As·usual,
25	changing·the·module·requires·recompilation,·re-installation,~~...~~	25	changing·the·module·requires·recompilation,·re-installation,â¦
26	Providing·the·source·code·to·your·application·is·generally·even·more·complex	26	Providing·the·source·code·to·your·application·is·generally·even·more·complex
27	for·users.·This·requires·an·even·more·complex·setup,·your·application·is	27	for·users.·This·requires·an·even·more·complex·setup,·your·application·is
28	generally·too·big·for·users·to·dive·into,·and·modifications·done·by·one·users	28	generally·too·big·for·users·to·dive·into,·and·modifications·done·by·one·users
29	are·hard·to·provide·to·other·users,·or·will·be·lost·when·you·distribute·a·new	29	are·hard·to·provide·to·other·users,·or·will·be·lost·when·you·distribute·a·new
30	version·of·your·application.	30	version·of·your·application.
31	The·third·solution·is·to·embed·one·or·more·scripting·languages·in·your	31	The·third·solution·is·to·embed·one·or·more·scripting·languages·in·your
32	application,·and·export·some·functions·to·it.·This·often·requires·your·users·to	32	application,·and·export·some·functions·to·it.·This·often·requires·your·users·to
Offset 35, 83 lines modified		Offset 35, 84 lines modified
35	The·resulting·scripts·can·easily·be·redistributed·to·other·users·or·even	35	The·resulting·scripts·can·easily·be·redistributed·to·other·users·or·even
36	distributed·with·future·versions·of·your·application.	36	distributed·with·future·versions·of·your·application.
37	The·module·in·GNATColl·helps·you·implement·the·third·solution.·It·was·used	37	The·module·in·GNATColl·helps·you·implement·the·third·solution.·It·was·used
38	extensively·in·the·GPS·programming·environment·for·its·python·interface.	38	extensively·in·the·GPS·programming·environment·for·its·python·interface.
39	[TIP:]·Each·of·the·scripting·language·is·optional	39	[TIP:]·Each·of·the·scripting·language·is·optional
40	This·module·can·be·compiled·with·any·of·these·languages·as·an·optional	40	This·module·can·be·compiled·with·any·of·these·languages·as·an·optional
41	dependency·(except·for·the·shell·language,·which·is·always·built-in,·but·is	41	dependency·(except·for·the·shell·language,·which·is·always·built-in,·but·is
42	extremely·minimal,·and·doesn't·have·to·be·loaded·at·run·time·anyway).·If·the	42	extremely·minimal,·and·doesnât·have·to·be·loaded·at·run·time·anyway).·If·the
43	necessary·libraries·are·found·on·the·system,·GNATColl·will·be·build·with	43	necessary·libraries·are·found·on·the·system,·GNATColl·will·be·build·with
44	support·for·the·corresponding·language,·but·your·application·can·chose·at·run	44	support·for·the·corresponding·language,·but·your·application·can·chose·at·run
45	time·whether·or·not·to·activate·the·support·for·a·specific·language.	45	time·whether·or·not·to·activate·the·support·for·a·specific·language.
46	[TIP:]·Use·a·scripting·language·to·provide·an·automatic·testing·framework·for	46	[TIP:]·Use·a·scripting·language·to·provide·an·automatic·testing·framework·for
47	your·application.	47	your·application.
48	The·GPS·environment·uses·python·command·for·its·automatic·test·suite,·including	48	The·GPS·environment·uses·python·command·for·its·automatic·test·suite,·including
49	graphical·tests·such·as·pressing·on·a·button,·selecting·a·menu,~~...~~	49	graphical·tests·such·as·pressing·on·a·button,·selecting·a·menu,â¦
50	***·3.1.·Supported·languagesÂ¶·***	50	***·3.1.·Supported·languagesÂ¶·***
51	The·module·provides·built-in·support·for·several·scripting·languages,·and·other	51	The·module·provides·built-in·support·for·several·scripting·languages,·and·other
52	languages·can·"easily"·be·added.·Your·application·does·not·change·when·new	52	languages·can·âeasilyâ·be·added.·Your·application·does·not·change·when·new
53	languages·are·added,·since·the·interface·to·export·subprograms·and·classes·to	53	languages·are·added,·since·the·interface·to·export·subprograms·and·classes·to
54	the·scripting·languages·is·language-neutral,·and·will·automatically·export·to	54	the·scripting·languages·is·language-neutral,·and·will·automatically·export·to
55	all·known·scripting·languages.	55	all·known·scripting·languages.
56	The·Core·component·provides·support·for·the·following·language:	56	The·Core·component·provides·support·for·the·following·language:
57	··Shell	57	··Shell
58	······This·is·a·very·simple-minded·scripting·language,·which·doesn't·provide	58	······This·is·a·very·simple-minded·scripting·language,·which·doesnât·provide
59	······flow-control·instructions·(The_Shell_language).	59	······flow-control·instructions·(The_Shell_language).
60	Optional·components·add·support·for·other·languages,·e.g.·Python.·Please·refer	60	Optional·components·add·support·for·other·languages,·e.g.·Python.·Please·refer
61	to·the·corresponding·component's·documentation.	61	to·the·corresponding·componentâs·documentation.
62	**·3.1.1.·The·Shell·languageÂ¶·**	62	**·3.1.1.·The·Shell·languageÂ¶·**
63	The·shell·language·was·initially·developed·in·the·context·of·the·GPS	63	The·shell·language·was·initially·developed·in·the·context·of·the·GPS
64	programming·environment,·as·a·way·to·embed·scripting·commands·in·XML	64	programming·environment,·as·a·way·to·embed·scripting·commands·in·XML
65	configuration·files.	65	configuration·files.
66	In·this·language,·you·can·execute·any·of·the·commands·exported·by·the	66	In·this·language,·you·can·execute·any·of·the·commands·exported·by·the
67	application,·passing·any·number·of·arguments·they·need.·Arguments·to·function	67	application,·passing·any·number·of·arguments·they·need.·Arguments·to·function
68	calls·can,·but·need·not,·be·quoted.·Quoting·is·only·mandatory·when·they·contain	68	calls·can,·but·need·not,·be·quoted.·Quoting·is·only·mandatory·when·they·contain
69	spaces,·newline·characters,·or·double-quotes·(~~'"'~~).·To·quote·an·argument,	69	spaces,·newline·characters,·or·double-quotes·(âââ).·To·quote·an·argument,
70	surround·it·by·double-quotes,·and·precede·each·double-quote·it·contains·by·a	70	surround·it·by·double-quotes,·and·precede·each·double-quote·it·contains·by·a
71	backslash·character.·Another·way·of·quoting·is·similar·to·what·python·provides,	71	backslash·character.·Another·way·of·quoting·is·similar·to·what·python·provides,
72	which·is·to·triple-quote·the·argument,·i.e.·surround·it·by·'~~"""'·on·each·side.~~	72	which·is·to·triple-quote·the·argument,·i.e.·surround·it·by·âââââ·on
73	In·such·a·case,·any·special·character·(in·particular·other·double-~~quotes·or~~	73	each·side.·In·such·a·case,·any·special·character·(in·particular·other·double-
74	backslashes)·lose·their·special·meaning·and·are·just·taken·as·part·of~~·the~~	74	quotes·or·backslashes)·lose·their·special·meaning·and·are·just·taken·as·part·of
75	argument.·This·is·in·particular·useful·when·you·do·not·know·in·advance·the	75	the·argument.·This·is·in·particular·useful·when·you·do·not·know·in·advance·the
76	contents·of·the·argument·you·are·quoting:	76	contents·of·the·argument·you·are·quoting:
77	Shell>·function_name·arg1·"arg·2"·"""arg·3"""	77	Shell>·function_name·arg1·"arg·2"·"""arg·3"""
78	Commands·are·executed·as·if·on·a·stack·machine:·the·result·of·a·command·is	78	Commands·are·executed·as·if·on·a·stack·machine:·the·result·of·a·command·is
79	pushed·on·the·stack,·and·later·commands·can·reference·it·using%following·by·a	79	pushed·on·the·stack,·and·later·commands·can·reference·it·using%following·by·a
80	number.·By·default,·the·number·of·previous·results·that·are·kept·is·set·to·9,	80	number.·By·default,·the·number·of·previous·results·that·are·kept·is·set·to·9,
81	and·this·can·only·be·changed·by·modifying·the·source·code·for·GNATColl.·The	81	and·this·can·only·be·changed·by·modifying·the·source·code·for·GNATColl.·The
82	return·values·are·also·modified·by·commands·executed·internally·by·your	82	return·values·are·also·modified·by·commands·executed·internally·by·your
83	application,·and·that·might·have·no·visible·output·from·the·user's·point·of	83	application,·and·that·might·have·no·visible·output·from·the·userâs·point·of
84	view.·As·a·result,·you·should·never·assume·you·know·what%1,~~...~~·contain·unless	84	view.·As·a·result,·you·should·never·assume·you·know·what%1,â¦·contain·unless
85	you·just·executed·a·command·in·the·same·script:	85	you·just·executed·a·command·in·the·same·script:
86	Shell>·function_name·arg1	86	Shell>·function_name·arg1
87	Shell>·function2_name·%1	87	Shell>·function2_name·%1
88	In·particular,·the%1syntax·is·used·when·emulating·object-oriented·programming	88	In·particular,·the%1syntax·is·used·when·emulating·object-oriented·programming
89	in·the·shell.·A·method·of·a·class·is·just·a·particular·function·that·contains·a	89	in·the·shell.·A·method·of·a·class·is·just·a·particular·function·that·contains·a
90	'.'·in·its·name,·and·whose·first·implicit·argument·is·the·instance·on·which~~·it~~	90	â.â·in·its·name,·and·whose·first·implicit·argument·is·the·instance·on·which
91	applies.·This·instance·is·generally·the·result·of·calling·a·constructor·i~~n·a~~n	91	it·applies.·This·instance·is·generally·the·result·of·calling·a·constructor·in
92	earlier·call.·Assuming,·for·instance,·that·we·have·exported·a·class~~·"Ba~~s~~e"·to~~	92	an·earlier·call.·Assuming,·for·instance,·that·we·have·exported·a·class
93	the·shell·from·our·Ada·core,·we·could·use·the·following·code:	93	âBaseâ·to·the·shell·from·our·Ada·core,·we·could·use·the·following·code:
94	Shell>·Base·arg1·arg2	94	Shell>·Base·arg1·arg2
95	Shell>·Base.method·%1·arg1·arg2	95	Shell>·Base.method·%1·arg1·arg2
96	to·create·an·instance·and·call·one·of·its·methods.·Of·course,·the·shell·is·not	96	to·create·an·instance·and·call·one·of·its·methods.·Of·course,·the·shell·is·not
97	the·best·language·for·object-oriented·programming,·and·better·languages·should	97	the·best·language·for·object-oriented·programming,·and·better·languages·should
98	be·used·instead.	98	be·used·instead.
99	When·an·instance·has·associated·properties·(which·you·can·export·from·Ada	99	When·an·instance·has·associated·properties·(which·you·can·export·from·Ada
100	usingSet_Property),·you·access·the·properties·by·prefixing·its·name·with~~·"@":~~	100	usingSet_Property),·you·access·the·properties·by·prefixing·its·name·with
		101	â@â:
101	Shell>·Base·arg1·arg2···#·Build·new·instance	102	Shell>·Base·arg1·arg2···#·Build·new·instance
102	Shell>·@id·%1···········#·Access·its·"id"·field	103	Shell>·@id·%1···········#·Access·its·"id"·field
103	Shell>·@id·%1·5·········#·Set·its·"id"·field	104	Shell>·@id·%1·5·········#·Set·its·"id"·field
104	Some·commands·are·automatically·added·to·the·shell·when·this·scripting·language	105	Some·commands·are·automatically·added·to·the·shell·when·this·scripting·language
105	is·added·to·the·application.·These·are	106	is·added·to·the·application.·These·are
106	··Function·load·(file)	107	··Function·load·(file)
107	······Loads·the·content·offilefrom·the·disk,·and·execute·each·of·its·lines·as·a	108	······Loads·the·content·offilefrom·the·disk,·and·execute·each·of·its·lines·as·a
108	······Shell·command.·This·can·for·instance·be·used·to·load·scripts·when·your	109	······Shell·command.·This·can·for·instance·be·used·to·load·scripts·when·your
109	······application·is·loaded	110	······application·is·loaded
110	··Function·echo·(arg~~...~~)	111	··Function·echo·(argâ¦)
111	······This·function·takes·any·number·of·argument,·and·prints·them·in·the	112	······This·function·takes·any·number·of·argument,·and·prints·them·in·the
112	······console·associated·with·the·language.·By·default,·when·in·an·interactive	113	······console·associated·with·the·language.·By·default,·when·in·an·interactive
113	······console,·the·output·of·commands·is·automatically·printed·to·the·console.	114	······console,·the·output·of·commands·is·automatically·printed·to·the·console.
114	······But·when·you·execute·a·script·throughloadabove,·you·need·to·explicitly	115	······But·when·you·execute·a·script·throughloadabove,·you·need·to·explicitly
115	······callechoto·make·some·output·visible.	116	······callechoto·make·some·output·visible.
116	··Function·clear_cache	117	··Function·clear_cache
117	······This·frees·the·memory·used·to·store·the·output·of·previous·commands.	118	······This·frees·the·memory·used·to·store·the·output·of·previous·commands.
Offset 126, 15 lines modified		Offset 127, 15 lines modified
126	··Class·Console	127	··Class·Console
127	······Consoleis·a·name·that·you·can·chose·yourself·when·you·call·the·above·Ada	128	······Consoleis·a·name·that·you·can·chose·yourself·when·you·call·the·above·Ada
128	······procedure.·It·will·be·assumed·to·beConsolein·the·rest·of·this·document.	129	······procedure.·It·will·be·assumed·to·beConsolein·the·rest·of·this·document.
129	······This·class·provides·an·interface·to·consoles.·A·console·is·an·input/	130	······This·class·provides·an·interface·to·consoles.·A·console·is·an·input/
130	······output·area·in·your·application·(whether·it·is·a·text·area·in·a·graphical	131	······output·area·in·your·application·(whether·it·is·a·text·area·in·a·graphical
131	······application,·or·simply·standard·text·I/O·in·text·mode).·In·particular,	132	······application,·or·simply·standard·text·I/O·in·text·mode).·In·particular,
132	······the·python·standard·output·streamssys.stdin,sys.stdoutandsys.stderrare	133	······the·python·standard·output·streamssys.stdin,sys.stdoutandsys.stderrare
133	······redirected·to·an·instance·of·that·class.·If·you·want·to·see·python's	134	······redirected·to·an·instance·of·that·class.·If·you·want·to·see·pythonâs
134	······error·messages·or·usual·output·in·your·application,·you·must·register	135	······error·messages·or·usual·output·in·your·application,·you·must·register
135	······that·class,·and·define·a·default·console·for·your·scripting·language	136	······that·class,·and·define·a·default·console·for·your·scripting·language
136	······through·calls·toGNATCOLL.Scripts.Set_Default_Console.	137	······through·calls·toGNATCOLL.Scripts.Set_Default_Console.
137	······You·can·later·add·new·methods·to·this·class,·which·would·be·specific·to	138	······You·can·later·add·new·methods·to·this·class,·which·would·be·specific·to
138	······your·application.·Or·you·can·derive·this·class·into·a·new·class·to	139	······your·application.·Or·you·can·derive·this·class·into·a·new·class·to
139	······achieve·a·similar·goal.	140	······achieve·a·similar·goal.
140	··Console.write(text)	141	··Console.write(text)
Offset 168, 38 lines modified		Offset 169, 39 lines modified
168	transparent·for·your·application·whether·you·are·talking·to·the·Shell,·to	169	transparent·for·your·application·whether·you·are·talking·to·the·Shell,·to
169	python,·or·to·another·language·integrated·in·GNATColl.·The·code·remains·exactly	170	python,·or·to·another·language·integrated·in·GNATColl.·The·code·remains·exactly
170	the·same,·and·new·scripting·languages·can·be·added·in·later·releases·of	171	the·same,·and·new·scripting·languages·can·be·added·in·later·releases·of
171	GNATColl·without·requiring·a·change·in·your·application.·This·flexibility·is	172	GNATColl·without·requiring·a·change·in·your·application.·This·flexibility·is
172	central·to·the·design·of·GNATColl.	173	central·to·the·design·of·GNATColl.
Max diff block lines reached; 16203/25792 bytes (62.82%) of diff not shown.


Offset 51, 16 lines modified		Offset 51, 16 lines modified
51	<p>This·can·of·course·be·done·in·most·languages.·However,·that·generally	51	<p>This·can·of·course·be·done·in·most·languages.·However,·that·generally
52	means·you·have·to·remember·not·to·use·the·standard·memory·allocations	52	means·you·have·to·remember·not·to·use·the·standard·memory·allocations
53	like·<cite>malloc</cite>·or·<cite>new</cite>,·and·instead·call·one·of·your	53	like·<cite>malloc</cite>·or·<cite>new</cite>,·and·instead·call·one·of·your
54	subprograms.·If·you·ever·decide·to·change·the·allocation·strategy,·or	54	subprograms.·If·you·ever·decide·to·change·the·allocation·strategy,·or
55	want·to·experiment·with·several·strategies,·that·means·updating·your	55	want·to·experiment·with·several·strategies,·that·means·updating·your
56	code·in·several·places.</p>	56	code·in·several·places.</p>
57	<p>In·Ada,·when·you·declare·the·type·of·your·data,·you·also·specify·through	57	<p>In·Ada,·when·you·declare·the·type·of·your·data,·you·also·specify·through
58	a·<cite>'Storage_Pool</cite>·attribute·how·the·memory·for·instances·of·that	58	a·<cite>‘Storage_Pool</cite>·attribute·how·the·memory·for·instances·of·that
59	type·should·be·allocated.·And·that's·it.·You·then·use·the·usual	59	type·should·be·allocated.·And·that’s·it.·You·then·use·the·usual
60	<cite>new</cite>·keyword·to·allocate·memory.</p>	60	<cite>new</cite>·keyword·to·allocate·memory.</p>
61	<p>GNATColl·provides·a·number·of·examples·for·such·storage·pools,	61	<p>GNATColl·provides·a·number·of·examples·for·such·storage·pools,
62	with·various·goals.·There·is·also·one·advanced·such·pool·in·the·GNAT	62	with·various·goals.·There·is·also·one·advanced·such·pool·in·the·GNAT
63	run-time·itself,·called·<cite>GNAT.Debug_Pools</cite>,·which·allows·you·to	63	run-time·itself,·called·<cite>GNAT.Debug_Pools</cite>,·which·allows·you·to
64	control·memory·leaks·and·whether·all·accesses·do·reference·valid·memory	64	control·memory·leaks·and·whether·all·accesses·do·reference·valid·memory
65	location·(and·not·memory·that·has·already·been·deallocated).</p>	65	location·(and·not·memory·that·has·already·been·deallocated).</p>
66	<p>In·GNATColl,·you·will·find·the·following·storage·pools:</p>	66	<p>In·GNATColl,·you·will·find·the·following·storage·pools:</p>


Offset 20, 16 lines modified		Offset 20, 17 lines modified
20	results·in·a·single·system·call,·which·speeds·up·your·application.	20	results·in·a·single·system·call,·which·speeds·up·your·application.
21	This·can·of·course·be·done·in·most·languages.·However,·that·generally·means·you	21	This·can·of·course·be·done·in·most·languages.·However,·that·generally·means·you
22	have·to·remember·not·to·use·the·standard·memory·allocations·likemallocornew,	22	have·to·remember·not·to·use·the·standard·memory·allocations·likemallocornew,
23	and·instead·call·one·of·your·subprograms.·If·you·ever·decide·to·change·the	23	and·instead·call·one·of·your·subprograms.·If·you·ever·decide·to·change·the
24	allocation·strategy,·or·want·to·experiment·with·several·strategies,·that·means	24	allocation·strategy,·or·want·to·experiment·with·several·strategies,·that·means
25	updating·your·code·in·several·places.	25	updating·your·code·in·several·places.
26	In·Ada,·when·you·declare·the·type·of·your·data,·you·also·specify·through	26	In·Ada,·when·you·declare·the·type·of·your·data,·you·also·specify·through
27	a'Storage_Poolattribute·how·the·memory·for·instances·of·that·type·should·be	27	aâStorage_Poolattribute·how·the·memory·for·instances·of·that·type·should·be
28	allocated.·And·that's·it.·You·then·use·the·usualnewkeyword·to·allocat~~e·m~~e~~mory.~~	28	allocated.·And·thatâs·it.·You·then·use·the·usualnewkeyword·to·allocate
		29	memory.
29	GNATColl·provides·a·number·of·examples·for·such·storage·pools,·with·various	30	GNATColl·provides·a·number·of·examples·for·such·storage·pools,·with·various
30	goals.·There·is·also·one·advanced·such·pool·in·the·GNAT·run-time·itself,	31	goals.·There·is·also·one·advanced·such·pool·in·the·GNAT·run-time·itself,
31	calledGNAT.Debug_Pools,·which·allows·you·to·control·memory·leaks·and·whether	32	calledGNAT.Debug_Pools,·which·allows·you·to·control·memory·leaks·and·whether
32	all·accesses·do·reference·valid·memory·location·(and·not·memory·that·has	33	all·accesses·do·reference·valid·memory·location·(and·not·memory·that·has
33	already·been·deallocated).	34	already·been·deallocated).
34	In·GNATColl,·you·will·find·the·following·storage·pools:	35	In·GNATColl,·you·will·find·the·following·storage·pools:
35	··`GNATCOLL.Storage_Pools.Alignment`	36	··`GNATCOLL.Storage_Pools.Alignment`


Offset 41, 19 lines modified		Offset 41, 19 lines modified
41	··········<div·class="body"·role="main">	41	··········<div·class="body"·role="main">
42	············	42	············
43	··<div·class="section"·id="strings-high-performance-strings">	43	··<div·class="section"·id="strings-high-performance-strings">
44	<h1><span·class="section-number">5.·</span><strong>Strings</strong>:·high-performance·strings<a·class="headerlink"·href="#strings-high-performance-strings"·title="Permalink·to·this·headline">¶</a></h1>	44	<h1><span·class="section-number">5.·</span><strong>Strings</strong>:·high-performance·strings<a·class="headerlink"·href="#strings-high-performance-strings"·title="Permalink·to·this·headline">¶</a></h1>
45	<p>The·generic·package·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Strings_Impl</span></code>·(and·its·default	45	<p>The·generic·package·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Strings_Impl</span></code>·(and·its·default
46	instantiation·in·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Strings</span></code>)·provides·a·high-performance	46	instantiation·in·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Strings</span></code>)·provides·a·high-performance
47	strings·implementation.</p>	47	strings·implementation.</p>
48	<p>It·comes·in·addition·to·Ada's·own·<cite>String</cite>·and·<cite>Unbounded_String</cite>·types,	48	<p>It·comes·in·addition·to·Ada’s·own·<cite>String</cite>·and·<cite>Unbounded_String</cite>·types,
49	although·it·attempts·to·find·a·middle·ground·in·between·(flexibility	49	although·it·attempts·to·find·a·middle·ground·in·between·(flexibility
50	vs·performance).</p>	50	vs·performance).</p>
51	<p>GNATCOLL.Strings·therefore·provides·strings·(named·<cite>XString</cite>,·as·in	51	<p>GNATCOLL.Strings·therefore·provides·strings·(named·<cite>XString</cite>,·as·in
52	extended-strings)·that·can·grow·as·needed·(up·to·<cite>Natural'Last</cite>,·like·standard	52	extended-strings)·that·can·grow·as·needed·(up·to·<cite>Natural’Last</cite>,·like·standard
53	strings),·yet·are·faster·than·unbounded·strings.·They·also·come·with·an	53	strings),·yet·are·faster·than·unbounded·strings.·They·also·come·with·an
54	extended·API,·which·includes·all·primitive·operations·from·unbounded·strings,	54	extended·API,·which·includes·all·primitive·operations·from·unbounded·strings,
55	in·addition·to·some·subprograms·inspired·from·GNATCOLL.Utils·and·the·python·and	55	in·addition·to·some·subprograms·inspired·from·GNATCOLL.Utils·and·the·python·and
56	C++·programming·languages.</p>	56	C++·programming·languages.</p>
57	<div·class="section"·id="small-string-optimization">	57	<div·class="section"·id="small-string-optimization">
58	<h2><span·class="section-number">5.1.·</span>Small·string·optimization<a·class="headerlink"·href="#small-string-optimization"·title="Permalink·to·this·headline">¶</a></h2>	58	<h2><span·class="section-number">5.1.·</span>Small·string·optimization<a·class="headerlink"·href="#small-string-optimization"·title="Permalink·to·this·headline">¶</a></h2>
59	<p>GNATCOLL.Strings·uses·a·number·of·tricks·to·improve·on·the·efficiency.··The	59	<p>GNATCOLL.Strings·uses·a·number·of·tricks·to·improve·on·the·efficiency.··The
Offset 87, 17 lines modified		Offset 87, 17 lines modified
87	</div>	87	</div>
88	<p>So·in·the·same·amount·of·memory·(24·bytes),·we·can·either·store·a·small·string	88	<p>So·in·the·same·amount·of·memory·(24·bytes),·we·can·either·store·a·small·string
89	of·23·characters·or·less·with·no·memory·allocations,·or·a·big·string·that	89	of·23·characters·or·less·with·no·memory·allocations,·or·a·big·string·that
90	requires·allocation.·In·a·typical·application,·most·strings·are·smaller·than·23	90	requires·allocation.·In·a·typical·application,·most·strings·are·smaller·than·23
91	bytes,·so·we·are·saving·very·significant·time·here.</p>	91	bytes,·so·we·are·saving·very·significant·time·here.</p>
92	<p>This·representation·has·to·work·on·both·32·bits·systems·and·64·bits·systems,·so	92	<p>This·representation·has·to·work·on·both·32·bits·systems·and·64·bits·systems,·so
93	we·have·careful·representation·clauses·to·take·this·into·account.··It·also	93	we·have·careful·representation·clauses·to·take·this·into·account.··It·also
94	needs·to·work·on·both·big-endian·and·little-endian·systems.·Thanks·to·Ada's	94	needs·to·work·on·both·big-endian·and·little-endian·systems.·Thanks·to·Ada’s
95	representation·clauses,·this·one·in·fact·relatively·easy·to·achieve·(well,	95	representation·clauses,·this·one·in·fact·relatively·easy·to·achieve·(well,
96	okay,·after·trying·a·few·different·approaches·to·emulate·what's·done·in·C++,	96	okay,·after·trying·a·few·different·approaches·to·emulate·what’s·done·in·C++,
97	and·that·did·not·work·elegantly).·In·fact,·emulating·via·bit-shift·operations	97	and·that·did·not·work·elegantly).·In·fact,·emulating·via·bit-shift·operations
98	ended·up·with·code·that·was·less·efficient·than·letting·the·compiler·do·it	98	ended·up·with·code·that·was·less·efficient·than·letting·the·compiler·do·it
99	automatically·because·of·our·representation·clauses.</p>	99	automatically·because·of·our·representation·clauses.</p>
100	</div>	100	</div>
101	<div·class="section"·id="character-types">	101	<div·class="section"·id="character-types">
102	<h2><span·class="section-number">5.2.·</span>Character·types<a·class="headerlink"·href="#character-types"·title="Permalink·to·this·headline">¶</a></h2>	102	<h2><span·class="section-number">5.2.·</span>Character·types<a·class="headerlink"·href="#character-types"·title="Permalink·to·this·headline">¶</a></h2>
103	<p>Applications·should·be·able·to·handle·the·whole·set·of·Unicode·characters.·In	103	<p>Applications·should·be·able·to·handle·the·whole·set·of·Unicode·characters.·In
Offset 145, 40 lines modified		Offset 145, 40 lines modified
145	<p>This·is·often·a·reasonable·number,·and·given·that·applications·mostly·use·small	145	<p>This·is·often·a·reasonable·number,·and·given·that·applications·mostly·use·small
146	strings,·we·are·already·saving·a·lot·of·allocations.·However,·in·some·cases·we	146	strings,·we·are·already·saving·a·lot·of·allocations.·However,·in·some·cases·we
147	know·that·the·typical·length·of·strings·in·a·particular·context·is·different.	147	know·that·the·typical·length·of·strings·in·a·particular·context·is·different.
148	For·instance,·GNATCOLL.Traces·builds·messages·to·output·in·the·log·file.·Such	148	For·instance,·GNATCOLL.Traces·builds·messages·to·output·in·the·log·file.·Such
149	messages·will·typically·be·at·most·100·characters,·although·they·can·of·course	149	messages·will·typically·be·at·most·100·characters,·although·they·can·of·course
150	be·much·larger·sometimes.</p>	150	be·much·larger·sometimes.</p>
151	<p>We·have·added·one·more·formal·parameter·to·GNATCOLL.Strings_Impl·to·control·the	151	<p>We·have·added·one·more·formal·parameter·to·GNATCOLL.Strings_Impl·to·control·the
152	maximum·size·of·small·strings.·If·for·instance·we·decide·that·a·~~&quot~~;small~~&quot~~;·string	152	maximum·size·of·small·strings.·If·for·instance·we·decide·that·a·“small”·string
153	is·anywhere·from·1·to·100·characters·long·(i.e.·we·do·not·want·to·allocate	153	is·anywhere·from·1·to·100·characters·long·(i.e.·we·do·not·want·to·allocate
154	memory·for·those·strings),·it·can·be·done·via·this·parameter.</p>	154	memory·for·those·strings),·it·can·be·done·via·this·parameter.</p>
155	<p>Of·course,·in·such·cases·the·size·of·the·string·itself·becomes·much·larger.	155	<p>Of·course,·in·such·cases·the·size·of·the·string·itself·becomes·much·larger.
156	In·this·example·it·would·be·101·bytes·long,·rather·than·the·24·bytes.··Although	156	In·this·example·it·would·be·101·bytes·long,·rather·than·the·24·bytes.··Although
157	we·are·saving·on·memory·allocations,·we·are·also·spending·more·time·copying	157	we·are·saving·on·memory·allocations,·we·are·also·spending·more·time·copying
158	data·when·the·string·is·passed·around,·so·you'll·need·to·measure·the	158	data·when·the·string·is·passed·around,·so·you’ll·need·to·measure·the
159	performance·here.</p>	159	performance·here.</p>
160	<p>The·maximum·size·for·the·small·string·is·127·bytes·however,·because·this·size	160	<p>The·maximum·size·for·the·small·string·is·127·bytes·however,·because·this·size
161	and·the·1-bit·flag·need·to·fit·in·1·bytes·in·the·representation·clauses·we	161	and·the·1-bit·flag·need·to·fit·in·1·bytes·in·the·representation·clauses·we
162	showed·above.·We·tried·to·make·this·more·configurable,·but·this·makes·things	162	showed·above.·We·tried·to·make·this·more·configurable,·but·this·makes·things
163	significantly·more·complex·between·little-endian·and·big-endian·systems,·and	163	significantly·more·complex·between·little-endian·and·big-endian·systems,·and
164	having·large·~~&quot~~;small~~&quot~~;·strings·would·not·make·much·sense·in·terms·of·performance	164	having·large·“small”·strings·would·not·make·much·sense·in·terms·of·performance
165	anyway.</p>	165	anyway.</p>
166	<p>Typical·C++·implementations·do·not·make·this·small·size·configurable.</p>	166	<p>Typical·C++·implementations·do·not·make·this·small·size·configurable.</p>
167	</div>	167	</div>
168	<div·class="section"·id="task-safety">	168	<div·class="section"·id="task-safety">
169	<h2><span·class="section-number">5.4.·</span>Task·safety<a·class="headerlink"·href="#task-safety"·title="Permalink·to·this·headline">¶</a></h2>	169	<h2><span·class="section-number">5.4.·</span>Task·safety<a·class="headerlink"·href="#task-safety"·title="Permalink·to·this·headline">¶</a></h2>
170	<p>Just·like·unbounded·strings,·the·strings·in·this·package·are·not·thread·safe.	170	<p>Just·like·unbounded·strings,·the·strings·in·this·package·are·not·thread·safe.
171	This·means·that·you·cannot·access·the·same·string·(read·or·write)·from·two	171	This·means·that·you·cannot·access·the·same·string·(read·or·write)·from·two
172	different·threads·without·somehow·protecting·the·access·via·a·protected·type,	172	different·threads·without·somehow·protecting·the·access·via·a·protected·type,
173	locks,...</p>	173	locks,…</p>
174	<p>In·practice,·sharing·strings·would·rarely·be·done,·so·if·the·package·itself	174	<p>In·practice,·sharing·strings·would·rarely·be·done,·so·if·the·package·itself
175	was·doing·its·own·locking·we·would·end·up·with·very·bad·performance·in·all	175	was·doing·its·own·locking·we·would·end·up·with·very·bad·performance·in·all
176	cases,·for·a·few·cases·where·it·might·prove·useful.</p>	176	cases,·for·a·few·cases·where·it·might·prove·useful.</p>
177	<p>As·we'll·discuss·below,·it·is·possible·to·use·two·different·strings·that	177	<p>As·we’ll·discuss·below,·it·is·possible·to·use·two·different·strings·that
178	actually·share·the·same·internal·buffer,·from·two·different·threads.·Since·this	178	actually·share·the·same·internal·buffer,·from·two·different·threads.·Since·this
179	is·an·implementation·detail,·this·package·takes·care·of·guaranteeing·the	179	is·an·implementation·detail,·this·package·takes·care·of·guaranteeing·the
180	integrity·of·the·shared·data·in·such·a·case.</p>	180	integrity·of·the·shared·data·in·such·a·case.</p>
181	</div>	181	</div>
182	<div·class="section"·id="copy-on-write">	182	<div·class="section"·id="copy-on-write">
183	<h2><span·class="section-number">5.5.·</span>Copy·on·write<a·class="headerlink"·href="#copy-on-write"·title="Permalink·to·this·headline">¶</a></h2>	183	<h2><span·class="section-number">5.5.·</span>Copy·on·write<a·class="headerlink"·href="#copy-on-write"·title="Permalink·to·this·headline">¶</a></h2>
184	<p>There·is·one·more·formal·parameter,·to·configure·whether·this·package·should	184	<p>There·is·one·more·formal·parameter,·to·configure·whether·this·package·should
Offset 217, 38 lines modified		Offset 217, 38 lines modified
217	<p>This·package·has·a·slightly·different·strategy.·Remember·that·we·only·start	217	<p>This·package·has·a·slightly·different·strategy.·Remember·that·we·only·start
218	allocating·memory·past·the·size·of·small·strings,·so·we·will·for·instance·first	218	allocating·memory·past·the·size·of·small·strings,·so·we·will·for·instance·first
219	allocate·24·bytes.·When·more·memory·is·needed,·we·multiply·this·size·by·1.5,	219	allocate·24·bytes.·When·more·memory·is·needed,·we·multiply·this·size·by·1.5,
220	which·some·researchers·have·found·to·be·a·good·comprise·between·waste·of·memory	220	which·some·researchers·have·found·to·be·a·good·comprise·between·waste·of·memory
221	and·number·of·allocations.·For·very·large·strings,·we·always·allocate·multiples	221	and·number·of·allocations.·For·very·large·strings,·we·always·allocate·multiples
222	of·the·memory·page·size·(4096·bytes),·since·this·is·what·the·system·will·make	222	of·the·memory·page·size·(4096·bytes),·since·this·is·what·the·system·will·make
223	available·anyway.·So·we·will·basically·allocate·the·following:·24,·36,·54,·82,	223	available·anyway.·So·we·will·basically·allocate·the·following:·24,·36,·54,·82,
224	122,...</p>	224	122,…</p>
225	<p>An·additional·constraint·is·that·we·only·ever·allocate·even·number·of·bytes.	225	<p>An·additional·constraint·is·that·we·only·ever·allocate·even·number·of·bytes.
226	This·is·called·the·capacity·of·the·string.·In·the·layout·of·the·big·string,	226	This·is·called·the·capacity·of·the·string.·In·the·layout·of·the·big·string,
227	as·shown·above,·we·store·half·that·capacity,·which·saves·one·bit·that·we	227	as·shown·above,·we·store·half·that·capacity,·which·saves·one·bit·that·we
228	use·for·the·flag.</p>	228	use·for·the·flag.</p>
229	</div>	229	</div>
230	<div·class="section"·id="substrings">	230	<div·class="section"·id="substrings">
231	<h2><span·class="section-number">5.7.·</span>Substrings<a·class="headerlink"·href="#substrings"·title="Permalink·to·this·headline">¶</a></h2>	231	<h2><span·class="section-number">5.7.·</span>Substrings<a·class="headerlink"·href="#substrings"·title="Permalink·to·this·headline">¶</a></h2>
232	<p>One·other·optimization·performed·by·this·package·(which·is·not·done·for	232	<p>One·other·optimization·performed·by·this·package·(which·is·not·done·for
233	unbounded·strings·or·various·C++·implementations)·is·to·optimize·substrings	233	unbounded·strings·or·various·C++·implementations)·is·to·optimize·substrings
234	when·also·using·copy-on-write.</p>	234	when·also·using·copy-on-write.</p>
235	<p>We·simply·store·the·index·of·the·first·character·of·the·string·within·the	235	<p>We·simply·store·the·index·of·the·first·character·of·the·string·within·the
236	shared·buffer,·instead·of·always·starting·at·the·first.</p>	236	shared·buffer,·instead·of·always·starting·at·the·first.</p>
237	<p>From·the·user's·point·of·view,·this·is·an·implementation·detail.·Strings	237	<p>From·the·user’s·point·of·view,·this·is·an·implementation·detail.·Strings
238	are·always·indexed·from·1,·and·internally·we·convert·to·an·actual·position	238	are·always·indexed·from·1,·and·internally·we·convert·to·an·actual·position
239	in·the·buffer.·This·means·that·if·we·need·to·reallocate·the·buffer,·for	239	in·the·buffer.·This·means·that·if·we·need·to·reallocate·the·buffer,·for
240	instance·when·the·string·is·modified,·we·transparently·change·the·index	240	instance·when·the·string·is·modified,·we·transparently·change·the·index
241	of·the·first·character,·but·the·indexes·the·user·was·using·are·still·valid.</p>	241	of·the·first·character,·but·the·indexes·the·user·was·using·are·still·valid.</p>
242	<p>This·results·in·very·significant·savings,·as·shown·below·in·the·timings	242	<p>This·results·in·very·significant·savings,·as·shown·below·in·the·timings
243	for·Trim·for·instance.·Also,·we·can·do·an·operation·like·splitting·a	243	for·Trim·for·instance.·Also,·we·can·do·an·operation·like·splitting·a
244	string·very·efficiently.</p>	244	string·very·efficiently.</p>
245	<p>For·instance,·the·following·code·doesn't·allocate·any·memory,·beside	245	<p>For·instance,·the·following·code·doesn’t·allocate·any·memory,·beside
246	setting·the·initial·value·of·the·string.·It·parses·a·file·containing	246	setting·the·initial·value·of·the·string.·It·parses·a·file·containing
247	some·~~&quot~~;key=value~~&quot~~;·lines,·with·optional·spaces,·and·possibly·empty·lines:</p>	247	some·“key=value”·lines,·with·optional·spaces,·and·possibly·empty·lines:</p>
248	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>	248	<div·class="highlight-ada·notranslate"><div·class="highlight"><pre><span></span><span·class="kr">declare</span>
249	···<span·class="n">S</span><span·class="p">,</span>·<span·class="n">Key</span><span·class="p">,</span>·<span·class="n">Value</span>·<span·class="p">:</span>·<span·class="n">XString</span><span·class="p">;</span>	249	···<span·class="n">S</span><span·class="p">,</span>·<span·class="n">Key</span><span·class="p">,</span>·<span·class="n">Value</span>·<span·class="p">:</span>·<span·class="n">XString</span><span·class="p">;</span>
250	···<span·class="n">L</span>·············<span·class="p">:</span>·<span·class="n">XString_Array</span>·<span·class="p">(</span><span·class="mi">1</span>·<span·class="p">..</span>·<span·class="mi">2</span><span·class="p">);</span>	250	···<span·class="n">L</span>·············<span·class="p">:</span>·<span·class="n">XString_Array</span>·<span·class="p">(</span><span·class="mi">1</span>·<span·class="p">..</span>·<span·class="mi">2</span><span·class="p">);</span>
251	···<span·class="n">Last</span>··········<span·class="p">:</span>·<span·class="kt">Natural</span><span·class="p">;</span>	251	···<span·class="n">Last</span>··········<span·class="p">:</span>·<span·class="kt">Natural</span><span·class="p">;</span>
252	<span·class="kr">begin</span>	252	<span·class="kr">begin</span>
253	···<span·class="n">S</span><span·class="p">.</span><span·class="n">Set</span>·<span·class="p">(</span><span·class="s">"......."</span><span·class="p">);</span>	253	···<span·class="n">S</span><span·class="p">.</span><span·class="n">Set</span>·<span·class="p">(</span><span·class="s">"......."</span><span·class="p">);</span>


Offset 11, 18 lines modified		Offset 11, 18 lines modified
11	····*·next·\|	11	····*·next·\|
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·5.·Strings:·high-performance·strings	14	····*·5.·Strings:·high-performance·strings
15	****·5.·Strings:·high-performance·stringsÂ¶·****	15	****·5.·Strings:·high-performance·stringsÂ¶·****
16	The·generic·package·GNATCOLL.Strings_Impl·(and·its·default·instantiation·in	16	The·generic·package·GNATCOLL.Strings_Impl·(and·its·default·instantiation·in
17	GNATCOLL.Strings)·provides·a·high-performance·strings·implementation.	17	GNATCOLL.Strings)·provides·a·high-performance·strings·implementation.
18	It·comes·in·addition·to·Ada's·ownStringandUnbounded_Stringtypes,·although·it	18	It·comes·in·addition·to·Adaâs·ownStringandUnbounded_Stringtypes,·although·it
19	attempts·to·find·a·middle·ground·in·between·(flexibility·vs·performance).	19	attempts·to·find·a·middle·ground·in·between·(flexibility·vs·performance).
20	GNATCOLL.Strings·therefore·provides·strings·(namedXString,·as·in·extended-	20	GNATCOLL.Strings·therefore·provides·strings·(namedXString,·as·in·extended-
21	strings)·that·can·grow·as·needed·(up·toNatural'Last,·like·standard·strings),	21	strings)·that·can·grow·as·needed·(up·toNaturalâLast,·like·standard·strings),
22	yet·are·faster·than·unbounded·strings.·They·also·come·with·an·extended·API,	22	yet·are·faster·than·unbounded·strings.·They·also·come·with·an·extended·API,
23	which·includes·all·primitive·operations·from·unbounded·strings,·in·addition·to	23	which·includes·all·primitive·operations·from·unbounded·strings,·in·addition·to
24	some·subprograms·inspired·from·GNATCOLL.Utils·and·the·python·and·C++	24	some·subprograms·inspired·from·GNATCOLL.Utils·and·the·python·and·C++
25	programming·languages.	25	programming·languages.
26	***·5.1.·Small·string·optimizationÂ¶·***	26	***·5.1.·Small·string·optimizationÂ¶·***
27	GNATCOLL.Strings·uses·a·number·of·tricks·to·improve·on·the·efficiency.·The·most	27	GNATCOLL.Strings·uses·a·number·of·tricks·to·improve·on·the·efficiency.·The·most
28	important·one·is·to·limit·the·number·of·memory·allocations.·For·this,·we·use·a	28	important·one·is·to·limit·the·number·of·memory·allocations.·For·this,·we·use·a
Offset 53, 17 lines modified		Offset 53, 17 lines modified
53	·········This·is·because·of·alignment·issues.	53	·········This·is·because·of·alignment·issues.
54	So·in·the·same·amount·of·memory·(24·bytes),·we·can·either·store·a·small·string	54	So·in·the·same·amount·of·memory·(24·bytes),·we·can·either·store·a·small·string
55	of·23·characters·or·less·with·no·memory·allocations,·or·a·big·string·that	55	of·23·characters·or·less·with·no·memory·allocations,·or·a·big·string·that
56	requires·allocation.·In·a·typical·application,·most·strings·are·smaller·than·23	56	requires·allocation.·In·a·typical·application,·most·strings·are·smaller·than·23
57	bytes,·so·we·are·saving·very·significant·time·here.	57	bytes,·so·we·are·saving·very·significant·time·here.
58	This·representation·has·to·work·on·both·32·bits·systems·and·64·bits·systems,·so	58	This·representation·has·to·work·on·both·32·bits·systems·and·64·bits·systems,·so
59	we·have·careful·representation·clauses·to·take·this·into·account.·It·also·needs	59	we·have·careful·representation·clauses·to·take·this·into·account.·It·also·needs
60	to·work·on·both·big-endian·and·little-endian·systems.·Thanks·to·Ada's	60	to·work·on·both·big-endian·and·little-endian·systems.·Thanks·to·Adaâs
61	representation·clauses,·this·one·in·fact·relatively·easy·to·achieve·(well,	61	representation·clauses,·this·one·in·fact·relatively·easy·to·achieve·(well,
62	okay,·after·trying·a·few·different·approaches·to·emulate·what's·done·in·C++,	62	okay,·after·trying·a·few·different·approaches·to·emulate·whatâs·done·in·C++,
63	and·that·did·not·work·elegantly).·In·fact,·emulating·via·bit-shift·operations	63	and·that·did·not·work·elegantly).·In·fact,·emulating·via·bit-shift·operations
64	ended·up·with·code·that·was·less·efficient·than·letting·the·compiler·do·it	64	ended·up·with·code·that·was·less·efficient·than·letting·the·compiler·do·it
65	automatically·because·of·our·representation·clauses.	65	automatically·because·of·our·representation·clauses.
66	***·5.2.·Character·typesÂ¶·***	66	***·5.2.·Character·typesÂ¶·***
67	Applications·should·be·able·to·handle·the·whole·set·of·Unicode·characters.·In	67	Applications·should·be·able·to·handle·the·whole·set·of·Unicode·characters.·In
68	Ada,·these·are·represented·as·the·Wide_Character·type,·rather·than·Character,	68	Ada,·these·are·represented·as·the·Wide_Character·type,·rather·than·Character,
69	and·stored·on·2·bytes·rather·than·1.·Of·course,·for·a·lot·of·applications·it	69	and·stored·on·2·bytes·rather·than·1.·Of·course,·for·a·lot·of·applications·it
Offset 102, 38 lines modified		Offset 102, 38 lines modified
102	This·is·often·a·reasonable·number,·and·given·that·applications·mostly·use·small	102	This·is·often·a·reasonable·number,·and·given·that·applications·mostly·use·small
103	strings,·we·are·already·saving·a·lot·of·allocations.·However,·in·some·cases·we	103	strings,·we·are·already·saving·a·lot·of·allocations.·However,·in·some·cases·we
104	know·that·the·typical·length·of·strings·in·a·particular·context·is·different.	104	know·that·the·typical·length·of·strings·in·a·particular·context·is·different.
105	For·instance,·GNATCOLL.Traces·builds·messages·to·output·in·the·log·file.·Such	105	For·instance,·GNATCOLL.Traces·builds·messages·to·output·in·the·log·file.·Such
106	messages·will·typically·be·at·most·100·characters,·although·they·can·of·course	106	messages·will·typically·be·at·most·100·characters,·although·they·can·of·course
107	be·much·larger·sometimes.	107	be·much·larger·sometimes.
108	We·have·added·one·more·formal·parameter·to·GNATCOLL.Strings_Impl·to·control·the	108	We·have·added·one·more·formal·parameter·to·GNATCOLL.Strings_Impl·to·control·the
109	maximum·size·of·small·strings.·If·for·instance·we·decide·that·a·"small~~"·string~~	109	maximum·size·of·small·strings.·If·for·instance·we·decide·that·a·âsmallâ
110	is·anywhere·from·1·to·100·characters·long·(i.e.·we·do·not·want·t~~o·all~~o~~cate~~	110	string·is·anywhere·from·1·to·100·characters·long·(i.e.·we·do·not·want·to
111	memory·for·those·strings),·it·can·be·done·via·this·parameter.	111	allocate·memory·for·those·strings),·it·can·be·done·via·this·parameter.
112	Of·course,·in·such·cases·the·size·of·the·string·itself·becomes·much·larger.·In	112	Of·course,·in·such·cases·the·size·of·the·string·itself·becomes·much·larger.·In
113	this·example·it·would·be·101·bytes·long,·rather·than·the·24·bytes.·Although·we	113	this·example·it·would·be·101·bytes·long,·rather·than·the·24·bytes.·Although·we
114	are·saving·on·memory·allocations,·we·are·also·spending·more·time·copying·data	114	are·saving·on·memory·allocations,·we·are·also·spending·more·time·copying·data
115	when·the·string·is·passed·around,·so·you'll·need·to·measure·the·performance	115	when·the·string·is·passed·around,·so·youâll·need·to·measure·the·performance
116	here.	116	here.
117	The·maximum·size·for·the·small·string·is·127·bytes·however,·because·this·size	117	The·maximum·size·for·the·small·string·is·127·bytes·however,·because·this·size
118	and·the·1-bit·flag·need·to·fit·in·1·bytes·in·the·representation·clauses·we	118	and·the·1-bit·flag·need·to·fit·in·1·bytes·in·the·representation·clauses·we
119	showed·above.·We·tried·to·make·this·more·configurable,·but·this·makes·things	119	showed·above.·We·tried·to·make·this·more·configurable,·but·this·makes·things
120	significantly·more·complex·between·little-endian·and·big-endian·systems,·and	120	significantly·more·complex·between·little-endian·and·big-endian·systems,·and
121	having·large·"small"·strings·would·not·make·much·sense·in·terms·o~~f·per~~f~~ormance~~	121	having·large·âsmallâ·strings·would·not·make·much·sense·in·terms·of
122	anyway.	122	performance·anyway.
123	Typical·C++·implementations·do·not·make·this·small·size·configurable.	123	Typical·C++·implementations·do·not·make·this·small·size·configurable.
124	***·5.4.·Task·safetyÂ¶·***	124	***·5.4.·Task·safetyÂ¶·***
125	Just·like·unbounded·strings,·the·strings·in·this·package·are·not·thread·safe.	125	Just·like·unbounded·strings,·the·strings·in·this·package·are·not·thread·safe.
126	This·means·that·you·cannot·access·the·same·string·(read·or·write)·from·two	126	This·means·that·you·cannot·access·the·same·string·(read·or·write)·from·two
127	different·threads·without·somehow·protecting·the·access·via·a·protected·type,	127	different·threads·without·somehow·protecting·the·access·via·a·protected·type,
128	locks,~~...~~	128	locks,â¦
129	In·practice,·sharing·strings·would·rarely·be·done,·so·if·the·package·itself·was	129	In·practice,·sharing·strings·would·rarely·be·done,·so·if·the·package·itself·was
130	doing·its·own·locking·we·would·end·up·with·very·bad·performance·in·all·cases,	130	doing·its·own·locking·we·would·end·up·with·very·bad·performance·in·all·cases,
131	for·a·few·cases·where·it·might·prove·useful.	131	for·a·few·cases·where·it·might·prove·useful.
132	As·we'll·discuss·below,·it·is·possible·to·use·two·different·strings·that	132	As·weâll·discuss·below,·it·is·possible·to·use·two·different·strings·that
133	actually·share·the·same·internal·buffer,·from·two·different·threads.·Since·this	133	actually·share·the·same·internal·buffer,·from·two·different·threads.·Since·this
134	is·an·implementation·detail,·this·package·takes·care·of·guaranteeing·the	134	is·an·implementation·detail,·this·package·takes·care·of·guaranteeing·the
135	integrity·of·the·shared·data·in·such·a·case.	135	integrity·of·the·shared·data·in·such·a·case.
136	***·5.5.·Copy·on·writeÂ¶·***	136	***·5.5.·Copy·on·writeÂ¶·***
137	There·is·one·more·formal·parameter,·to·configure·whether·this·package·should	137	There·is·one·more·formal·parameter,·to·configure·whether·this·package·should
138	use·copy-on-write·or·not.·When·copy·on·write·is·enabled,·you·can·have·multiple	138	use·copy-on-write·or·not.·When·copy·on·write·is·enabled,·you·can·have·multiple
139	strings·that·internally·share·the·same·buffer·of·characters.·This·means·that	139	strings·that·internally·share·the·same·buffer·of·characters.·This·means·that
Offset 167, 36 lines modified		Offset 167, 36 lines modified
167	This·package·has·a·slightly·different·strategy.·Remember·that·we·only·start	167	This·package·has·a·slightly·different·strategy.·Remember·that·we·only·start
168	allocating·memory·past·the·size·of·small·strings,·so·we·will·for·instance·first	168	allocating·memory·past·the·size·of·small·strings,·so·we·will·for·instance·first
169	allocate·24·bytes.·When·more·memory·is·needed,·we·multiply·this·size·by·1.5,	169	allocate·24·bytes.·When·more·memory·is·needed,·we·multiply·this·size·by·1.5,
170	which·some·researchers·have·found·to·be·a·good·comprise·between·waste·of·memory	170	which·some·researchers·have·found·to·be·a·good·comprise·between·waste·of·memory
171	and·number·of·allocations.·For·very·large·strings,·we·always·allocate·multiples	171	and·number·of·allocations.·For·very·large·strings,·we·always·allocate·multiples
172	of·the·memory·page·size·(4096·bytes),·since·this·is·what·the·system·will·make	172	of·the·memory·page·size·(4096·bytes),·since·this·is·what·the·system·will·make
173	available·anyway.·So·we·will·basically·allocate·the·following:·24,·36,·54,·82,	173	available·anyway.·So·we·will·basically·allocate·the·following:·24,·36,·54,·82,
174	122,~~...~~	174	122,â¦
175	An·additional·constraint·is·that·we·only·ever·allocate·even·number·of·bytes.	175	An·additional·constraint·is·that·we·only·ever·allocate·even·number·of·bytes.
176	This·is·called·the·capacity·of·the·string.·In·the·layout·of·the·big·string,·as	176	This·is·called·the·capacity·of·the·string.·In·the·layout·of·the·big·string,·as
177	shown·above,·we·store·half·that·capacity,·which·saves·one·bit·that·we·use·for	177	shown·above,·we·store·half·that·capacity,·which·saves·one·bit·that·we·use·for
178	the·flag.	178	the·flag.
179	***·5.7.·SubstringsÂ¶·***	179	***·5.7.·SubstringsÂ¶·***
180	One·other·optimization·performed·by·this·package·(which·is·not·done·for	180	One·other·optimization·performed·by·this·package·(which·is·not·done·for
181	unbounded·strings·or·various·C++·implementations)·is·to·optimize·substrings	181	unbounded·strings·or·various·C++·implementations)·is·to·optimize·substrings
182	when·also·using·copy-on-write.	182	when·also·using·copy-on-write.
183	We·simply·store·the·index·of·the·first·character·of·the·string·within·the	183	We·simply·store·the·index·of·the·first·character·of·the·string·within·the
184	shared·buffer,·instead·of·always·starting·at·the·first.	184	shared·buffer,·instead·of·always·starting·at·the·first.
185	From·the·user's·point·of·view,·this·is·an·implementation·detail.·Strings·are	185	From·the·userâs·point·of·view,·this·is·an·implementation·detail.·Strings·are
186	always·indexed·from·1,·and·internally·we·convert·to·an·actual·position·in·the	186	always·indexed·from·1,·and·internally·we·convert·to·an·actual·position·in·the
187	buffer.·This·means·that·if·we·need·to·reallocate·the·buffer,·for·instance·when	187	buffer.·This·means·that·if·we·need·to·reallocate·the·buffer,·for·instance·when
188	the·string·is·modified,·we·transparently·change·the·index·of·the·first	188	the·string·is·modified,·we·transparently·change·the·index·of·the·first
189	character,·but·the·indexes·the·user·was·using·are·still·valid.	189	character,·but·the·indexes·the·user·was·using·are·still·valid.
190	This·results·in·very·significant·savings,·as·shown·below·in·the·timings·for	190	This·results·in·very·significant·savings,·as·shown·below·in·the·timings·for
191	Trim·for·instance.·Also,·we·can·do·an·operation·like·splitting·a·string·very	191	Trim·for·instance.·Also,·we·can·do·an·operation·like·splitting·a·string·very
192	efficiently.	192	efficiently.
193	For·instance,·the·following·code·doesn't·allocate·any·memory,·beside·setting	193	For·instance,·the·following·code·doesnât·allocate·any·memory,·beside·setting
194	the·initial·value·of·the·string.·It·parses·a·file·containing·some~~·"key=value"~~	194	the·initial·value·of·the·string.·It·parses·a·file·containing·some
195	lines,·with·optional·spaces,·and·possibly·empty·lines:	195	âkey=valueâ·lines,·with·optional·spaces,·and·possibly·empty·lines:
196	declare	196	declare
197	···S,·Key,·Value·:·XString;	197	···S,·Key,·Value·:·XString;
198	···L·············:·XString_Array·(1·..·2);	198	···L·············:·XString_Array·(1·..·2);
199	···Last··········:·Natural;	199	···Last··········:·Natural;
200	begin	200	begin
201	···S.Set·(".......");	201	···S.Set·(".......");


Offset 40, 45 lines modified		Offset 40, 45 lines modified
40	········<div·class="bodywrapper">	40	········<div·class="bodywrapper">
41	··········<div·class="body"·role="main">	41	··········<div·class="body"·role="main">
42	············	42	············
43	··<div·class="section"·id="templates-generating-text">	43	··<div·class="section"·id="templates-generating-text">
44	<h1><span·class="section-number">10.·</span><strong>Templates</strong>:·generating·text<a·class="headerlink"·href="#templates-generating-text"·title="Permalink·to·this·headline">¶</a></h1>	44	<h1><span·class="section-number">10.·</span><strong>Templates</strong>:·generating·text<a·class="headerlink"·href="#templates-generating-text"·title="Permalink·to·this·headline">¶</a></h1>
45	<p·id="index-0">This·module·provides·convenient·subprograms·for·replacing·specific	45	<p·id="index-0">This·module·provides·convenient·subprograms·for·replacing·specific
46	substrings·with·other·values.·It·is·typically·used·to·replace·substrings	46	substrings·with·other·values.·It·is·typically·used·to·replace·substrings
47	like·~~&quot~~;%{version}~~&quot~~;·in·a·longer·string·with·the·actual·version,·at·run·time.</p>	47	like·“%{version}”·in·a·longer·string·with·the·actual·version,·at·run·time.</p>
48	<p>This·module·is·not·the·same·as·the·templates·parser·provided·in·the·context	48	<p>This·module·is·not·the·same·as·the·templates·parser·provided·in·the·context
49	of·AWS,·the·Ada·web·server,·where·external·files·are·parsed·and·processed	49	of·AWS,·the·Ada·web·server,·where·external·files·are·parsed·and·processed
50	to·generate·other·files.·The·latter·provides·advanced·features·like·filters,	50	to·generate·other·files.·The·latter·provides·advanced·features·like·filters,
51	loops,...</p>	51	loops,…</p>
52	<p>The·substrings·to·be·replaced·always·start·with·a·specific·delimiter,·which	52	<p>The·substrings·to·be·replaced·always·start·with·a·specific·delimiter,·which
53	is·set·to·<cite>%</cite>·by·default,·but·can·be·overridden·in·your·code.·The·name	53	is·set·to·<cite>%</cite>·by·default,·but·can·be·overridden·in·your·code.·The·name
54	of·the·substring·to·be·replaced·is·then·the·identifier·following·that	54	of·the·substring·to·be·replaced·is·then·the·identifier·following·that
55	delimiter,·with·the·following·rules:</p>	55	delimiter,·with·the·following·rules:</p>
56	<ul·class="simple">	56	<ul·class="simple">
57	<li><p>If·the·character·following·the·delimiter·is·the·delimiter·itself,	57	<li><p>If·the·character·following·the·delimiter·is·the·delimiter·itself,
58	then·the·final·string·will·contain·a·single·instance·of·that·delimiter,·and	58	then·the·final·string·will·contain·a·single·instance·of·that·delimiter,·and
59	no·further·substitution·is·done·for·that·delimiter.·An·example·of·this·is	59	no·further·substitution·is·done·for·that·delimiter.·An·example·of·this·is
60	<cite>~~&quot~~;%%~~&quot~~;</cite>.</p></li>	60	<cite>“%%”</cite>.</p></li>
61	<li><p>If·the·character·immediately·after·the·delimiter·is·a·curly·brace	61	<li><p>If·the·character·immediately·after·the·delimiter·is·a·curly·brace
62	(<cite>{</cite>),·then·the·name·of·the·identifier·is·the·text·until·the·next	62	(<cite>{</cite>),·then·the·name·of·the·identifier·is·the·text·until·the·next
63	closing·curly·brace.·It·can·then·contain·any·character·expect·a·closing	63	closing·curly·brace.·It·can·then·contain·any·character·expect·a·closing
64	curly·brace.·An·example·of·this·is·<cite>~~&quot~~;%{long·name}~~&quot~~;</cite></p></li>	64	curly·brace.·An·example·of·this·is·<cite>“%{long·name}”</cite></p></li>
65	<li><p>If·the·first·character·after·the·delimiter·is·a·digit,·then·the	65	<li><p>If·the·first·character·after·the·delimiter·is·a·digit,·then·the
66	name·of·the·identifier·is·the·number·after·the·delimiter.·An·example·of	66	name·of·the·identifier·is·the·number·after·the·delimiter.·An·example·of
67	this·is·<cite>~~&quot~~;%12~~&quot~~;</cite>.·As·a·special·case,·if·the·first·non-digit	67	this·is·<cite>“%12”</cite>.·As·a·special·case,·if·the·first·non-digit
68	character·is·the·symbol·<cite>-</cite>,·it·is·added·as·part·of·the·name·of·the	68	character·is·the·symbol·<cite>-</cite>,·it·is·added·as·part·of·the·name·of·the
69	identifier,·as·in·<cite>~~&quot~~;%1-~~&quot~~;</cite>.·One·use·for·this·feature·is·to·indicate	69	identifier,·as·in·<cite>“%1-“</cite>.·One·use·for·this·feature·is·to·indicate
70	you·want·to·replace·it·with·all·the·positional·parameters·%1%2%3%4.·For	70	you·want·to·replace·it·with·all·the·positional·parameters·%1%2%3%4.·For
71	instance,·if·you·are·writing·the·command·line·to·spawn·an·external·tool,	71	instance,·if·you·are·writing·the·command·line·to·spawn·an·external·tool,
72	to·which·the·user·can·pass·any·number·of·parameter,·you·could·specify·that	72	to·which·the·user·can·pass·any·number·of·parameter,·you·could·specify·that
73	command·line·as·<cite>~~&quot~~;tool·-o·%1·%2-~~&quot~~;</cite>·to·indicate·that·all·parameters	73	command·line·as·<cite>“tool·-o·%1·%2-“</cite>·to·indicate·that·all·parameters
74	should·be·concatenated·on·the·command·line.</p></li>	74	should·be·concatenated·on·the·command·line.</p></li>
75	<li><p>If·the·first·character·after·the·delimiter·is·a·letter,·the·identifier	75	<li><p>If·the·first·character·after·the·delimiter·is·a·letter,·the·identifier
76	follows·the·same·rules·as·for·Ada·identifiers,·and·can·contain·any·letter,	76	follows·the·same·rules·as·for·Ada·identifiers,·and·can·contain·any·letter,
77	digit,·or·underscore·character.·An·example·of·this·is·<cite>~~&quot~~;%ab_12~~&quot~~;</cite>.·For	77	digit,·or·underscore·character.·An·example·of·this·is·<cite>“%ab_12”</cite>.·For
78	readability,·it·is·recommended·to·use·the·curly·brace·notation·when·the	78	readability,·it·is·recommended·to·use·the·curly·brace·notation·when·the
79	name·is·complex,·but·that·is·not·mandatory.</p></li>	79	name·is·complex,·but·that·is·not·mandatory.</p></li>
80	<li><p>Otherwise·the·name·of·the·identifier·is·the·single·character	80	<li><p>Otherwise·the·name·of·the·identifier·is·the·single·character
81	following·the·delimiter</p></li>	81	following·the·delimiter</p></li>
82	</ul>	82	</ul>
83	<p>For·each·substring·matching·the·rules·above,·the·<cite>Substitute</cite>·subprogram	83	<p>For·each·substring·matching·the·rules·above,·the·<cite>Substitute</cite>·subprogram
84	will·look·for·possible·replacement·text·in·the·following·order:</p>	84	will·look·for·possible·replacement·text·in·the·following·order:</p>


Offset 10, 47 lines modified		Offset 10, 47 lines modified
10	····*·index	10	····*·index
11	····*·next·\|	11	····*·next·\|
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·10.·Templates:·generating·text	14	····*·10.·Templates:·generating·text
15	****·10.·Templates:·generating·textÂ¶·****	15	****·10.·Templates:·generating·textÂ¶·****
16	This·module·provides·convenient·subprograms·for·replacing·specific·substrings	16	This·module·provides·convenient·subprograms·for·replacing·specific·substrings
17	with·other·values.·It·is·typically·used·to·replace·substrings·like·~~"%{version}"~~	17	with·other·values.·It·is·typically·used·to·replace·substrings·like·â%
18	in·a·longer·string·with·the·actual·version,·at·run·time.	18	{version}â·in·a·longer·string·with·the·actual·version,·at·run·time.
19	This·module·is·not·the·same·as·the·templates·parser·provided·in·the·context·of	19	This·module·is·not·the·same·as·the·templates·parser·provided·in·the·context·of
20	AWS,·the·Ada·web·server,·where·external·files·are·parsed·and·processed·to	20	AWS,·the·Ada·web·server,·where·external·files·are·parsed·and·processed·to
21	generate·other·files.·The·latter·provides·advanced·features·like·filters,	21	generate·other·files.·The·latter·provides·advanced·features·like·filters,
22	loops,~~...~~	22	loops,â¦
23	The·substrings·to·be·replaced·always·start·with·a·specific·delimiter,·which·is	23	The·substrings·to·be·replaced·always·start·with·a·specific·delimiter,·which·is
24	set·to%by·default,·but·can·be·overridden·in·your·code.·The·name·of·the	24	set·to%by·default,·but·can·be·overridden·in·your·code.·The·name·of·the
25	substring·to·be·replaced·is·then·the·identifier·following·that·delimiter,·with	25	substring·to·be·replaced·is·then·the·identifier·following·that·delimiter,·with
26	the·following·rules:	26	the·following·rules:
27	····*·If·the·character·following·the·delimiter·is·the·delimiter·itself,·then	27	····*·If·the·character·following·the·delimiter·is·the·delimiter·itself,·then
28	······the·final·string·will·contain·a·single·instance·of·that·delimiter,·and·no	28	······the·final·string·will·contain·a·single·instance·of·that·delimiter,·and·no
29	······further·substitution·is·done·for·that·delimiter.·An·example·of·this	29	······further·substitution·is·done·for·that·delimiter.·An·example·of·this
30	······is"%%".	30	······isâ%%â.
31	····*·If·the·character·immediately·after·the·delimiter·is·a·curly·brace·({),	31	····*·If·the·character·immediately·after·the·delimiter·is·a·curly·brace·({),
32	······then·the·name·of·the·identifier·is·the·text·until·the·next·closing·curly	32	······then·the·name·of·the·identifier·is·the·text·until·the·next·closing·curly
33	······brace.·It·can·then·contain·any·character·expect·a·closing·curly·brace.·An	33	······brace.·It·can·then·contain·any·character·expect·a·closing·curly·brace.·An
34	······example·of·this·is"%{long·name}"	34	······example·of·this·isâ%{long·name}â
35	····*·If·the·first·character·after·the·delimiter·is·a·digit,·then·the·name·of	35	····*·If·the·first·character·after·the·delimiter·is·a·digit,·then·the·name·of
36	······the·identifier·is·the·number·after·the·delimiter.·An·example·of·this	36	······the·identifier·is·the·number·after·the·delimiter.·An·example·of·this
37	······is"%12".·As·a·special·case,·if·the·first·non-digit·character·is·the	37	······isâ%12â.·As·a·special·case,·if·the·first·non-digit·character·is·the
38	······symbol-,·it·is·added·as·part·of·the·name·of·the·identifier,·as·in"%1-".	38	······symbol-,·it·is·added·as·part·of·the·name·of·the·identifier,·as·inâ%1-
39	······One·use·for·this·feature·is·to·indicate·you·want·to·replace·it·with~~·all~~	39	······â.·One·use·for·this·feature·is·to·indicate·you·want·to·replace·it·with
40	······the·positional·parameters·%1%2%3%4.·For·instance,·if·you·are·writing~~·the~~	40	······all·the·positional·parameters·%1%2%3%4.·For·instance,·if·you·are·writing
41	······command·line·to·spawn·an·external·tool,·to·which·the·user·can·pass~~·any~~	41	······the·command·line·to·spawn·an·external·tool,·to·which·the·user·can·pass
42	······number·of·parameter,·you·could·specify·that·command·line·as"tool·-~~o·%1~~	42	······any·number·of·parameter,·you·could·specify·that·command·line·asâtool·-
43	······%2-"to·indicate·that·all·parameters·should·be·concatenated·on·the~~·command~~	43	······o·%1·%2-âto·indicate·that·all·parameters·should·be·concatenated·on·the
44	······line.	44	······command·line.
45	····*·If·the·first·character·after·the·delimiter·is·a·letter,·the·identifier	45	····*·If·the·first·character·after·the·delimiter·is·a·letter,·the·identifier
46	······follows·the·same·rules·as·for·Ada·identifiers,·and·can·contain·any	46	······follows·the·same·rules·as·for·Ada·identifiers,·and·can·contain·any
47	······letter,·digit,·or·underscore·character.·An·example·of·this~~·is"%ab_12".~~	47	······letter,·digit,·or·underscore·character.·An·example·of·this
48	······For·readability,·it·is·recommended·to·use·the·curly·brac~~e·notation·wh~~en	48	······isâ%ab_12â.·For·readability,·it·is·recommended·to·use·the·curly·brace
49	······the·name·is·complex,·but·that·is·not·mandatory.	49	······notation·when·the·name·is·complex,·but·that·is·not·mandatory.
50	····*·Otherwise·the·name·of·the·identifier·is·the·single·character·following	50	····*·Otherwise·the·name·of·the·identifier·is·the·single·character·following
51	······the·delimiter	51	······the·delimiter
52	For·each·substring·matching·the·rules·above,·theSubstitutesubprogram·will·look	52	For·each·substring·matching·the·rules·above,·theSubstitutesubprogram·will·look
53	for·possible·replacement·text·in·the·following·order:	53	for·possible·replacement·text·in·the·following·order:
54	····*·If·theSubstringsparameter·contains·an·entry·for·that·name,·the	54	····*·If·theSubstringsparameter·contains·an·entry·for·that·name,·the
55	······corresponding·value·is·used.	55	······corresponding·value·is·used.
56	····*·Otherwise,·if·acallbackwas·specified,·it·is·called·with·the·name·of·the	56	····*·Otherwise,·if·acallbackwas·specified,·it·is·called·with·the·name·of·the


Offset 41, 40 lines modified		Offset 41, 40 lines modified
41	··········<div·class="body"·role="main">	41	··········<div·class="body"·role="main">
42	············	42	············
43	··<div·class="section"·id="traces-logging-information">	43	··<div·class="section"·id="traces-logging-information">
44	<span·id="logging-information"></span><h1><span·class="section-number">4.·</span><strong>Traces</strong>:·Logging·information<a·class="headerlink"·href="#traces-logging-information"·title="Permalink·to·this·headline">¶</a></h1>	44	<span·id="logging-information"></span><h1><span·class="section-number">4.·</span><strong>Traces</strong>:·Logging·information<a·class="headerlink"·href="#traces-logging-information"·title="Permalink·to·this·headline">¶</a></h1>
45	<p>Most·applications·need·to·log·various·kinds·of·information:·error·messages,	45	<p>Most·applications·need·to·log·various·kinds·of·information:·error·messages,
46	information·messages·or·debug·messages·among·others.·These·logs·can·be	46	information·messages·or·debug·messages·among·others.·These·logs·can·be
47	displayed·and·stored·in·a·number·of·places:·standard·output,·a·file,·the	47	displayed·and·stored·in·a·number·of·places:·standard·output,·a·file,·the
48	system·logger,·an·application-specific·database·table,...</p>	48	system·logger,·an·application-specific·database·table,…</p>
49	<p>The·package·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Traces</span></code>·addresses·the·various·needs,·except·for·the	49	<p>The·package·<code·class="file·docutils·literal·notranslate"><span·class="pre">GNATCOLL.Traces</span></code>·addresses·the·various·needs,·except·for·the
50	application-specific·database,·which·of·course·is·specific·to·your·business	50	application-specific·database,·which·of·course·is·specific·to·your·business
51	and·needs·various·custom·fields·in·any·case,·which·cannot·be·easily·provided	51	and·needs·various·custom·fields·in·any·case,·which·cannot·be·easily·provided
52	through·a·general·interface.</p>	52	through·a·general·interface.</p>
53	<p>This·module·is·organized·around·two·tagged·types·(used·through·access·types,	53	<p>This·module·is·organized·around·two·tagged·types·(used·through·access·types,
54	in·fact,·so·the·latter·are·mentioned·below·as·a·shortcut):</p>	54	in·fact,·so·the·latter·are·mentioned·below·as·a·shortcut):</p>
55	<dl·class="simple">	55	<dl·class="simple">
56	<dt><em>Trace_Handle</em></dt><dd><p>This·type·defines·a·handle·(similar·to·a·file·descriptor·in·other·contexts)	56	<dt><em>Trace_Handle</em></dt><dd><p>This·type·defines·a·handle·(similar·to·a·file·descriptor·in·other·contexts)
57	which·is·latter·used·to·output·messages.·An·application·will·generally	57	which·is·latter·used·to·output·messages.·An·application·will·generally
58	define·several·handles,·which·can·be·enabled·or·disabled·separately,·therefore	58	define·several·handles,·which·can·be·enabled·or·disabled·separately,·therefore
59	limiting·the·amount·of·logging.</p>	59	limiting·the·amount·of·logging.</p>
60	</dd>	60	</dd>
61	<dt><em>Trace_Stream</em></dt><dd><p>Streams·are·the·ultimate·types·responsible·for·the·output·of·the·messages.	61	<dt><em>Trace_Stream</em></dt><dd><p>Streams·are·the·ultimate·types·responsible·for·the·output·of·the·messages.
62	One·or·more·handles·are·associated·with·each·stream.·The·latter·can·be·a·file,	62	One·or·more·handles·are·associated·with·each·stream.·The·latter·can·be·a·file,
63	the·standard·output,·a·graphical·window,·a·socket,...·New·types·of·streams	63	the·standard·output,·a·graphical·window,·a·socket,…·New·types·of·streams
64	can·easily·be·defined·in·your·application.</p>	64	can·easily·be·defined·in·your·application.</p>
65	</dd>	65	</dd>
66	</dl>	66	</dl>
67	<div·class="section"·id="configuring-traces">	67	<div·class="section"·id="configuring-traces">
68	<span·id="id1"></span><h2><span·class="section-number">4.1.·</span>Configuring·traces<a·class="headerlink"·href="#configuring-traces"·title="Permalink·to·this·headline">¶</a></h2>	68	<span·id="id1"></span><h2><span·class="section-number">4.1.·</span>Configuring·traces<a·class="headerlink"·href="#configuring-traces"·title="Permalink·to·this·headline">¶</a></h2>
69	<p>As·mentioned·above,·an·application·will·generally·create·several	69	<p>As·mentioned·above,·an·application·will·generally·create·several
70	<cite>Trace_Handle</cite>·(typically·one·per·module·in·the·application).·When	70	<cite>Trace_Handle</cite>·(typically·one·per·module·in·the·application).·When
71	new·features·are·added·to·the·application,·the·developers·will·generally	71	new·features·are·added·to·the·application,·the·developers·will·generally
72	need·to·add·lots·of·traces·to·help·investigate·problems·once·the·application	72	need·to·add·lots·of·traces·to·help·investigate·problems·once·the·application
73	is·installed·at·a·customer's·site.·The·problem·here·is·that·each·module	73	is·installed·at·a·customer’s·site.·The·problem·here·is·that·each·module
74	might·output·a·lot·of·information,·thus·confusing·the·logs;·this·also·does	74	might·output·a·lot·of·information,·thus·confusing·the·logs;·this·also·does
75	not·help·debugging.</p>	75	not·help·debugging.</p>
76	<p>The·<cite>GNATCOLL.Traces</cite>·package·allows·the·user·to·configure·which·handles	76	<p>The·<cite>GNATCOLL.Traces</cite>·package·allows·the·user·to·configure·which·handles
77	should·actually·generate·logs,·and·which·should·just·be·silent·and·not	77	should·actually·generate·logs,·and·which·should·just·be·silent·and·not
78	generate·anything.·Depending·on·the·part·of·the·application·that·needs·to	78	generate·anything.·Depending·on·the·part·of·the·application·that·needs·to
79	be·investigated,·one·can·therefore·enable·a·set·of·handles·or·another,·to	79	be·investigated,·one·can·therefore·enable·a·set·of·handles·or·another,·to
80	be·able·to·concentrate·on·that·part·of·the·application.</p>	80	be·able·to·concentrate·on·that·part·of·the·application.</p>
Offset 93, 70 lines modified		Offset 93, 70 lines modified
93	<cite>Parse_Config_File</cite>.</p>	93	<cite>Parse_Config_File</cite>.</p>
94	</li>	94	</li>
95	<li·id="index-0"><p>If·no·file·name·was·specified·in·that·call,·the·environment·variable	95	<li·id="index-0"><p>If·no·file·name·was·specified·in·that·call,·the·environment·variable
96	<cite>ADA_DEBUG_FILE</cite>·might·point·to·a·configuration·file.</p>	96	<cite>ADA_DEBUG_FILE</cite>·might·point·to·a·configuration·file.</p>
97	</li>	97	</li>
98	<li·id="index-1"><p>If·the·above·two·attempts·did·not·find·a·suitable·configuration·file,	98	<li·id="index-1"><p>If·the·above·two·attempts·did·not·find·a·suitable·configuration·file,
99	the·current·directory·is·searched·for·a·file·called·<cite>.gnatdebug</cite>.	99	the·current·directory·is·searched·for·a·file·called·<cite>.gnatdebug</cite>.
100	Finally,·the·user's·home·directory·will·also·be·searched·for·that·file.</p></li>	100	Finally,·the·user’s·home·directory·will·also·be·searched·for·that·file.</p></li>
101	</ul>	101	</ul>
102	<p>In·all·cases,·the·format·of·the·configuration·file·is·the·same.·Its·goal·is	102	<p>In·all·cases,·the·format·of·the·configuration·file·is·the·same.·Its·goal·is
103	to·associate·the·name·of·a·<cite>trace_handle</cite>·with·the·name·of·a	103	to·associate·the·name·of·a·<cite>trace_handle</cite>·with·the·name·of·a
104	<cite>trace_stream</cite>·on·which·it·should·be·displayed.</p>	104	<cite>trace_stream</cite>·on·which·it·should·be·displayed.</p>
105	<p>Streams·are·identified·by·a·name.·You·can·provide·additional·streams·by	105	<p>Streams·are·identified·by·a·name.·You·can·provide·additional·streams·by
106	creating·a·new·tagged·object·(<a·class="reference·internal"·href="#defining-custom-stream-types"><span·class="std·std-ref">Defining·custom·stream·types</span></a>).·Here·are	106	creating·a·new·tagged·object·(<a·class="reference·internal"·href="#defining-custom-stream-types"><span·class="std·std-ref">Defining·custom·stream·types</span></a>).·Here·are
107	the·various·possibilities·to·reference·a·stream:</p>	107	the·various·possibilities·to·reference·a·stream:</p>
108	<dl·class="simple">	108	<dl·class="simple">
109	<dt><em>~~&quot~~;name~~&quot~~;</em></dt><dd><p>where·name·is·a·string·made·of·letters,·digits·and·slash·('/')·characters.	109	<dt><em>“name”</em></dt><dd><p>where·name·is·a·string·made·of·letters,·digits·and·slash·(‘/’)·characters.
110	This·is·the·name·of·a·file·to·which·the·traces·should·be·redirected.·The	110	This·is·the·name·of·a·file·to·which·the·traces·should·be·redirected.·The
111	previous·contents·of·the·file·is·discarded.·If·the·name·of·the·file·is·a	111	previous·contents·of·the·file·is·discarded.·If·the·name·of·the·file·is·a
112	relative·path,·it·is·relative·to·the·location·of·the·configuration·file,·not	112	relative·path,·it·is·relative·to·the·location·of·the·configuration·file,·not
113	necessarily·to·the·current·directory·when·the·file·is·parsed.	113	necessarily·to·the·current·directory·when·the·file·is·parsed.
114	In·the·file·name,·<cite>$$</cite>·is·automatically·replaced·by·the·process·number.	114	In·the·file·name,·<cite>$$</cite>·is·automatically·replaced·by·the·process·number.
115	<cite>$D</cite>·is·automatically·replaced·by·the·current·date.·<cite>$T</cite>·is·automatically	115	<cite>$D</cite>·is·automatically·replaced·by·the·current·date.·<cite>$T</cite>·is·automatically
116	replaced·by·the·current·date·and·time.·Other·patterns·of·the·form·<cite>$name</cite>,	116	replaced·by·the·current·date·and·time.·Other·patterns·of·the·form·<cite>$name</cite>,
117	<cite>${name}</cite>,·or·<cite>$(name)</cite>·are·substituted·with·the·value·of·the·named·environment	117	<cite>${name}</cite>,·or·<cite>$(name)</cite>·are·substituted·with·the·value·of·the·named·environment
118	variable,·if·it·exists.·If·~~&quot~~;>>~~&quot~~;·is·used·instead·of·~~&quot~~;>~~&quot~~;·to·redirect·to·that	118	variable,·if·it·exists.·If·“>>”·is·used·instead·of·“>”·to·redirect·to·that
119	stream,·the·file·is·appended·to,·instead·of·truncated.</p>	119	stream,·the·file·is·appended·to,·instead·of·truncated.</p>
120	</dd>	120	</dd>
121	<dt><em>~~&quot~~;&1~~&quot~~;</em></dt><dd><p>This·syntax·is·similar·to·the·one·used·on·Unix·shells,·and·indicates·that	121	<dt><em>“&1”</em></dt><dd><p>This·syntax·is·similar·to·the·one·used·on·Unix·shells,·and·indicates·that
122	the·output·should·be·displayed·on·the·standard·output·for·the·application.	122	the·output·should·be·displayed·on·the·standard·output·for·the·application.
123	If·the·application·is·graphical,·and·in·particular·on·Windows·platforms,·it	123	If·the·application·is·graphical,·and·in·particular·on·Windows·platforms,·it
124	is·possible·that·there·is·no·standard·output!</p>	124	is·possible·that·there·is·no·standard·output!</p>
125	</dd>	125	</dd>
126	<dt><em>~~&quot~~;&2~~&quot~~;</em></dt><dd><p>Similar·to·the·previous·one,·but·the·output·is·sent·to·standard·error.</p>	126	<dt><em>“&2”</em></dt><dd><p>Similar·to·the·previous·one,·but·the·output·is·sent·to·standard·error.</p>
127	</dd>	127	</dd>
128	<dt><em>~~&quot~~;&syslog~~&quot~~;</em></dt><dd><p><a·class="reference·internal"·href="#logging-to-syslog"><span·class="std·std-ref">Logging·to·syslog</span></a>.</p>	128	<dt><em>“&syslog”</em></dt><dd><p><a·class="reference·internal"·href="#logging-to-syslog"><span·class="std·std-ref">Logging·to·syslog</span></a>.</p>
129	</dd>	129	</dd>
130	</dl>	130	</dl>
131	<p>Comments·in·a·configuration·file·must·be·on·a·line·of·their·own,·and·start	131	<p>Comments·in·a·configuration·file·must·be·on·a·line·of·their·own,·and·start
132	with·<cite>--</cite>.·Empty·lines·are·ignored.·The·rest·of·the·lines·represent	132	with·<cite>–</cite>.·Empty·lines·are·ignored.·The·rest·of·the·lines·represent
133	configurations,·as·in:</p>	133	configurations,·as·in:</p>
134	<ul>	134	<ul>
135	<li><p>If·a·line·contains·the·single·character·<cite>~~&quot~~;+~~&quot~~;</cite>,·it·activates·all	135	<li><p>If·a·line·contains·the·single·character·<cite>“+”</cite>,·it·activates·all
136	<cite>trace_handle</cite>·by·default.·This·means·the·rest·of·the·configuration	136	<cite>trace_handle</cite>·by·default.·This·means·the·rest·of·the·configuration
137	file·should·disable·those·handles·that·are·not·needed.·The·default·is·that	137	file·should·disable·those·handles·that·are·not·needed.·The·default·is·that
138	all·handles·are·disabled·by·default,·and·the·configuration·file·should	138	all·handles·are·disabled·by·default,·and·the·configuration·file·should
139	activate·the·ones·it·needs.·The·Ada·source·code·can·change·the·default	139	activate·the·ones·it·needs.·The·Ada·source·code·can·change·the·default
140	status·of·each·handles,·as·well</p></li>	140	status·of·each·handles,·as·well</p></li>
141	<li><p>If·the·line·starts·with·the·character·<cite>~~&quot~~;>~~&quot~~;</cite>,·followed·by·a	141	<li><p>If·the·line·starts·with·the·character·<cite>“>”</cite>,·followed·by·a
142	stream·name·(as·defined·above),·this·becomes·the·default·stream.·All·handles	142	stream·name·(as·defined·above),·this·becomes·the·default·stream.·All·handles
143	will·be·displayed·on·that·stream,·unless·otherwise·specified.·If·the·stream	143	will·be·displayed·on·that·stream,·unless·otherwise·specified.·If·the·stream
144	does·not·exist,·it·defaults·to·standard·output.</p></li>	144	does·not·exist,·it·defaults·to·standard·output.</p></li>
145	<li><p>Otherwise,·the·first·token·on·the·line·is·the·name·of·a·handle.	145	<li><p>Otherwise,·the·first·token·on·the·line·is·the·name·of·a·handle.
146	If·that·is·the·only·element·on·the·line,·the·handle·is·activated,·and·will	146	If·that·is·the·only·element·on·the·line,·the·handle·is·activated,·and·will
147	be·displayed·on·the·default·stream.</p>	147	be·displayed·on·the·default·stream.</p>
148	<p>Otherwise,·the·next·element·on·the·line·should·be·a·<cite>~~&quot~~;=~~&quot~~;</cite>·sign,	148	<p>Otherwise,·the·next·element·on·the·line·should·be·a·<cite>“=”</cite>·sign,
149	followed·by·either·<cite>~~&quot~~;yes~~&quot~~;</cite>·or·<cite>~~&quot~~;n~~o&qu~~ot;</cite>,·depending·on·whether·the	149	followed·by·either·<cite>“yes”</cite>·or·<cite>“no”</cite>,·depending·on·whether·the
150	handle·should·resp.·be·enabled·or·disabled.</p>	150	handle·should·resp.·be·enabled·or·disabled.</p>
151	<p>Finally,·the·rest·of·the·line·can·optionally·contain·the·<cite>~~&quot~~;>~~&quot~~;</cite>	151	<p>Finally,·the·rest·of·the·line·can·optionally·contain·the·<cite>“>”</cite>
152	character·followed·by·the·name·of·the·stream·to·which·the·handle·should	152	character·followed·by·the·name·of·the·stream·to·which·the·handle·should
153	be·directed.</p>	153	be·directed.</p>
154	<p>There·is·are·two·special·cases·for·the·names·on·this·line:·they·can	154	<p>There·is·are·two·special·cases·for·the·names·on·this·line:·they·can
155	start·with·either·<cite>~~&quot~~;.~~&quot~~;</cite>·or·<cite>~~&quot~~;.~~&quot~~;</cite>·to·indicate·the·settings·apply·to·a	155	start·with·either·<cite>“.”</cite>·or·<cite>“.”</cite>·to·indicate·the·settings·apply·to·a
156	whole·set·of·handles.·See·the·example·below.</p>	156	whole·set·of·handles.·See·the·example·below.</p>
157	</li>	157	</li>
158	</ul>	158	</ul>
159	<p>Here·is·a·short·example·of·a·configuration·file.·It·activates·all·handles	159	<p>Here·is·a·short·example·of·a·configuration·file.·It·activates·all·handles
160	by·default,·and·defines·four·handles:·two·of·them·are·directed·to·the	160	by·default,·and·defines·four·handles:·two·of·them·are·directed·to·the
161	default·stream·(standard·error),·the·third·one·to·a·file·on·the·disk,	161	default·stream·(standard·error),·the·third·one·to·a·file·on·the·disk,
162	and·the·last·one·to·the·system·logger·syslog·(if·your·system·supports·it,	162	and·the·last·one·to·the·system·logger·syslog·(if·your·system·supports·it,
Offset 297, 15 lines modified		Offset 297, 15 lines modified
297	</div>	297	</div>
298	<div·class="section"·id="log-decorators">	298	<div·class="section"·id="log-decorators">
299	<span·id="id3"></span><h2><span·class="section-number">4.3.·</span>Log·decorators<a·class="headerlink"·href="#log-decorators"·title="Permalink·to·this·headline">¶</a></h2>	299	<span·id="id3"></span><h2><span·class="section-number">4.3.·</span>Log·decorators<a·class="headerlink"·href="#log-decorators"·title="Permalink·to·this·headline">¶</a></h2>
300	<p·id="index-4">Speaking·of·color,·a·number·of·decorators·are·defined·by	300	<p·id="index-4">Speaking·of·color,·a·number·of·decorators·are·defined·by
301	<cite>GNATCOLL.Traces</cite>.·Their·goal·is·not·to·be·used·for·outputting·information,	301	<cite>GNATCOLL.Traces</cite>.·Their·goal·is·not·to·be·used·for·outputting·information,
302	but·to·configure·what·extra·information·should·be·output·with·all·log	302	but·to·configure·what·extra·information·should·be·output·with·all·log
303	messages.·They·are·activated·through·the·same·configuration·file·as·the	303	messages.·They·are·activated·through·the·same·configuration·file·as·the
304	traces,·with·the·same·syntax·(i.e·either·<cite>~~&quot~~;=yes~~&quot~~;</cite>·or·<cite>~~&quot~~;=n~~o&qu~~ot;</cite>).</p>	304	traces,·with·the·same·syntax·(i.e·either·<cite>“=yes”</cite>·or·<cite>“=no”</cite>).</p>
305	<p>Here·is·an·exhaustive·list:</p>	305	<p>Here·is·an·exhaustive·list:</p>
306	<dl·class="simple">	306	<dl·class="simple">
307	<dt><em>DEBUG.ABSOLUTE_TIME</em></dt><dd><p>If·this·decorator·is·activated·in·the·configuration·file,·the·absolute·time	307	<dt><em>DEBUG.ABSOLUTE_TIME</em></dt><dd><p>If·this·decorator·is·activated·in·the·configuration·file,·the·absolute·time
308	when·Trace·is·called·is·automatically·added·to·the·output,·when·the	308	when·Trace·is·called·is·automatically·added·to·the·output,·when·the
309	streams·supports·it·(in·particular,·this·has·no·effect·for·syslog,·which	309	streams·supports·it·(in·particular,·this·has·no·effect·for·syslog,·which
310	already·does·this·on·its·own).</p>	310	already·does·this·on·its·own).</p>
311	</dd>	311	</dd>
Max diff block lines reached; 10199/20357 bytes (50.10%) of diff not shown.


Offset 12, 36 lines modified		Offset 12, 36 lines modified
12	····*·previous·\|	12	····*·previous·\|
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·4.·Traces:·Logging·information	14	····*·4.·Traces:·Logging·information
15	****·4.·Traces:·Logging·informationÂ¶·****	15	****·4.·Traces:·Logging·informationÂ¶·****
16	Most·applications·need·to·log·various·kinds·of·information:·error·messages,	16	Most·applications·need·to·log·various·kinds·of·information:·error·messages,
17	information·messages·or·debug·messages·among·others.·These·logs·can·be	17	information·messages·or·debug·messages·among·others.·These·logs·can·be
18	displayed·and·stored·in·a·number·of·places:·standard·output,·a·file,·the·system	18	displayed·and·stored·in·a·number·of·places:·standard·output,·a·file,·the·system
19	logger,·an·application-specific·database·table,~~...~~	19	logger,·an·application-specific·database·table,â¦
20	The·package·GNATCOLL.Traces·addresses·the·various·needs,·except·for·the	20	The·package·GNATCOLL.Traces·addresses·the·various·needs,·except·for·the
21	application-specific·database,·which·of·course·is·specific·to·your·business·and	21	application-specific·database,·which·of·course·is·specific·to·your·business·and
22	needs·various·custom·fields·in·any·case,·which·cannot·be·easily·provided	22	needs·various·custom·fields·in·any·case,·which·cannot·be·easily·provided
23	through·a·general·interface.	23	through·a·general·interface.
24	This·module·is·organized·around·two·tagged·types·(used·through·access·types,·in	24	This·module·is·organized·around·two·tagged·types·(used·through·access·types,·in
25	fact,·so·the·latter·are·mentioned·below·as·a·shortcut):	25	fact,·so·the·latter·are·mentioned·below·as·a·shortcut):
26	··Trace_Handle	26	··Trace_Handle
27	······This·type·defines·a·handle·(similar·to·a·file·descriptor·in·other	27	······This·type·defines·a·handle·(similar·to·a·file·descriptor·in·other
28	······contexts)·which·is·latter·used·to·output·messages.·An·application·will	28	······contexts)·which·is·latter·used·to·output·messages.·An·application·will
29	······generally·define·several·handles,·which·can·be·enabled·or·disabled	29	······generally·define·several·handles,·which·can·be·enabled·or·disabled
30	······separately,·therefore·limiting·the·amount·of·logging.	30	······separately,·therefore·limiting·the·amount·of·logging.
31	··Trace_Stream	31	··Trace_Stream
32	······Streams·are·the·ultimate·types·responsible·for·the·output·of·the	32	······Streams·are·the·ultimate·types·responsible·for·the·output·of·the
33	······messages.·One·or·more·handles·are·associated·with·each·stream.·The·latter	33	······messages.·One·or·more·handles·are·associated·with·each·stream.·The·latter
34	······can·be·a·file,·the·standard·output,·a·graphical·window,·a·socket,~~...~~·New	34	······can·be·a·file,·the·standard·output,·a·graphical·window,·a·socket,â¦·New
35	······types·of·streams·can·easily·be·defined·in·your·application.	35	······types·of·streams·can·easily·be·defined·in·your·application.
36	***·4.1.·Configuring·tracesÂ¶·***	36	***·4.1.·Configuring·tracesÂ¶·***
37	As·mentioned·above,·an·application·will·generally·create·severalTrace_Handle	37	As·mentioned·above,·an·application·will·generally·create·severalTrace_Handle
38	(typically·one·per·module·in·the·application).·When·new·features·are·added·to	38	(typically·one·per·module·in·the·application).·When·new·features·are·added·to
39	the·application,·the·developers·will·generally·need·to·add·lots·of·traces·to	39	the·application,·the·developers·will·generally·need·to·add·lots·of·traces·to
40	help·investigate·problems·once·the·application·is·installed·at·a·customer's	40	help·investigate·problems·once·the·application·is·installed·at·a·customerâs
41	site.·The·problem·here·is·that·each·module·might·output·a·lot·of·information,	41	site.·The·problem·here·is·that·each·module·might·output·a·lot·of·information,
42	thus·confusing·the·logs;·this·also·does·not·help·debugging.	42	thus·confusing·the·logs;·this·also·does·not·help·debugging.
43	TheGNATCOLL.Tracespackage·allows·the·user·to·configure·which·handles·should	43	TheGNATCOLL.Tracespackage·allows·the·user·to·configure·which·handles·should
44	actually·generate·logs,·and·which·should·just·be·silent·and·not·generate	44	actually·generate·logs,·and·which·should·just·be·silent·and·not·generate
45	anything.·Depending·on·the·part·of·the·application·that·needs·to·be	45	anything.·Depending·on·the·part·of·the·application·that·needs·to·be
46	investigated,·one·can·therefore·enable·a·set·of·handles·or·another,·to·be·able	46	investigated,·one·can·therefore·enable·a·set·of·handles·or·another,·to·be·able
47	to·concentrate·on·that·part·of·the·application.	47	to·concentrate·on·that·part·of·the·application.
Offset 54, 68 lines modified		Offset 54, 68 lines modified
54	The·configuration·file·is·found·in·one·of·three·places,·in·the·following·order:	54	The·configuration·file·is·found·in·one·of·three·places,·in·the·following·order:
55	····*·The·file·name·is·specified·in·the·source·code·in·the·call	55	····*·The·file·name·is·specified·in·the·source·code·in·the·call
56	······toParse_Config_File.	56	······toParse_Config_File.
57	····*·If·no·file·name·was·specified·in·that·call,·the·environment	57	····*·If·no·file·name·was·specified·in·that·call,·the·environment
58	······variableADA_DEBUG_FILEmight·point·to·a·configuration·file.	58	······variableADA_DEBUG_FILEmight·point·to·a·configuration·file.
59	····*·If·the·above·two·attempts·did·not·find·a·suitable·configuration·file,·the	59	····*·If·the·above·two·attempts·did·not·find·a·suitable·configuration·file,·the
60	······current·directory·is·searched·for·a·file·called.gnatdebug.·Finally,·the	60	······current·directory·is·searched·for·a·file·called.gnatdebug.·Finally,·the
61	······user's·home·directory·will·also·be·searched·for·that·file.	61	······userâs·home·directory·will·also·be·searched·for·that·file.
62	In·all·cases,·the·format·of·the·configuration·file·is·the·same.·Its·goal·is·to	62	In·all·cases,·the·format·of·the·configuration·file·is·the·same.·Its·goal·is·to
63	associate·the·name·of·atrace_handlewith·the·name·of·atrace_streamon·which·it	63	associate·the·name·of·atrace_handlewith·the·name·of·atrace_streamon·which·it
64	should·be·displayed.	64	should·be·displayed.
65	Streams·are·identified·by·a·name.·You·can·provide·additional·streams·by	65	Streams·are·identified·by·a·name.·You·can·provide·additional·streams·by
66	creating·a·new·tagged·object·(Defining_custom_stream_types).·Here·are·the	66	creating·a·new·tagged·object·(Defining_custom_stream_types).·Here·are·the
67	various·possibilities·to·reference·a·stream:	67	various·possibilities·to·reference·a·stream:
68	··"name"	68	··ânameâ
69	······where·name·is·a·string·made·of·letters,·digits·and·slash·('/')	69	······where·name·is·a·string·made·of·letters,·digits·and·slash·(â/â)
70	······characters.·This·is·the·name·of·a·file·to·which·the·traces·should·be	70	······characters.·This·is·the·name·of·a·file·to·which·the·traces·should·be
71	······redirected.·The·previous·contents·of·the·file·is·discarded.·If·the·name	71	······redirected.·The·previous·contents·of·the·file·is·discarded.·If·the·name
72	······of·the·file·is·a·relative·path,·it·is·relative·to·the·location·of·the	72	······of·the·file·is·a·relative·path,·it·is·relative·to·the·location·of·the
73	······configuration·file,·not·necessarily·to·the·current·directory·when·the	73	······configuration·file,·not·necessarily·to·the·current·directory·when·the
74	······file·is·parsed.·In·the·file·name,$$is·automatically·replaced·by·the	74	······file·is·parsed.·In·the·file·name,$$is·automatically·replaced·by·the
75	······process·number.$Dis·automatically·replaced·by·the·current·date.$Tis	75	······process·number.$Dis·automatically·replaced·by·the·current·date.$Tis
76	······automatically·replaced·by·the·current·date·and·time.·Other·patterns·of	76	······automatically·replaced·by·the·current·date·and·time.·Other·patterns·of
77	······the·form$name,${name},·or$(name)are·substituted·with·the·value·of·the	77	······the·form$name,${name},·or$(name)are·substituted·with·the·value·of·the
78	······named·environment·variable,·if·it·exists.·If·">>"·is·used·instead·of~~·">"~~	78	······named·environment·variable,·if·it·exists.·If·â>>â·is·used·instead·of
79	······to·redirect·to·that·stream,·the·file·is·appended·to,·instead·of	79	······â>â·to·redirect·to·that·stream,·the·file·is·appended·to,·instead·of
80	······truncated.	80	······truncated.
81	··"&1"	81	··â&1â
82	······This·syntax·is·similar·to·the·one·used·on·Unix·shells,·and·indicates·that	82	······This·syntax·is·similar·to·the·one·used·on·Unix·shells,·and·indicates·that
83	······the·output·should·be·displayed·on·the·standard·output·for·the	83	······the·output·should·be·displayed·on·the·standard·output·for·the
84	······application.·If·the·application·is·graphical,·and·in·particular·on	84	······application.·If·the·application·is·graphical,·and·in·particular·on
85	······Windows·platforms,·it·is·possible·that·there·is·no·standard·output!	85	······Windows·platforms,·it·is·possible·that·there·is·no·standard·output!
86	··"&2"	86	··â&2â
87	······Similar·to·the·previous·one,·but·the·output·is·sent·to·standard·error.	87	······Similar·to·the·previous·one,·but·the·output·is·sent·to·standard·error.
88	··"&syslog"	88	··â&syslogâ
89	······Logging_to_syslog.	89	······Logging_to_syslog.
90	Comments·in·a·configuration·file·must·be·on·a·line·of·their·own,·and·start	90	Comments·in·a·configuration·file·must·be·on·a·line·of·their·own,·and·start
91	with--.·Empty·lines·are·ignored.·The·rest·of·the·lines·represent	91	withâ.·Empty·lines·are·ignored.·The·rest·of·the·lines·represent
92	configurations,·as·in:	92	configurations,·as·in:
93	····*·If·a·line·contains·the·single·character"+",·it·activates	93	····*·If·a·line·contains·the·single·characterâ+â,·it·activates
94	······alltrace_handleby·default.·This·means·the·rest·of·the·configuration·file	94	······alltrace_handleby·default.·This·means·the·rest·of·the·configuration·file
95	······should·disable·those·handles·that·are·not·needed.·The·default·is·that·all	95	······should·disable·those·handles·that·are·not·needed.·The·default·is·that·all
96	······handles·are·disabled·by·default,·and·the·configuration·file·should	96	······handles·are·disabled·by·default,·and·the·configuration·file·should
97	······activate·the·ones·it·needs.·The·Ada·source·code·can·change·the·default	97	······activate·the·ones·it·needs.·The·Ada·source·code·can·change·the·default
98	······status·of·each·handles,·as·well	98	······status·of·each·handles,·as·well
99	····*·If·the·line·starts·with·the·character">",·followed·by·a·stream·name~~·(as~~	99	····*·If·the·line·starts·with·the·characterâ>â,·followed·by·a·stream·name
100	······defined·above),·this·becomes·the·default·stream.·All·handles·will·be	100	······(as·defined·above),·this·becomes·the·default·stream.·All·handles·will·be
101	······displayed·on·that·stream,·unless·otherwise·specified.·If·the·stream·does	101	······displayed·on·that·stream,·unless·otherwise·specified.·If·the·stream·does
102	······not·exist,·it·defaults·to·standard·output.	102	······not·exist,·it·defaults·to·standard·output.
103	····*·Otherwise,·the·first·token·on·the·line·is·the·name·of·a·handle.·If·that	103	····*·Otherwise,·the·first·token·on·the·line·is·the·name·of·a·handle.·If·that
104	······is·the·only·element·on·the·line,·the·handle·is·activated,·and·will·be	104	······is·the·only·element·on·the·line,·the·handle·is·activated,·and·will·be
105	······displayed·on·the·default·stream.	105	······displayed·on·the·default·stream.
106	······Otherwise,·the·next·element·on·the·line·should·be·a"="sign,·followed~~·by~~	106	······Otherwise,·the·next·element·on·the·line·should·be·aâ=âsign,·followed
107	······either"yes"or"no",·depending·on·whether·the·handle·should~~·resp.·be~~	107	······by·eitherâyesâorânoâ,·depending·on·whether·the·handle·should
108	······enabled·or·disabled.	108	······resp.·be·enabled·or·disabled.
109	······Finally,·the·rest·of·the·line·can·optionally·contain·the">"character	109	······Finally,·the·rest·of·the·line·can·optionally·contain·theâ>âcharacter
110	······followed·by·the·name·of·the·stream·to·which·the·handle·should·be	110	······followed·by·the·name·of·the·stream·to·which·the·handle·should·be
111	······directed.	111	······directed.
112	······There·is·are·two·special·cases·for·the·names·on·this·line:·they·can·start	112	······There·is·are·two·special·cases·for·the·names·on·this·line:·they·can·start
113	······with·either"."or"."to·indicate·the·settings·apply·to·a·whol~~e·s~~e~~t·of~~	113	······with·eitherâ.âorâ.âto·indicate·the·settings·apply·to·a·whole
114	······handles.·See·the·example·below.	114	······set·of·handles.·See·the·example·below.
115	Here·is·a·short·example·of·a·configuration·file.·It·activates·all·handles·by	115	Here·is·a·short·example·of·a·configuration·file.·It·activates·all·handles·by
116	default,·and·defines·four·handles:·two·of·them·are·directed·to·the·default	116	default,·and·defines·four·handles:·two·of·them·are·directed·to·the·default
117	stream·(standard·error),·the·third·one·to·a·file·on·the·disk,·and·the·last·one	117	stream·(standard·error),·the·third·one·to·a·file·on·the·disk,·and·the·last·one
118	to·the·system·logger·syslog·(if·your·system·supports·it,·otherwise·to·the	118	to·the·system·logger·syslog·(if·your·system·supports·it,·otherwise·to·the
119	default·stream,·ie·standard·error):	119	default·stream,·ie·standard·error):
120	+	120	+
121	>&2	121	>&2
Offset 226, 15 lines modified		Offset 226, 15 lines modified
226	···Trace·(Me,·A·&·B·&·C·&·D·&·E);	226	···Trace·(Me,·A·&·B·&·C·&·D·&·E);
227	end·if;	227	end·if;
228	***·4.3.·Log·decoratorsÂ¶·***	228	***·4.3.·Log·decoratorsÂ¶·***
229	Speaking·of·color,·a·number·of·decorators·are·defined·byGNATCOLL.Traces.·Their	229	Speaking·of·color,·a·number·of·decorators·are·defined·byGNATCOLL.Traces.·Their
230	goal·is·not·to·be·used·for·outputting·information,·but·to·configure·what·extra	230	goal·is·not·to·be·used·for·outputting·information,·but·to·configure·what·extra
231	information·should·be·output·with·all·log·messages.·They·are·activated·through	231	information·should·be·output·with·all·log·messages.·They·are·activated·through
232	the·same·configuration·file·as·the·traces,·with·the·same·syntax·(i.e	232	the·same·configuration·file·as·the·traces,·with·the·same·syntax·(i.e
233	either"=yes"or"=no").	233	eitherâ=yesâorâ=noâ).
234	Here·is·an·exhaustive·list:	234	Here·is·an·exhaustive·list:
235	··DEBUG.ABSOLUTE_TIME	235	··DEBUG.ABSOLUTE_TIME
236	······If·this·decorator·is·activated·in·the·configuration·file,·the·absolute	236	······If·this·decorator·is·activated·in·the·configuration·file,·the·absolute
237	······time·when·Trace·is·called·is·automatically·added·to·the·output,·when·the	237	······time·when·Trace·is·called·is·automatically·added·to·the·output,·when·the
238	······streams·supports·it·(in·particular,·this·has·no·effect·for·syslog,·which	238	······streams·supports·it·(in·particular,·this·has·no·effect·for·syslog,·which
239	······already·does·this·on·its·own).	239	······already·does·this·on·its·own).
240	··DEBUG.MICRO_TIME	240	··DEBUG.MICRO_TIME
Offset 247, 21 lines modified		Offset 247, 21 lines modified
247	······If·this·decorator·is·activated,·then·the·stack·trace·is·also·displayed.	247	······If·this·decorator·is·activated,·then·the·stack·trace·is·also·displayed.
248	······It·can·be·converted·to·a·symbolic·stack·trace·through·the·use·of·the	248	······It·can·be·converted·to·a·symbolic·stack·trace·through·the·use·of·the
249	······external·applicationaddr2line,·but·that·would·be·too·costly·to·do·this	249	······external·applicationaddr2line,·but·that·would·be·too·costly·to·do·this
250	······automatically·for·each·message.	250	······automatically·for·each·message.
251	··DEBUG.LOCATION	251	··DEBUG.LOCATION
Max diff block lines reached; 7567/16504 bytes (45.85%) of diff not shown.


Offset 43, 21 lines modified		Offset 43, 21 lines modified
43	··<div·class="section"·id="tribooleans-three-state-logic">	43	··<div·class="section"·id="tribooleans-three-state-logic">
44	<span·id="three-state-logic"></span><h1><span·class="section-number">15.·</span><strong>Tribooleans</strong>:·Three·state·logic<a·class="headerlink"·href="#tribooleans-three-state-logic"·title="Permalink·to·this·headline">¶</a></h1>	44	<span·id="three-state-logic"></span><h1><span·class="section-number">15.·</span><strong>Tribooleans</strong>:·Three·state·logic<a·class="headerlink"·href="#tribooleans-three-state-logic"·title="Permalink·to·this·headline">¶</a></h1>
45	<p>Through·the·package·<cite>GNATCOLL.Tribooleans</cite>,·GNATColl·provides	45	<p>Through·the·package·<cite>GNATCOLL.Tribooleans</cite>,·GNATColl·provides
46	a·type·that·extends·the·classical·<cite>Boolean</cite>·type·with·an	46	a·type·that·extends·the·classical·<cite>Boolean</cite>·type·with·an
47	<cite>Indeterminate</cite>·value.</p>	47	<cite>Indeterminate</cite>·value.</p>
48	<p>There·are·various·cases·where·such·a·type·is·useful.·One·example·we·have	48	<p>There·are·various·cases·where·such·a·type·is·useful.·One·example·we·have
49	is·when·a·user·is·doing·a·search·(on·a·database·or·any·set·of·data),·and	49	is·when·a·user·is·doing·a·search·(on·a·database·or·any·set·of·data),·and
50	can·specify·some·optional·boolean·criteria·(~~&quot~~;must·the·contact·be·french?~~&quot~~;).	50	can·specify·some·optional·boolean·criteria·(“must·the·contact·be·french?”).
51	He·can·choose·to·only·see·french·people·(~~&quot~~;True~~&quot~~;),·to·see·no·french·people	51	He·can·choose·to·only·see·french·people·(“True”),·to·see·no·french·people
52	at·all·(~~&quot~~;False~~&quot~~;),·or·to·get·all·contacts·(~~&quot~~;Indeterminate~~&quot~~;).·With·a·classical	52	at·all·(“False”),·or·to·get·all·contacts·(“Indeterminate”).·With·a·classical
53	boolean,·there·is·no·way·to·cover·all·these·cases.</p>	53	boolean,·there·is·no·way·to·cover·all·these·cases.</p>
54	<p>Of·course,·there·are·more·advanced·use·cases·for·such·a·type.·To·support	54	<p>Of·course,·there·are·more·advanced·use·cases·for·such·a·type.·To·support
55	these·cases,·the·<cite>Tribooleans</cite>·package·overrides·the·usual·logical	55	these·cases,·the·<cite>Tribooleans</cite>·package·overrides·the·usual·logical
56	operations·<cite>~~&quot~~;and~~&quot~~;</cite>,·<cite>~~&quot~~;or~~&quot~~;</cite>,·<cite>~~&quot~~;xor~~&quot~~;</cite>,·<cite>~~&quot~~;n~~ot&qu~~ot;</cite>·and	56	operations·<cite>“and”</cite>,·<cite>“or”</cite>,·<cite>“xor”</cite>,·<cite>“not”</cite>·and
57	provides·an·<cite>Equal</cite>·function.</p>	57	provides·an·<cite>Equal</cite>·function.</p>
58	<p>See·the·specs·of·the·package·to·see·the·truth·tables·associated·with·those	58	<p>See·the·specs·of·the·package·to·see·the·truth·tables·associated·with·those
59	operators.</p>	59	operators.</p>
60	</div>	60	</div>


61	············<div·class="clearer"></div>	61	············<div·class="clearer"></div>


Offset 13, 21 lines modified		Offset 13, 21 lines modified
13	····*·GNATColl_0.0_documentation·»	13	····*·GNATColl_0.0_documentation·»
14	····*·15.·Tribooleans:·Three·state·logic	14	····*·15.·Tribooleans:·Three·state·logic
15	****·15.·Tribooleans:·Three·state·logicÂ¶·****	15	****·15.·Tribooleans:·Three·state·logicÂ¶·****
16	Through·the·packageGNATCOLL.Tribooleans,·GNATColl·provides·a·type·that·extends	16	Through·the·packageGNATCOLL.Tribooleans,·GNATColl·provides·a·type·that·extends
17	the·classicalBooleantype·with·anIndeterminatevalue.	17	the·classicalBooleantype·with·anIndeterminatevalue.
18	There·are·various·cases·where·such·a·type·is·useful.·One·example·we·have·is	18	There·are·various·cases·where·such·a·type·is·useful.·One·example·we·have·is
19	when·a·user·is·doing·a·search·(on·a·database·or·any·set·of·data),·and·can	19	when·a·user·is·doing·a·search·(on·a·database·or·any·set·of·data),·and·can
20	specify·some·optional·boolean·criteria·("must·the·contact·be·french?").·He~~·can~~	20	specify·some·optional·boolean·criteria·(âmust·the·contact·be·french?â).·He
21	choose·to·only·see·french·people·("True"),·to·see·no·french·people·at~~·all~~	21	can·choose·to·only·see·french·people·(âTrueâ),·to·see·no·french·people·at
22	("False"),·or·to·get·all·contacts·("Indeterminate").·With~~·a·classical~~·~~boole~~an,	22	all·(âFalseâ),·or·to·get·all·contacts·(âIndeterminateâ).·With·a
23	there·is·no·way·to·cover·all·these·cases.	23	classical·boolean,·there·is·no·way·to·cover·all·these·cases.
24	Of·course,·there·are·more·advanced·use·cases·for·such·a·type.·To·support·these	24	Of·course,·there·are·more·advanced·use·cases·for·such·a·type.·To·support·these
25	cases,·theTribooleanspackage·overrides·the·usual·logical	25	cases,·theTribooleanspackage·overrides·the·usual·logical
26	operations"and","or","xor","not"and·provides·anEqualfunction.	26	operationsâandâ,âorâ,âxorâ,ânotâand·provides·anEqualfunction.
27	See·the·specs·of·the·package·to·see·the·truth·tables·associated·with·those	27	See·the·specs·of·the·package·to·see·the·truth·tables·associated·with·those
28	operators.	28	operators.
29	[Logo]	29	[Logo]
30	*·Previous·topic·*	30	*·Previous·topic·*
31	14._VFS:_Manipulating_Files	31	14._VFS:_Manipulating_Files
32	*·Next·topic·*	32	*·Next·topic·*
33	16._Geometry:_primitive_geometric_operations	33	16._Geometry:_primitive_geometric_operations


Offset 67, 35 lines modified		Offset 67, 35 lines modified
67	course,·might·be·an·expansive·computation).·To·make·this·easier,	67	course,·might·be·an·expansive·computation).·To·make·this·easier,
68	GNATColl·provides·a·type·that·encapsulates·the·notion·of·a·file,	68	GNATColl·provides·a·type·that·encapsulates·the·notion·of·a·file,
69	and·removes·the·need·for·the·application·to·indicate·whether·it·needs·a	69	and·removes·the·need·for·the·application·to·indicate·whether·it·needs·a
70	full·name,·a·base·name,·or·any·other·part·of·the·file·name.</p>	70	full·name,·a·base·name,·or·any·other·part·of·the·file·name.</p>
71	<div·class="section"·id="filesystems-abstraction">	71	<div·class="section"·id="filesystems-abstraction">
72	<h2><span·class="section-number">14.1.·</span>Filesystems·abstraction<a·class="headerlink"·href="#filesystems-abstraction"·title="Permalink·to·this·headline">¶</a></h2>	72	<h2><span·class="section-number">14.1.·</span>Filesystems·abstraction<a·class="headerlink"·href="#filesystems-abstraction"·title="Permalink·to·this·headline">¶</a></h2>
73	<p>There·exists·lots·of·different·filesystems·on·all·machines.·These·include	73	<p>There·exists·lots·of·different·filesystems·on·all·machines.·These·include
74	such·things·as·FAT,·VFAT,·NTFS,·ext2,·VMS,....·However,·all·these·can	74	such·things·as·FAT,·VFAT,·NTFS,·ext2,·VMS,….·However,·all·these·can
75	be·grouped·into·three·families·of·filesystems:</p>	75	be·grouped·into·three·families·of·filesystems:</p>
76	<ul>	76	<ul>
77	<li><p>windows-based·filesystems</p>	77	<li><p>windows-based·filesystems</p>
78	<p>On·such·filesystems,·the·full·name·of·a·file·is·split·into·three·parts:·the	78	<p>On·such·filesystems,·the·full·name·of·a·file·is·split·into·three·parts:·the
79	name·of·the·drive·(c:,·d:,...),·the·directories·which·are·separated·by	79	name·of·the·drive·(c:,·d:,…),·the·directories·which·are·separated·by
80	a·backslash,·and·the·base·name.·Such·filesystems·are·sometimes·inaccurately	80	a·backslash,·and·the·base·name.·Such·filesystems·are·sometimes·inaccurately
81	said·to·be·case·insensitive:·by·that,·one·means·that·the·same·file·can·be	81	said·to·be·case·insensitive:·by·that,·one·means·that·the·same·file·can·be
82	accessed·through·various·casing.·However,·a·user·is·generally·expecting·a	82	accessed·through·various·casing.·However,·a·user·is·generally·expecting·a
83	specific·casing·when·a·file·name·is·displayed,·and·the·application·should	83	specific·casing·when·a·file·name·is·displayed,·and·the·application·should
84	strive·to·preserve·that·casing·(as·opposed·to,·for·instance,·systematically	84	strive·to·preserve·that·casing·(as·opposed·to,·for·instance,·systematically
85	convert·the·file·name·to·lower·cases).</p>	85	convert·the·file·name·to·lower·cases).</p>
86	<p>A·special·case·of·a·windows-based·filesystems·is·that·emulated·by·the	86	<p>A·special·case·of·a·windows-based·filesystems·is·that·emulated·by·the
87	cygwin·development·environment.·In·this·case,·the·filesystem·is·seen·as·if	87	cygwin·development·environment.·In·this·case,·the·filesystem·is·seen·as·if
88	it·was·unix-based·(see·below),·with·one·special·quirk·to·indicate·the·drive	88	it·was·unix-based·(see·below),·with·one·special·quirk·to·indicate·the·drive
89	letter·(the·file·name·starts·with·~~&quot~~;/cygwin/c/~~&quot~~;).</p>	89	letter·(the·file·name·starts·with·“/cygwin/c/”).</p>
90	</li>	90	</li>
91	<li><p>unix-based·filesystems</p>	91	<li><p>unix-based·filesystems</p>
92	<p>On·such·filesystems,·directories·are·separated·by·forward·slashed.·File	92	<p>On·such·filesystems,·directories·are·separated·by·forward·slashed.·File
93	names·are·case·sensitive,·that·is·a·directory·can·contain·both·~~&quot~~;foo~~&qu~~ot;·and	93	names·are·case·sensitive,·that·is·a·directory·can·contain·both·“foo”·and
94	~~&quot~~;Foo~~&qu~~ot;,·which·is·not·possible·on·windows-based·filesystems.</p>	94	“Foo”,·which·is·not·possible·on·windows-based·filesystems.</p>
95	</li>	95	</li>
96	<li><p>vms·filesystem</p>	96	<li><p>vms·filesystem</p>
97	<p>This·filesystem·represents·path·differently·than·the·other·two,·using	97	<p>This·filesystem·represents·path·differently·than·the·other·two,·using
98	brackets·to·indicate·parent·directories</p>	98	brackets·to·indicate·parent·directories</p>
99	</li>	99	</li>
100	</ul>	100	</ul>
101	<p>A·given·machine·can·actually·have·several·file·systems·in·parallel,·when	101	<p>A·given·machine·can·actually·have·several·file·systems·in·parallel,·when
Offset 109, 15 lines modified		Offset 109, 15 lines modified
109	a·set·of·tagged·types·in·the·<cite>GNATCOLL.Filesystem</cite>·package·and·its	109	a·set·of·tagged·types·in·the·<cite>GNATCOLL.Filesystem</cite>·package·and·its
110	children.·Such·a·type·has·primitive·operations·to·manipulate·the·names·of	110	children.·Such·a·type·has·primitive·operations·to·manipulate·the·names·of
111	files·(retrieving·the·base·name·from·a·full·name·for·instance),·to·check	111	files·(retrieving·the·base·name·from·a·full·name·for·instance),·to·check
112	various·attributes·of·the·file·(is·this·a·directory,·a·symbolic·link,·is·the	112	various·attributes·of·the·file·(is·this·a·directory,·a·symbolic·link,·is·the
113	file·readable·or·writable),·or·to	113	file·readable·or·writable),·or·to
114	manipulate·the·file·itself·(copying,·deleting,·reading·and·writing).	114	manipulate·the·file·itself·(copying,·deleting,·reading·and·writing).
115	It·provides·similar·operations·for·directories·(creating·or·deleting·paths,	115	It·provides·similar·operations·for·directories·(creating·or·deleting·paths,
116	reading·the·list·of·files·in·a·directory,...).</p>	116	reading·the·list·of·files·in·a·directory,…).</p>
117	<p>It·also·provides·information·on·the·system·itself·(the·list·of·available·drives	117	<p>It·also·provides·information·on·the·system·itself·(the·list·of·available·drives
118	on·a·windows·machine·for·instance).</p>	118	on·a·windows·machine·for·instance).</p>
119	<p>The·root·type·<cite>Filesystem_Record</cite>·is·abstract,·and·is·specialized·in	119	<p>The·root·type·<cite>Filesystem_Record</cite>·is·abstract,·and·is·specialized·in
120	various·child·types.·A·convenient·factory·is·provided·to·return·the·filesystem	120	various·child·types.·A·convenient·factory·is·provided·to·return·the·filesystem
121	appropriate·for·the·local·machine·(<cite>Get_Local_Filesystem</cite>),·but·you	121	appropriate·for·the·local·machine·(<cite>Get_Local_Filesystem</cite>),·but·you
122	might·chose·to·create·your·own·factory·in·your·application·if·you·have	122	might·chose·to·create·your·own·factory·in·your·application·if·you·have
123	specialized·needs·(<a·class="reference·internal"·href="#remote-filesystems"><span·class="std·std-ref">Remote·filesystems</span></a>).</p>	123	specialized·needs·(<a·class="reference·internal"·href="#remote-filesystems"><span·class="std·std-ref">Remote·filesystems</span></a>).</p>
Offset 148, 24 lines modified		Offset 148, 24 lines modified
148	<div·class="section"·id="remote-filesystems">	148	<div·class="section"·id="remote-filesystems">
149	<span·id="id1"></span><h2><span·class="section-number">14.2.·</span>Remote·filesystems<a·class="headerlink"·href="#remote-filesystems"·title="Permalink·to·this·headline">¶</a></h2>	149	<span·id="id1"></span><h2><span·class="section-number">14.2.·</span>Remote·filesystems<a·class="headerlink"·href="#remote-filesystems"·title="Permalink·to·this·headline">¶</a></h2>
150	<p>Once·the·abstract·for·filesystems·exists,·it·is·tempting·to·use·it·to	150	<p>Once·the·abstract·for·filesystems·exists,·it·is·tempting·to·use·it·to
151	access·files·on·remote·machines.·There·are·of·course·lots·of·differences	151	access·files·on·remote·machines.·There·are·of·course·lots·of·differences
152	with·filesystems·on·the·local·machine:·their·names·are·manipulated	152	with·filesystems·on·the·local·machine:·their·names·are·manipulated
153	similarly·(although·you·need·to·somehow·indicate·on·which·host·they·are	153	similarly·(although·you·need·to·somehow·indicate·on·which·host·they·are
154	to·be·found),·but·any·operation·of·the·file·itself·needs·to·be·done·on·the	154	to·be·found),·but·any·operation·of·the·file·itself·needs·to·be·done·on·the
155	remote·host·itself,·as·it·can't·be·done·through·calls·to·the·system's	155	remote·host·itself,·as·it·can’t·be·done·through·calls·to·the·system’s
156	standard·C·library.</p>	156	standard·C·library.</p>
157	<p>Note·that·when·we·speak·of·disks·on·a·remote·machine,·we·indicate·disks	157	<p>Note·that·when·we·speak·of·disks·on·a·remote·machine,·we·indicate·disks
158	that·are·not·accessible·locally,·for·instance·through·NFS·mounts·or·samba.	158	that·are·not·accessible·locally,·for·instance·through·NFS·mounts·or·samba.
159	In·such·cases,·the·files·are·accessed·transparently·as·if·they·were·local,	159	In·such·cases,·the·files·are·accessed·transparently·as·if·they·were·local,
160	and·all·this·is·taken·care·of·by·the·system·itself,·no·special·layer·is	160	and·all·this·is·taken·care·of·by·the·system·itself,·no·special·layer·is
161	needed·at·the·application·level.</p>	161	needed·at·the·application·level.</p>
162	<p>GNATColl·provides·an·extensive·framework·for·manipulating·such	162	<p>GNATColl·provides·an·extensive·framework·for·manipulating·such
163	remote·files.·It·knows·what·commands·need·to·be·run·on·the·remote·host·to	163	remote·files.·It·knows·what·commands·need·to·be·run·on·the·remote·host·to
164	perform·the·operations·(~~&quot~~;cp~~&quot~~;·or·~~&quot~~;copy~~&quot~~;,·~~&quot~~;sta~~t&quo~~t;·or·~~&quot~~;dir·/a-d~~&quot~~;,...)·and	164	perform·the·operations·(“cp”·or·“copy”,·“stat”·or·“dir·/a-d”,…)·and
165	will·happily·perform·these·operations·when·you·try·to·manipulate·such	165	will·happily·perform·these·operations·when·you·try·to·manipulate·such
166	files.</p>	166	files.</p>
167	<p>There·are·however·two·operations·that·your·own·application·needs·to·take	167	<p>There·are·however·two·operations·that·your·own·application·needs·to·take
168	care·of·to·take·full·advantage·of·remote·files.</p>	168	care·of·to·take·full·advantage·of·remote·files.</p>
169	<div·class="section"·id="filesystem-factory">	169	<div·class="section"·id="filesystem-factory">
170	<h3><span·class="section-number">14.2.1.·</span>Filesystem·factory<a·class="headerlink"·href="#filesystem-factory"·title="Permalink·to·this·headline">¶</a></h3>	170	<h3><span·class="section-number">14.2.1.·</span>Filesystem·factory<a·class="headerlink"·href="#filesystem-factory"·title="Permalink·to·this·headline">¶</a></h3>
171	<p>GNATColl·cannot·know·in·advance·what·filesystem·is·running·on·the	171	<p>GNATColl·cannot·know·in·advance·what·filesystem·is·running·on·the
Offset 219, 15 lines modified		Offset 219, 15 lines modified
219	different·machines.</p>	219	different·machines.</p>
220	<p>GNATColl·does·not·try·to·second·guess·your·intention·here.·It	220	<p>GNATColl·does·not·try·to·second·guess·your·intention·here.·It
221	performs·all·its·remote·operations·through·a·tagged·type·defined·in	221	performs·all·its·remote·operations·through·a·tagged·type·defined·in
222	<cite>GNATCOLL.Filesystem.Transport</cite>.·This·type·is·abstract,·and·must·be	222	<cite>GNATCOLL.Filesystem.Transport</cite>.·This·type·is·abstract,·and·must·be
223	overridden·in·your·application.·For·instance,·GPS·has·a·full·support·for	223	overridden·in·your·application.·For·instance,·GPS·has·a·full·support·for
224	choosing·which·protocol·to·use·on·which·host,·what·kind·of·filesystem·is	224	choosing·which·protocol·to·use·on·which·host,·what·kind·of·filesystem·is
225	running·on·that·host,·to·recognize·password·queries·from·the·transport	225	running·on·that·host,·to·recognize·password·queries·from·the·transport
226	protocol,....·All·these·can·be·encapsulated·in·the·transport	226	protocol,….·All·these·can·be·encapsulated·in·the·transport
227	protocol.</p>	227	protocol.</p>
228	<p>Once·you·have·created·one·or·more·children·of	228	<p>Once·you·have·created·one·or·more·children·of
229	<cite>Filesystem_Transport_Record</cite>,·you·associate·them·with·your	229	<cite>Filesystem_Transport_Record</cite>,·you·associate·them·with·your
230	instance·of·the·filesystem·through·a·call·to·the·<cite>Setup</cite>·primitive	230	instance·of·the·filesystem·through·a·call·to·the·<cite>Setup</cite>·primitive
231	operation·of·the·filesystem.·See·the·factory·example·above.</p>	231	operation·of·the·filesystem.·See·the·factory·example·above.</p>
232	</div>	232	</div>
233	</div>	233	</div>


Offset 36, 33 lines modified		Offset 36, 33 lines modified
36	the·API,·and·certainly·fills·the·code·with·lots·of·conversion·from·full·name·to	36	the·API,·and·certainly·fills·the·code·with·lots·of·conversion·from·full·name·to
37	base·name,·and·sometimes·reverse·(which,·of·course,·might·be·an·expansive	37	base·name,·and·sometimes·reverse·(which,·of·course,·might·be·an·expansive
38	computation).·To·make·this·easier,·GNATColl·provides·a·type·that·encapsulates	38	computation).·To·make·this·easier,·GNATColl·provides·a·type·that·encapsulates
39	the·notion·of·a·file,·and·removes·the·need·for·the·application·to·indicate	39	the·notion·of·a·file,·and·removes·the·need·for·the·application·to·indicate
40	whether·it·needs·a·full·name,·a·base·name,·or·any·other·part·of·the·file·name.	40	whether·it·needs·a·full·name,·a·base·name,·or·any·other·part·of·the·file·name.
41	***·14.1.·Filesystems·abstractionÂ¶·***	41	***·14.1.·Filesystems·abstractionÂ¶·***
42	There·exists·lots·of·different·filesystems·on·all·machines.·These·include·such	42	There·exists·lots·of·different·filesystems·on·all·machines.·These·include·such
43	things·as·FAT,·VFAT,·NTFS,·ext2,·VMS,~~...~~.·However,·all·these·can·be·grouped	43	things·as·FAT,·VFAT,·NTFS,·ext2,·VMS,â¦.·However,·all·these·can·be·grouped
44	into·three·families·of·filesystems:	44	into·three·families·of·filesystems:
45	····*·windows-based·filesystems	45	····*·windows-based·filesystems
46	······On·such·filesystems,·the·full·name·of·a·file·is·split·into·three·parts:	46	······On·such·filesystems,·the·full·name·of·a·file·is·split·into·three·parts:
47	······the·name·of·the·drive·(c:,·d:,~~...~~),·the·directories·which·are·separated	47	······the·name·of·the·drive·(c:,·d:,â¦),·the·directories·which·are·separated
48	······by·a·backslash,·and·the·base·name.·Such·filesystems·are·sometimes	48	······by·a·backslash,·and·the·base·name.·Such·filesystems·are·sometimes
49	······inaccurately·said·to·be·case·insensitive:·by·that,·one·means·that·the	49	······inaccurately·said·to·be·case·insensitive:·by·that,·one·means·that·the
50	······same·file·can·be·accessed·through·various·casing.·However,·a·user·is	50	······same·file·can·be·accessed·through·various·casing.·However,·a·user·is
51	······generally·expecting·a·specific·casing·when·a·file·name·is·displayed,·and	51	······generally·expecting·a·specific·casing·when·a·file·name·is·displayed,·and
52	······the·application·should·strive·to·preserve·that·casing·(as·opposed·to,·for	52	······the·application·should·strive·to·preserve·that·casing·(as·opposed·to,·for
53	······instance,·systematically·convert·the·file·name·to·lower·cases).	53	······instance,·systematically·convert·the·file·name·to·lower·cases).
54	······A·special·case·of·a·windows-based·filesystems·is·that·emulated·by·the	54	······A·special·case·of·a·windows-based·filesystems·is·that·emulated·by·the
55	······cygwin·development·environment.·In·this·case,·the·filesystem·is·seen·as	55	······cygwin·development·environment.·In·this·case,·the·filesystem·is·seen·as
56	······if·it·was·unix-based·(see·below),·with·one·special·quirk·to·indicate·the	56	······if·it·was·unix-based·(see·below),·with·one·special·quirk·to·indicate·the
57	······drive·letter·(the·file·name·starts·with·"/cygwin/c/").	57	······drive·letter·(the·file·name·starts·with·â/cygwin/c/â).
58	····*·unix-based·filesystems	58	····*·unix-based·filesystems
59	······On·such·filesystems,·directories·are·separated·by·forward·slashed.·File	59	······On·such·filesystems,·directories·are·separated·by·forward·slashed.·File
60	······names·are·case·sensitive,·that·is·a·directory·can·contain·both·"foo"·~~and~~	60	······names·are·case·sensitive,·that·is·a·directory·can·contain·both·âfooâ
61	······"Foo",·which·is·not·possible·on·windows-based·filesystems.	61	······and·âFooâ,·which·is·not·possible·on·windows-based·filesystems.
62	····*·vms·filesystem	62	····*·vms·filesystem
63	······This·filesystem·represents·path·differently·than·the·other·two,·using	63	······This·filesystem·represents·path·differently·than·the·other·two,·using
64	······brackets·to·indicate·parent·directories	64	······brackets·to·indicate·parent·directories
65	A·given·machine·can·actually·have·several·file·systems·in·parallel,·when·a	65	A·given·machine·can·actually·have·several·file·systems·in·parallel,·when·a
66	remote·disk·is·mounted·through·NFS·or·samba·for·instance.·There·is·generally·no	66	remote·disk·is·mounted·through·NFS·or·samba·for·instance.·There·is·generally·no
67	easy·way·to·guess·that·information·automatically,·and·it·generally·does·not	67	easy·way·to·guess·that·information·automatically,·and·it·generally·does·not
68	matter·since·the·system·will·convert·from·the·native·file·system·to·that·of·the	68	matter·since·the·system·will·convert·from·the·native·file·system·to·that·of·the
Offset 72, 15 lines modified		Offset 72, 15 lines modified
72	GNATColl·abstracts·the·differences·between·these·filesystems·through·a·set·of	72	GNATColl·abstracts·the·differences·between·these·filesystems·through·a·set·of
73	tagged·types·in·theGNATCOLL.Filesystempackage·and·its·children.·Such·a·type·has	73	tagged·types·in·theGNATCOLL.Filesystempackage·and·its·children.·Such·a·type·has
74	primitive·operations·to·manipulate·the·names·of·files·(retrieving·the·base·name	74	primitive·operations·to·manipulate·the·names·of·files·(retrieving·the·base·name
75	from·a·full·name·for·instance),·to·check·various·attributes·of·the·file·(is	75	from·a·full·name·for·instance),·to·check·various·attributes·of·the·file·(is
76	this·a·directory,·a·symbolic·link,·is·the·file·readable·or·writable),·or·to	76	this·a·directory,·a·symbolic·link,·is·the·file·readable·or·writable),·or·to
77	manipulate·the·file·itself·(copying,·deleting,·reading·and·writing).·It	77	manipulate·the·file·itself·(copying,·deleting,·reading·and·writing).·It
78	provides·similar·operations·for·directories·(creating·or·deleting·paths,	78	provides·similar·operations·for·directories·(creating·or·deleting·paths,
79	reading·the·list·of·files·in·a·directory,~~...~~).	79	reading·the·list·of·files·in·a·directory,â¦).
80	It·also·provides·information·on·the·system·itself·(the·list·of·available·drives	80	It·also·provides·information·on·the·system·itself·(the·list·of·available·drives
81	on·a·windows·machine·for·instance).	81	on·a·windows·machine·for·instance).
82	The·root·typeFilesystem_Recordis·abstract,·and·is·specialized·in·various·child	82	The·root·typeFilesystem_Recordis·abstract,·and·is·specialized·in·various·child
83	types.·A·convenient·factory·is·provided·to·return·the·filesystem·appropriate	83	types.·A·convenient·factory·is·provided·to·return·the·filesystem·appropriate
84	for·the·local·machine·(Get_Local_Filesystem),·but·you·might·chose·to·create	84	for·the·local·machine·(Get_Local_Filesystem),·but·you·might·chose·to·create
85	your·own·factory·in·your·application·if·you·have·specialized·needs·(Remote	85	your·own·factory·in·your·application·if·you·have·specialized·needs·(Remote
86	filesystems).	86	filesystems).
Offset 106, 24 lines modified		Offset 106, 24 lines modified
106	subprogramsLocale_To_DisplayandSet_Locale_To_Display_Encoder	106	subprogramsLocale_To_DisplayandSet_Locale_To_Display_Encoder
107	***·14.2.·Remote·filesystemsÂ¶·***	107	***·14.2.·Remote·filesystemsÂ¶·***
108	Once·the·abstract·for·filesystems·exists,·it·is·tempting·to·use·it·to·access	108	Once·the·abstract·for·filesystems·exists,·it·is·tempting·to·use·it·to·access
109	files·on·remote·machines.·There·are·of·course·lots·of·differences·with	109	files·on·remote·machines.·There·are·of·course·lots·of·differences·with
110	filesystems·on·the·local·machine:·their·names·are·manipulated·similarly	110	filesystems·on·the·local·machine:·their·names·are·manipulated·similarly
111	(although·you·need·to·somehow·indicate·on·which·host·they·are·to·be·found),·but	111	(although·you·need·to·somehow·indicate·on·which·host·they·are·to·be·found),·but
112	any·operation·of·the·file·itself·needs·to·be·done·on·the·remote·host·itself,·as	112	any·operation·of·the·file·itself·needs·to·be·done·on·the·remote·host·itself,·as
113	it·can't·be·done·through·calls·to·the·system's·standard·C·library.	113	it·canât·be·done·through·calls·to·the·systemâs·standard·C·library.
114	Note·that·when·we·speak·of·disks·on·a·remote·machine,·we·indicate·disks·that	114	Note·that·when·we·speak·of·disks·on·a·remote·machine,·we·indicate·disks·that
115	are·not·accessible·locally,·for·instance·through·NFS·mounts·or·samba.·In·such	115	are·not·accessible·locally,·for·instance·through·NFS·mounts·or·samba.·In·such
116	cases,·the·files·are·accessed·transparently·as·if·they·were·local,·and·all·this	116	cases,·the·files·are·accessed·transparently·as·if·they·were·local,·and·all·this
117	is·taken·care·of·by·the·system·itself,·no·special·layer·is·needed·at·the	117	is·taken·care·of·by·the·system·itself,·no·special·layer·is·needed·at·the
118	application·level.	118	application·level.
119	GNATColl·provides·an·extensive·framework·for·manipulating·such·remote·files.·It	119	GNATColl·provides·an·extensive·framework·for·manipulating·such·remote·files.·It
120	knows·what·commands·need·to·be·run·on·the·remote·host·to·perform·the·operations	120	knows·what·commands·need·to·be·run·on·the·remote·host·to·perform·the·operations
121	("cp"·or·"copy",·"stat"·or·"dir·/a-d",~~...~~)·and·will·happily~~·perform·these~~	121	(âcpâ·or·âcopyâ,·âstatâ·or·âdir·/a-dâ,â¦)·and·will·happily
122	operations·when·you·try·to·manipulate·such·files.	122	perform·these·operations·when·you·try·to·manipulate·such·files.
123	There·are·however·two·operations·that·your·own·application·needs·to·take·care	123	There·are·however·two·operations·that·your·own·application·needs·to·take·care
124	of·to·take·full·advantage·of·remote·files.	124	of·to·take·full·advantage·of·remote·files.
125	**·14.2.1.·Filesystem·factoryÂ¶·**	125	**·14.2.1.·Filesystem·factoryÂ¶·**
126	GNATColl·cannot·know·in·advance·what·filesystem·is·running·on·the·remote·host,	126	GNATColl·cannot·know·in·advance·what·filesystem·is·running·on·the·remote·host,
127	so·it·does·not·try·to·guess·it.·As·a·result,·your·application·should·have·a	127	so·it·does·not·try·to·guess·it.·As·a·result,·your·application·should·have·a
128	factory·that·creates·the·proper·instance·of·aFilesystem_Recorddepending·on·the	128	factory·that·creates·the·proper·instance·of·aFilesystem_Recorddepending·on·the
129	host.·Something·like:	129	host.·Something·like:
Offset 168, 15 lines modified		Offset 168, 15 lines modified
168	(and·will·likely·be·asked·to·the·user).·Furthermore,·you·might·not·want·to·use	168	(and·will·likely·be·asked·to·the·user).·Furthermore,·you·might·not·want·to·use
169	the·same·protocol·to·connect·to·different·machines.	169	the·same·protocol·to·connect·to·different·machines.
170	GNATColl·does·not·try·to·second·guess·your·intention·here.·It·performs·all·its	170	GNATColl·does·not·try·to·second·guess·your·intention·here.·It·performs·all·its
171	remote·operations·through·a·tagged·type·defined	171	remote·operations·through·a·tagged·type·defined
172	inGNATCOLL.Filesystem.Transport.·This·type·is·abstract,·and·must·be·overridden	172	inGNATCOLL.Filesystem.Transport.·This·type·is·abstract,·and·must·be·overridden
173	in·your·application.·For·instance,·GPS·has·a·full·support·for·choosing·which	173	in·your·application.·For·instance,·GPS·has·a·full·support·for·choosing·which
174	protocol·to·use·on·which·host,·what·kind·of·filesystem·is·running·on·that·host,	174	protocol·to·use·on·which·host,·what·kind·of·filesystem·is·running·on·that·host,
175	to·recognize·password·queries·from·the·transport·protocol,~~...~~.·All·these·can·be	175	to·recognize·password·queries·from·the·transport·protocol,â¦.·All·these·can·be
176	encapsulated·in·the·transport·protocol.	176	encapsulated·in·the·transport·protocol.
177	Once·you·have·created·one·or·more·children·ofFilesystem_Transport_Record,·you	177	Once·you·have·created·one·or·more·children·ofFilesystem_Transport_Record,·you
178	associate·them·with·your·instance·of·the·filesystem·through·a·call·to	178	associate·them·with·your·instance·of·the·filesystem·through·a·call·to
179	theSetupprimitive·operation·of·the·filesystem.·See·the·factory·example·above.	179	theSetupprimitive·operation·of·the·filesystem.·See·the·factory·example·above.
180	***·14.3.·Virtual·filesÂ¶·***	180	***·14.3.·Virtual·filesÂ¶·***
181	As·we·have·seen,·the·filesystem·type·abstracts·all·the·operations·for	181	As·we·have·seen,·the·filesystem·type·abstracts·all·the·operations·for
182	manipulating·files·and·their·names.·There·is·however·another·aspect·when	182	manipulating·files·and·their·names.·There·is·however·another·aspect·when


Offset 12, 15 lines modified		Offset 12, 15 lines modified
12	efficient·depending·on·the·pattern.	12	efficient·depending·on·the·pattern.

13	It·deals·with·string·searching,·and·does·not·handle·regular	13	It·deals·with·string·searching,·and·does·not·handle·regular
14	expressions·for·instance.	14	expressions·for·instance.

15	This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but	15	This·algorithm·needs·to·preprocess·its·key·(the·searched·string),·but
16	does·not·need·to·perform·any·specific·analysis·of·the·string·to·be	16	does·not·need·to·perform·any·specific·analysis·of·the·string·to·be
17	searched.·Its·execution·time·can·be·sub-linear:·it·doesn't·need·to	17	searched.·Its·execution·time·can·be·sub-linear:·it·doesn’t·need·to
18	actually·check·every·character·of·the·string·to·be·searched,·and·will	18	actually·check·every·character·of·the·string·to·be·searched,·and·will
19	skip·over·some·of·them.·The·worst·case·for·this·algorithm·has·been	19	skip·over·some·of·them.·The·worst·case·for·this·algorithm·has·been
20	proved·to·need·approximately·3·*·N·comparisons,·hence·the·algorithm	20	proved·to·need·approximately·3·*·N·comparisons,·hence·the·algorithm
21	has·a·complexity·of·O(n).	21	has·a·complexity·of·O(n).

22	The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that	22	The·longer·the·key,·the·faster·the·algorithm·in·general,·since·that
23	provides·more·context·as·to·how·many·characters·can·be·skipped·when·a	23	provides·more·context·as·to·how·many·characters·can·be·skipped·when·a
Offset 29, 18 lines modified		Offset 29, 18 lines modified
29	We·will·not·go·into·the·details·of·the·algorithm,·although·a·general	29	We·will·not·go·into·the·details·of·the·algorithm,·although·a·general
30	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-	30	description·follows:·when·the·pattern·is·being·preprocessed,·Boyer-
31	Moore·computes·how·many·characters·can·be·skipped·if·an·incorrect	31	Moore·computes·how·many·characters·can·be·skipped·if·an·incorrect
32	match·is·found·at·that·point,·depending·on·which·character·was·read.	32	match·is·found·at·that·point,·depending·on·which·character·was·read.
33	In·addition,·this·algorithm·tries·to·match·the·key·starting·from·its	33	In·addition,·this·algorithm·tries·to·match·the·key·starting·from·its
34	end,·which·in·general·provides·a·greater·number·of·characters·to·skip.	34	end,·which·in·general·provides·a·greater·number·of·characters·to·skip.

35	For·instance,·if·you·are·looking·for·"ABC"·in·the·string·"ABDEFG"·at	35	For·instance,·if·you·are·looking·for·“ABC”·in·the·string·“ABDEFG”·at
36	the·first·position,·the·algorithm·will·compare·"C"·and·"D".·Since·"D"	36	the·first·position,·the·algorithm·will·compare·“C”·and·“D”.·Since·“D”
37	does·not·appear·in·the·key·"ABC",·it·knows·that·it·can·immediately	37	does·not·appear·in·the·key·“ABC”,·it·knows·that·it·can·immediately
38	skip·3·characters·and·start·the·search·after·"D".	38	skip·3·characters·and·start·the·search·after·“D”.

39	Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:	39	Using·this·package·is·extremely·easy,·and·it·has·only·a·limited·API:

40	···declare	40	···declare
41	·····Str·:·constant·String·:=·"ABDEABCFGABC";	41	·····Str·:·constant·String·:=·"ABDEABCFGABC";
42	·····Key·:·Pattern;	42	·····Key·:·Pattern;
43	·····Index·:·Integer;	43	·····Index·:·Integer;


Offset 1, 1 lines modified		Offset 1, 1 lines modified
1	u~~s-ascii~~	1	utf-8


Offset 45, 15 lines modified		Offset 45, 15 lines modified

45	SOURCE_DIR	45	SOURCE_DIR
46	···For·out-of-tree·build	46	···For·out-of-tree·build

47	ENABLE_SHARED	47	ENABLE_SHARED
48	···Controls·whether·shared·and·static-pic·library·variants·should·be	48	···Controls·whether·shared·and·static-pic·library·variants·should·be
49	···built:·yes·(default)·or·no.·If·you·only·intend·to·use·static	49	···built:·yes·(default)·or·no.·If·you·only·intend·to·use·static
50	···libraries,·specify·'no'.	50	···libraries,·specify·‘no’.

51	Module-specific:	51	Module-specific:

52	GNATCOLL_MMAP	52	GNATCOLL_MMAP
53	···Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect	53	···Whether·MMAP·is·supported:·yes·(default)·or·no;·this·has·no·effect
54	···on·Windows·where·embedded·MMAP·implementation·is·always·provided.	54	···on·Windows·where·embedded·MMAP·implementation·is·always·provided.

Offset 87, 13 lines modified		Offset 87, 13 lines modified
87	build·it·first.·This·command·will·install·all·library·variants·that	87	build·it·first.·This·command·will·install·all·library·variants·that
88	were·built.	88	were·built.

89	Your·application·can·now·use·the·GNATColl·code·through·a·project·file,	89	Your·application·can·now·use·the·GNATColl·code·through·a·project·file,
90	by·adding·a·"with"·clause·to·"gnatcoll.gpr".	90	by·adding·a·"with"·clause·to·"gnatcoll.gpr".

91	If·you·wish·to·install·in·a·different·location·than·was·specified·at	91	If·you·wish·to·install·in·a·different·location·than·was·specified·at
92	configure·time,·you·can·override·the·"prefix"·variable·from·the	92	configure·time,·you·can·override·the·“prefix”·variable·from·the
93	command·line,·for·instance:	93	command·line,·for·instance:

94	···make·prefix=/alternate/directory·install	94	···make·prefix=/alternate/directory·install

95	This·does·not·require·any·recompilation.	95	This·does·not·require·any·recompilation.