Debian Codegraph @

manual/grammar.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="grammar">
5 <title>Grammar</title>
6
7 <section id="reopen-mappings">
8 <title>REOPEN-MAPPINGS</title>
9 <para>
10 A list of mapping tags that ADD/MAP/REPLACE should be able to operate on even though they were present on readings
11 in the input stream.
12 </para>
13 <screen>
14 REOPEN-MAPPINGS = @a @b @c ;
15 </screen>
16 </section>
17
18 <section id="grammar-cmdargs">
19 <title>CMDARGS, CMDARGS-OVERRIDE</title>
20 <indexterm>
21 <primary>CMDARGS</primary>
22 </indexterm>
23 <indexterm>
24 <primary>CMDARGS-OVERRIDE</primary>
25 </indexterm>
26 <para>
27 You can set default cmdline arguments with <code>CMDARGS += ... ;</code>.
28 Currently arguments can only be added, hence <code>+=</code>, but removing and assignment can be implemented if needed.
29 </para>
30 <para>
31 Similarly, <code>CMDARGS-OVERRIDE += ... ;</code> will set cmdline arguments that will override the ones actually passed on the command line.
32 </para>
33 <para>
34 The <link linkend="cmdargs-override">order of argument sources</link> is well defined.
35 </para>
36 <screen>
37 CMDARGS += --num-windows 5 ;
38 </screen>
39 </section>
40
41 <section id="grammar-options">
42 <title>OPTIONS</title>
43 <para>
44 You can affect how the grammar should be parsed with <code>OPTIONS += ... ;</code>.
45 Currently options can only be added, hence <code>+=</code>, but removing and assignment can be implemented if needed.
46 </para>
47 <screen>
48 OPTIONS += no-inline-templates ;
49 </screen>
50
51 <section id="grammar-options-safe-setparent">
52 <title>safe-setparent</title>
53 <indexterm>
54 <primary>safe-setparent</primary>
55 </indexterm>
56 <para>
57 Adds rule flag SAFE to all SETPARENT rules, meaning they won't run on cohorts that already have a parent.
58 Can be countered per-rule with flag UNSAFE.
59 </para>
60 </section>
61
62 <section id="grammar-options-addcattach">
63 <title>addcohort-attach</title>
64 <indexterm>
65 <primary>addcohort-attach</primary>
66 </indexterm>
67 <para>
68 Causes ADDCOHORT to set the dependency parent of the newly added cohort to the target cohort.
69 </para>
70 </section>
71
72 <section id="grammar-options-noisets">
73 <title>no-inline-sets</title>
74 <indexterm>
75 <primary>no-inline-sets</primary>
76 </indexterm>
77 <para>
78 Disallows the use of inline sets in most places. They're still allowed in places that CG-2 did not consider sets,
79 such as MAP, ADD, REPLACE, and ADDCOHORT tag lists, and in the context of a SET definition.
80 Also, the special set (*) remains valid.
81 </para>
82 </section>
83
84 <section id="grammar-options-noitmpls">
85 <title>no-inline-templates</title>
86 <indexterm>
87 <primary>no-inline-templates</primary>
88 </indexterm>
89 <para>
90 Disallows the use of inline templates in most places. They're still allowed in the context of a TEMPLATE definition.
91 </para>
92 </section>
93
94 <section id="grammar-options-strict-wforms">
95 <title>strict-wordforms</title>
96 <indexterm>
97 <primary>strict-wordforms</primary>
98 </indexterm>
99 <para>
100 Instructs STRICT-TAGS to forbid all wordform tags (<code>"&lt;…&gt;"</code>) by default.
101 </para>
102 </section>
103
104 <section id="grammar-options-strict-bforms">
105 <title>strict-baseforms</title>
106 <indexterm>
107 <primary>strict-baseforms</primary>
108 </indexterm>
109 <para>
110 Instructs STRICT-TAGS to forbid all baseform tags (<code>"…"</code>) by default.
111 </para>
112 </section>
113
114 <section id="grammar-options-strict-second">
115 <title>strict-secondary</title>
116 <indexterm>
117 <primary>strict-secondary</primary>
118 </indexterm>
119 <para>
120 Instructs STRICT-TAGS to forbid all secondary tags (<code>&lt;…&gt;</code>) by default.
121 </para>
122 </section>
123
124 <section id="grammar-options-strict-regex">
125 <title>strict-regex</title>
126 <indexterm>
127 <primary>strict-regex</primary>
128 </indexterm>
129 <para>
130 Instructs STRICT-TAGS to forbid all regular expression tags (<code>/…/r</code> and others) by default.
131 </para>
132 </section>
133
134 <section id="grammar-options-strict-icase">
135 <title>strict-icase</title>
136 <indexterm>
137 <primary>strict-icase</primary>
138 </indexterm>
139 <para>
140 Instructs STRICT-TAGS to forbid all case-insensitive tags by default.
141 </para>
142 </section>
143
144 <section id="grammar-options-self-no-barrier">
145 <title>self-no-barrier</title>
146 <indexterm>
147 <primary>self-no-barrier</primary>
148 </indexterm>
149 <para>
150 Inverts the behavior of barriers on self tests. By default, barriers will stop if the self cohort matches.
151 This can be toggled on a per context basis with modifier <link linkend="dep-ct-no-barrier">N</link>,
152 where self-no-barrier inverts the behavior of S vs. SN.
153 </para>
154 </section>
155 </section>
156
157 <section id="grammar-include">
158 <title>INCLUDE</title>
159 <indexterm>
160 <primary>INCLUDE</primary>
161 </indexterm>
162 <indexterm>
163 <primary>STATIC</primary>
164 </indexterm>
165 <para>
166 <link linkend="keyword-include">INCLUDE</link> loads and parses another grammar file as if it had been pasted
167 in on the line of the INCLUDE statement, with the exception that line numbers start again from 1.
168 Included rules can thus conflict with rules in other files if they happen to occupy the same line in multiple files.
169 It will still work as you expect, but --trace output won't show you which file the rules come from.
170 <screen>
171 INCLUDE other-file-name ;
172 </screen>
173 The file name should not be quoted and the line must end with semi-colon.
174 On Posix platforms the path will be shell expanded if it contains any of <code>~ $ *</code>.
175 The include candidate will be looked for at a path relative to the file performing the include.
176 Be careful not to make circular includes as they will loop forever.
177 </para>
178 <para>
179 If you use option <code>STATIC</code>, only the passive parts of the grammar is loaded.
180 This is useful if you have an existing grammar that you don't want to split, but still want to reuse the sets
181 from it for other grammars. This is transitive - all grammars loaded from a static grammar will be static, even
182 if not explicitly loaded as such.
183 <screen>
184 INCLUDE STATIC other-file-name ;
185 </screen>
186 </para>
187 </section>
188
189 <section id="grammar-sections">
190 <title>Sections</title>
191 <para>
192 <indexterm>
193 <primary>SECTION</primary>
194 </indexterm>
195 <indexterm>
196 <primary>BEFORE-SECTIONS</primary>
197 </indexterm>
198 <indexterm>
199 <primary>AFTER-SECTIONS</primary>
200 </indexterm>
201 <indexterm>
202 <primary>NULL-SECTION</primary>
203 </indexterm>
204 <indexterm>
205 <primary>MAPPINGS</primary>
206 </indexterm>
207 <indexterm>
208 <primary>SETS</primary>
209 </indexterm>
210 <indexterm>
211 <primary>CORRECTIONS</primary>
212 </indexterm>
213 <indexterm>
214 <primary>CONSTRAINTS</primary>
215 </indexterm>
216 CG-2 has three seperate grammar sections: <link linkend="keyword-sets">SETS</link>,
217 <link linkend="keyword-mappings">MAPPINGS</link>,
218 and <link linkend="keyword-constraints">CONSTRAINTS</link>.
219 VISLCG added to these with the <link linkend="keyword-corrections">CORRECTIONS</link> section.
220 Each of these can only contain certain definitions, such as LIST, MAP, or SELECT.
221 As I understand it, this was due to the original CG parser being written in a language
222 that needed such a format. In any case, I did not see the logic or usability in
223 such a strict format. VISL CG-3 has a single section header
224 <link linkend="keyword-section">SECTION</link>, which can contain
225 any of the set or rule definitions. Sections can also be given a name for easier
226 identification and anchor behavior, but that is optional. The older section
227 headings are still valid and will work as expected, though.
228 </para>
229 <para>
230 By allowing any set or rule definition anywhere you could write a grammar such as:
231 <screen>
232 DELIMITERS = "&lt;$.&gt;" ;
233 LIST ThisIsASet = "&lt;sometag&gt;" "&lt;othertag&gt;" ;
234
235 SECTION
236 LIST ThisIsAlsoASet = atag btag ctag ;
237 SET Hubba = ThisIsASet - (ctag) ;
238 SELECT ThisIsASet IF (-1 (dtag)) ;
239
240 SECTION with-name;
241 LIST AnotherSet = "&lt;youknowthedrill&gt;" ;
242 MAP (@bingo) TARGET AnotherSet ;
243 </screen>
244 </para>
245 <para>
246 Notice that the first LIST ThisIsASet is outside a section.
247 This is because sets are considered global regardless of where
248 they are declared and can as such be declared anywhere, even before the
249 DELIMITERS declaration should you so desire. A side effect of this is
250 that set names must be unique across the entire grammar, but as this is
251 also the behavior of CG-2 and VISLCG that should not be a surprise nor problem.
252 </para>
253 <para>
254 Rules are applied in the order they are declared. In the above example
255 that would execute SELECT first and then the MAP rule.
256 </para>
257 <para>
258 Sections may optionally have <link linkend="rule-options">rule options (flags)</link> which will be inherited by all rules within that section. Each new section resets this list. In order to parse the section name from rule options, the list of rule options must come after a <code>:</code> with space before it.
259 </para>
260
261 <section id="grammar-before-sections">
262 <title>BEFORE-SECTIONS</title>
263 <para>
264 See <link linkend="keyword-before-sections">BEFORE-SECTIONS</link>.
265 Takes the place of what previously were the MAPPINGS and CORRECTIONS blocks,
266 but may contain any rule type.
267 </para>
268 </section>
269
270 <section id="grammar-section">
271 <title>SECTION</title>
272 <para>
273 See <link linkend="keyword-section">SECTION</link>.
274 Takes the place of what previously were the CONSTRAINTS blocks,
275 but may contain any rule type.
276 </para>
277 </section>
278
279 <section id="grammar-after-sections">
280 <title>AFTER-SECTIONS</title>
281 <para>
282 See <link linkend="keyword-after-sections">AFTER-SECTIONS</link>.
283 May contain any rule type, and is run once after all other sections.
284 This is new in CG-3.
285 </para>
286 </section>
287
288 <section id="grammar-null-section">
289 <title>NULL-SECTION</title>
290 <para>
291 See <link linkend="keyword-null-section">NULL-SECTION</link>.
292 May contain any rule type, but is not actually run.
293 This is new in CG-3.
294 </para>
295 </section>
296
297 <section id="grammar-section-order">
298 <title>Ordering of sections in grammar</title>
299 <para>
300 The order and arrangement of BEFORE-SECTIONS and AFTER-SECTIONS in the grammar has no impact on the
301 order normal SECTIONs are applied in.
302 </para>
303 <para>
304 An order of
305 <screen>
306 SECTION
307 SECTION
308 BEFORE-SECTIONS
309 SECTION
310 NULL-SECTION
311 AFTER-SECTIONS
312 SECTION
313 BEFORE-SECTIONS
314 SECTION
315 </screen>
316 is equivalent to
317 <screen>
318 BEFORE-SECTIONS
319 SECTION
320 SECTION
321 SECTION
322 SECTION
323 SECTION
324 AFTER-SECTIONS
325 NULL-SECTION
326 </screen>
327 </para>
328 </section>
329
330 <section id="sections-range">
331 <title>--sections with ranges</title>
332 <para>
333 In VISL CG-3, the --sections flag is able to specify ranges of sections to run, and can even be used to skip
334 sections. If only a single number N is given it behaves as if you had written 1-N.
335 </para>
336 <para>
337 While it is possible to specify a range such as 1,4-6,3 where the selection of sections is not ascending, the actual
338 application order will be 1, 1:4, 1:4:5, 1:4:5:6, 1:3:4:5:6 - that is, the final step will run section 3 in between
339 1 and 4. This is due to the ordering of rules being adamantly enforced as ascending only. If you wish to customize
340 the order of rules you will currently have to use JUMP or EXECUTE.
341 </para>
342 <screen>
343 --sections 6
344 --sections 3-6
345 --sections 2-5,7-9,13-15
346 </screen>
347 </section>
348
349 </section>
350
351 </chapter>