Debian Codegraph @

manual/rules.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="rules">
5 <title>Rules</title>
6
7 <para>
8 Firstly, the CG-2 optional seperation keywords IF and TARGET are completely ignored by VISL CG-3,
9 so only use them for readability. The definitions are given in the following format:
10 <screen>
11 KEYWORD &lt;required_element&gt; [optional_element] ;
12 ...and | separates mutually exclusive choices.
13 </screen>
14 </para>
15
16 <section id="rules-cheatsheet">
17 <title>Cheat Sheet</title>
18 <para>
19 All rules can take an optional wordform tag before the rule keyword.
20 </para>
21 <screen>
22 Reading &amp; Tag manipulations:
23 ADD &lt;tags&gt; [BEFORE|AFTER &lt;tags&gt;] &lt;target&gt; [contextual_tests] ;
24 MAP &lt;tags&gt; [BEFORE|AFTER &lt;tags&gt;] &lt;target&gt; [contextual_tests] ;
25 SUBSTITUTE &lt;locate tags&gt; &lt;replacement tags&gt; &lt;target&gt; [contextual_tests] ;
26 UNMAP &lt;target&gt; [contextual_tests] ;
27
28 REPLACE &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
29 APPEND &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
30 COPY &lt;extra tags&gt; [EXCEPT &lt;except tags&gt;] [BEFORE|AFTER &lt;tags&gt;] &lt;target&gt; [contextual_tests] ;
31
32 SELECT &lt;target&gt; [contextual_tests] ;
33 REMOVE &lt;target&gt; [contextual_tests] ;
34 IFF &lt;target&gt; [contextual_tests] ;
35 RESTORE &lt;restore_target&gt; &lt;target&gt; [contextual_tests] ;
36
37 Dependency manipulation:
38 SETPARENT &lt;target&gt; [contextual_tests]
39 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
40 SETCHILD &lt;target&gt; [contextual_tests]
41 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
42 REMPARENT &lt;target&gt; [contextual_tests] ;
43 SWITCHPARENT [WITHCHILD &lt;child_set&gt;] &lt;target&gt; [contextual_tests] ;
44
45 Relation manipulation:
46 ADDRELATION &lt;name&gt; &lt;target&gt; [contextual_tests]
47 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
48 ADDRELATIONS &lt;name&gt; &lt;name&gt; &lt;target&gt; [contextual_tests]
49 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
50 SETRELATION &lt;name&gt; &lt;target&gt; [contextual_tests]
51 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
52 SETRELATIONS &lt;name&gt; &lt;name&gt; &lt;target&gt; [contextual_tests]
53 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
54 REMRELATION &lt;name&gt; &lt;target&gt; [contextual_tests]
55 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
56 REMRELATIONS &lt;name&gt; &lt;name&gt; &lt;target&gt; [contextual_tests]
57 TO|FROM &lt;contextual_target&gt; [contextual_tests] ;
58
59 Cohort manipulation:
60 ADDCOHORT &lt;cohort tags&gt; BEFORE|AFTER [WITHCHILD &lt;child_set&gt;|NOCHILD]
61 &lt;target&gt; [contextual_tests] ;
62 COPYCOHORT &lt;added tags&gt; [EXCEPT &lt;removed tags&gt;] &lt;target&gt; [contextual_tests]
63 TO [BEFORE|AFTER] [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;contextual targets&gt; ;
64 COPYCOHORT &lt;added tags&gt; [EXCEPT &lt;removed tags&gt;] [BEFORE|AFTER] [WITHCHILD &lt;child_set&gt;|NOCHILD]
65 &lt;target&gt; [contextual_tests] FROM &lt;contextual targets&gt; ;
66 REMCOHORT &lt;target&gt; [contextual_tests] ;
67 SPLITCOHORT &lt;cohort recipe&gt; &lt;target&gt; [contextual_tests] ;
68 MERGECOHORTS &lt;cohort recipe&gt; &lt;target&gt; [contextual_tests] WITH &lt;contextual targets&gt; ;
69
70 MOVE [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;target&gt; [contextual_tests]
71 BEFORE|AFTER [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;contextual_target&gt; [contextual_tests] ;
72 SWITCH &lt;target&gt; [contextual_tests] WITH &lt;contextual_target&gt; [contextual_tests] ;
73
74 Window manipulation:
75 DELIMIT &lt;target&gt; [contextual_tests] ;
76 EXTERNAL ONCE|ALWAYS &lt;program&gt; &lt;target&gt; [contextual_tests] ;
77
78 Variable manipulation:
79 SETVARIABLE [OUTPUT] &lt;name&gt; &lt;value&gt; &lt;target&gt; [contextual_tests] ;
80 REMVARIABLE [OUTPUT] &lt;name&gt; &lt;target&gt; [contextual_tests] ;
81
82 Flow control:
83 JUMP &lt;anchor_name&gt; &lt;target&gt; [contextual_tests] ;
84 WITH &lt;target&gt; [contextual_tests] { [rules] } ;
85 </screen>
86 </section>
87
88 <section id="add">
89 <title>ADD</title>
90 <indexterm>
91 <primary>ADD</primary>
92 </indexterm>
93 <screen>
94 [wordform] ADD &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
95 </screen>
96 <para>
97 Appends tags to matching readings. Will not block for adding further tags, but can be blocked if a reading
98 is considered mapped either via rule type MAP or from input.
99 </para>
100 <screen>
101 ADD (@func £other) TARGET (target) IF (-1 KC) ;
102 </screen>
103 </section>
104
105 <section id="copy">
106 <title>COPY</title>
107 <indexterm>
108 <primary>COPY</primary>
109 </indexterm>
110 <screen>
111 [wordform] COPY &lt;extra tags&gt; [EXCEPT &lt;except tags&gt;] &lt;target&gt; [contextual_tests] ;
112 </screen>
113 <para>
114 Duplicates a reading and adds tags to it. If you don't want to copy previously copied readings,
115 you will have to keep track of that yourself by adding a marker tag.
116 Optionally excludes certain tags from the copy.
117 </para>
118 <screen>
119 COPY (¤copy tags) TARGET (target) - (¤copy) ;
120 COPY (¤copy tags) EXCEPT (not these tags) TARGET (target) - (¤copy) ;
121 </screen>
122 </section>
123
124 <section id="delimit">
125 <title>DELIMIT</title>
126 <indexterm>
127 <primary>DELIMIT</primary>
128 </indexterm>
129 <screen>
130 [wordform] DELIMIT &lt;target&gt; [contextual_tests] ;
131 </screen>
132 <para>
133 This will work as an on-the-fly sentence (disambiguation window) delimiter.
134 When a reading matches a DELIMIT rule's context it will cut off all subsequent
135 cohorts in the current window immediately restart disambiguating with the new
136 window size. This is not and must not be used as a substitute for the DELIMITERS
137 list, but can be useful for cases where the delimiter has to be decided from context.
138 </para>
139 </section>
140
141 <section id="external">
142 <title>EXTERNAL</title>
143 <indexterm>
144 <primary>EXTERNAL</primary>
145 </indexterm>
146 <indexterm>
147 <primary>EXTERNAL ONCE</primary>
148 </indexterm>
149 <indexterm>
150 <primary>EXTERNAL ALWAYS</primary>
151 </indexterm>
152 <screen>
153 [wordform] EXTERNAL ONCE &lt;program&gt; &lt;target&gt; [contextual_tests] ;
154 [wordform] EXTERNAL ALWAYS &lt;program&gt; &lt;target&gt; [contextual_tests] ;
155 </screen>
156 <para>
157 Opens up a persistent pipe to the program and passes it the current window.
158 The ONCE version will only be run once per window, while ALWAYS will be run every time the rule is seen.
159 See the <link linkend="externals">Externals chapter</link> for technical and protocol information.
160 </para>
161 <screen>
162 EXTERNAL ONCE /usr/local/bin/waffles (V) (-1 N) ;
163 EXTERNAL ALWAYS program-in-path (V) (-1 N) ;
164 EXTERNAL ONCE "program with spaces" (V) (-1 N) ;
165 </screen>
166 </section>
167
168 <section id="addcohort">
169 <title>ADDCOHORT</title>
170 <indexterm>
171 <primary>ADDCOHORT</primary>
172 </indexterm>
173 <screen>
174 [wordform] ADDCOHORT &lt;cohort tags&gt; BEFORE|AFTER [WITHCHILD &lt;child_set&gt;|NOCHILD]
175 &lt;target&gt; [contextual_tests] ;
176 </screen>
177 <para>
178 Inserts a new cohort before or after the target. See also <link linkend="grammar-options-addcattach">addcohort-attach</link>.
179 </para>
180 <para>
181 WITHCHILD uses the children of the cohort you're targeting as edges so you can avoid creating cohorts
182 in the middle of another dependency group.
183 If you specify WITHCHILD you will need to provide a set that the children you want to apply must match.
184 The (*) set will match all children.
185 </para>
186 <screen>
187 ADDCOHORT ("&lt;wordform&gt;" "baseform" tags) BEFORE (@waffles) ;
188 ADDCOHORT ("&lt;wordform&gt;" "baseform" tags) AFTER (@waffles) ;
189 </screen>
190 </section>
191
192 <section id="copycohort">
193 <title>COPYCOHORT</title>
194 <indexterm>
195 <primary>COPYCOHORT</primary>
196 </indexterm>
197 <screen>
198 [wordform] COPYCOHORT &lt;added tags&gt; [EXCEPT &lt;removed tags&gt;] &lt;target&gt; [contextual_tests]
199 TO [BEFORE|AFTER] [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;contextual targets&gt; ;
200 [wordform] COPYCOHORT &lt;added tags&gt; [EXCEPT &lt;removed tags&gt;] [BEFORE|AFTER] [WITHCHILD &lt;child_set&gt;|NOCHILD]
201 &lt;target&gt; [contextual_tests] FROM &lt;contextual targets&gt; ;
202 </screen>
203 <para>
204 Copies the current cohort to before or after the contextual target.
205 Or copies a contextual target cohort to before or after the current cohort.
206 The added tags is not optional, but you can specify * to not actually add any tags.
207 </para>
208 <para>
209 The newly added cohort will be dependency-attached to the nearest cohort towards the target.
210 Relations are not currently copied.
211 </para>
212 <para>
213 WITHCHILD uses the children of the cohort you're targeting as edges so you can avoid creating cohorts
214 in the middle of another dependency group.
215 If you specify WITHCHILD you will need to provide a set that the children you want to apply must match.
216 The (*) set will match all children.
217 </para>
218 <screen>
219 CopyCohort (copied) Except (snip) Before WithChild (*) (target) From (1* (from) - (copied)) ;
220 </screen>
221 </section>
222
223 <section id="remcohort">
224 <title>REMCOHORT</title>
225 <indexterm>
226 <primary>REMCOHORT</primary>
227 </indexterm>
228 <screen>
229 [wordform] REMCOHORT &lt;target&gt; [contextual_tests] ;
230 </screen>
231 <para>
232 This will entirely remove a cohort with all its readings from the window.
233 Dependency will be forwarded so that the tree remains intact.
234 Named relations will be deleted.
235 </para>
236 </section>
237
238 <section id="splitcohort">
239 <title>SPLITCOHORT</title>
240 <indexterm>
241 <primary>SPLITCOHORT</primary>
242 </indexterm>
243 <screen>
244 [wordform] SPLITCOHORT &lt;cohort recipe&gt; &lt;target&gt; [contextual_tests] ;
245 </screen>
246 <para>
247 Splits a cohort into multiple new cohorts, with a recipe for which of the new cohorts shall inherit tags,
248 dependency, or named relations. The cohorts are listed in any order you want, and you may use regex captures to
249 fill in wordforms and baseforms. You can list as many cohorts as you want.
250 </para>
251 <para>
252 You can also designate their relative place in the dependency tree with <code>x-&gt;y</code> tags,
253 where <code>x</code> must be the sequential number of the new cohorts starting from 1, and <code>y</code>
254 is which new cohort it should link to.
255 Special value <code>c</code> for <code>x</code> may be used to designate that the cohort should inherit all children,
256 and value <code>p</code> for <code>y</code> designates it is the head of the local tree.
257 You may use <code>c-&gt;p</code> to give the same cohort both roles.
258 The default is that first cohort is the head and last cohort is the tail, and the new cohorts form a simple chain.
259 </para>
260 <para>
261 Similarly, you can use tag <code>R:*</code> to designate which cohort should inherit the named relations.
262 If <code>R:*</code> is not listed, the cohort marked <code>c-&gt;</code> will be used.
263 Thus if neither is listed, default is that the last cohort inherits them.
264 </para>
265 <screen>
266 # Split hyphenated tokens with exactly two parts
267 SPLITCOHORT (
268 # inherit tags with *, and inherit dependency children with c->2
269 "&lt;$1&gt;"v "$1"v tags * tags c->2
270 # inherit named relations with R:*, and inherit dependency parents with 2->p
271 "&lt;$2&gt;"v "$2"v tags go here R:* 2->p
272 ) ("&lt;([^-]+)-([^-]+)&gt;"r other tags) (1* (context)) ;
273 </screen>
274 </section>
275
276 <section id="mergecohorts">
277 <title>MERGECOHORTS</title>
278 <indexterm>
279 <primary>MERGECOHORTS</primary>
280 </indexterm>
281 <screen>
282 [wordform] MERGECOHORTS &lt;cohort recipe&gt; &lt;target&gt; [contextual_tests] WITH &lt;contextual targets&gt; ;
283 </screen>
284 <para>
285 Removes the target cohort and all cohorts matched by the contextual targets and inserts a new cohort in the target's position.
286 The removed cohorts need not be sequential.
287 In the cohort recipe, the special tag <code>*</code> will copy all tags from the insert position cohort to that spot.
288 </para>
289 <screen>
290 # Given input
291 "&lt;March&gt;"
292 "March" month
293 "&lt;2nd&gt;"
294 "2nd" ordinal
295
296 # The rule
297 MergeCohorts ("&lt;$1 $2&gt;"v "$1 $2"v date) ("&lt;(.+)&gt;"r month) WITH (1 ("&lt;(.+)&gt;"r ordinal)) ;
298
299 # would yield
300 "&lt;March 2nd&gt;"
301 "March 2nd" date
302 </screen>
303 <para>
304 Each contextual target is a contextual test where by default the last matched cohort is the cohort you want removed.
305 In a longer chain, you can override which cohort is to be removed with modifier <code>w</code> such as <code>(1w ("word") LINK 1 (condition on word))</code>.
306 Each contextual target can only contribute 1 cohort for the merge - multiple <code>w</code> in a single test is not possible.
307 </para>
308 <para>
309 Also, modifier <code>A</code> will override where the insertion is to take place - if set, the insertion happens after the cohort marked as <code>A</code>.
310 Modifier <code>A</code> does not imply <code>w</code> - it is possible to insert in a different position than any removed cohort.
311 <code>A</code> will suppress that contextual target from yielding a cohort, but <code>w</code> can force it.
312 </para>
313 <screen>
314 WITH examples:
315 # Normal, last cohort in the chain, "word", is marked for removal
316 (1 ("the") LINK 1 ("word"))
317
318 # Sets the insert position after "the" and requires "word" follows that cohort
319 # Does not mark any cohort for removal
320 (1A ("the") LINK 1 ("word"))
321
322 # Marks "the" for removal, and merely requires "word" follows that cohort
323 (1w ("the") LINK 1 ("word"))
324
325 # Sets the insert position after "the" and requires "word" follows that cohort
326 # Also marks "word" for removal
327 (1A ("the") LINK 1w ("word"))
328 </screen>
329 <para>
330 By default, the created cohort will inherit all dependencies and relations of the merged cohorts.
331 Rule flag <link linkend="rule-options-detach">DETACH</link> will prevent that behavior.
332 </para>
333 </section>
334
335 <section id="move-switch">
336 <title>MOVE, SWITCH</title>
337 <indexterm>
338 <primary>MOVE</primary>
339 </indexterm>
340 <indexterm>
341 <primary>SWITCH</primary>
342 </indexterm>
343 <screen>
344 [wordform] MOVE [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;target&gt; [contextual_tests]
345 AFTER [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;contextual_target&gt; [contextual_tests] ;
346 [wordform] MOVE [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;target&gt; [contextual_tests]
347 BEFORE [WITHCHILD &lt;child_set&gt;|NOCHILD] &lt;contextual_target&gt; [contextual_tests] ;
348 [wordform] SWITCH &lt;target&gt; [contextual_tests] WITH &lt;contextual_target&gt; [contextual_tests] ;
349 </screen>
350 <para>
351 Allows re-arranging of cohorts. The option WITHCHILD will cause the movement of the cohort plus all children
352 of the cohort, maintaining their internal order. Default is NOCHILD which moves only the one cohort.
353 SWITCH does not take options.
354 </para>
355 <para>
356 If you specify WITHCHILD you will need to provide a set that the children you want to apply must match.
357 The (*) set will match all children.
358 </para>
359 <para>
360 The first WITHCHILD specifies which children you want moved - the target cohorts.
361 The second WITHCHILD uses the children of the cohort you're moving to as edges so you can avoid moving into
362 another dependency group - the anchor cohorts.
363 </para>
364 <para>
365 WITHCHILD will match direct children only and then gobble up all descendents of the matched children.
366 If the target cohort is a descendent of the anchor, all target cohorts are removed from the anchor cohorts.
367 Otherwise, the inverse is done. This allows maximal movement while retaining chosen subtree integrity.
368 </para>
369 </section>
370
371 <section id="replace">
372 <title>REPLACE</title>
373 <indexterm>
374 <primary>REPLACE</primary>
375 </indexterm>
376 <screen>
377 [wordform] REPLACE &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
378 </screen>
379 <para>
380 Removes all tags from a reading except the base form, then appends the given tags.
381 Cannot target readings that are considered mapped due to earlier MAP rules or from input.
382 </para>
383 <screen>
384 REPLACE (&lt;v-act&gt; V INF @func) TARGET (target);
385 </screen>
386 </section>
387
388 <section id="append">
389 <title>APPEND</title>
390 <indexterm>
391 <primary>APPEND</primary>
392 </indexterm>
393 <screen>
394 [wordform] APPEND &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
395 </screen>
396 <para>
397 Appends a reading to the matched cohort, so be sure the tags include a baseform.
398 </para>
399 <screen>
400 APPEND ("jump" &lt;v-act&gt; V INF @func) TARGET (target);
401 </screen>
402 </section>
403
404 <section id="substitute">
405 <title>SUBSTITUTE</title>
406 <indexterm>
407 <primary>SUBSTITUTE</primary>
408 </indexterm>
409 <screen>
410 [wordform] SUBSTITUTE &lt;locate tags&gt; &lt;replacement tags&gt; &lt;target&gt; [contextual_tests] ;
411 </screen>
412 <para>
413 Replaces the tags in the first list with the tags in the second list.
414 If none of the tags in the first list are found, no insertion is done.
415 If only some of the tags are found, the insertion happens at the last removed tag, which may cause tags to be out of your desired order.
416 To prevent this, also have important tags as part of the target.
417 This works as in VISLCG, but the replacement tags may be the * tag to signify a nil replacement,
418 allowing for clean removal of tags in a reading. For example, to remove TAG do:
419 </para>
420 <screen>
421 SUBSTITUTE (TAG) (*) TARGET (TAG) ;
422 </screen>
423 </section>
424
425 <section id="setvariable">
426 <title>SETVARIABLE</title>
427 <indexterm>
428 <primary>SETVARIABLE</primary>
429 <secondary>OUTPUT</secondary>
430 </indexterm>
431 <screen>
432 [wordform] SETVARIABLE [OUTPUT] &lt;name&gt; &lt;value&gt; &lt;target&gt; [contextual_tests] ;
433 </screen>
434 <para>
435 Sets a <link linkend="global-variables">global variable</link> to a given value.
436 If you don't care about the value you can just set it to 1 or *.
437 </para>
438 <para>
439 If you provide the optional OUTPUT flag, then an equivalent <link linkend="cmd-setvar">STREAMCMD:SETVAR</link>
440 will be output before the currently active window.
441 </para>
442 <screen>
443 SETVARIABLE (news) (*) (@headline) ;
444 SETVARIABLE (year) (1764) ("Jozef") (-2 ("Arch") LINK 1 ("Duke")) ;
445 </screen>
446 </section>
447
448 <section id="remvariable">
449 <title>REMVARIABLE</title>
450 <indexterm>
451 <primary>REMVARIABLE</primary>
452 <secondary>OUTPUT</secondary>
453 </indexterm>
454 <screen>
455 [wordform] REMVARIABLE [OUTPUT] &lt;name&gt; &lt;target&gt; [contextual_tests] ;
456 </screen>
457 <para>
458 Unsets a <link linkend="global-variables">global variable</link>.
459 </para>
460 <para>
461 If you provide the optional OUTPUT flag, then an equivalent <link linkend="cmd-remvar">STREAMCMD:REMVAR</link>
462 will be output before the currently active window.
463 </para>
464 <screen>
465 REMVARIABLE (news) (@stanza) ;
466 REMVARIABLE (year) (@timeless) ;
467 </screen>
468 </section>
469
470 <section id="map">
471 <title>MAP</title>
472 <indexterm>
473 <primary>MAP</primary>
474 </indexterm>
475 <screen>
476 [wordform] MAP &lt;tags&gt; &lt;target&gt; [contextual_tests] ;
477 </screen>
478 <para>
479 Appends tags to matching readings, and blocks other MAP, ADD, and REPLACE rules from targetting those readings.
480 Cannot target readings that are considered mapped due to earlier MAP rules or from input.
481 </para>
482 <screen>
483 MAP (@func £other) TARGET (target) IF (-1 KC) ;
484 </screen>
485 </section>
486
487 <section id="unmap">
488 <title>UNMAP</title>
489 <indexterm>
490 <primary>UNMAP</primary>
491 </indexterm>
492 <screen>
493 [wordform] UNMAP &lt;target&gt; [contextual_tests] ;
494 </screen>
495 <para>
496 Removes the mapping tag of a reading and lets ADD and MAP target the reading again.
497 By default it will only act if the cohort has exactly one reading, but marking the rule UNSAFE
498 lets it act on multiple readings.
499 </para>
500 <screen>
501 UNMAP (TAG) ;
502 UNMAP UNSAFE (TAG) ;
503 </screen>
504 </section>
505
506 <section id="protect">
507 <title>PROTECT</title>
508 <indexterm>
509 <primary>PROTECT</primary>
510 </indexterm>
511 <screen>
512 [wordform] PROTECT &lt;target&gt; [contextual_tests] ;
513 </screen>
514 <para>
515 Protects the matched reading from removal and modification.
516 Once protected, no other rule can target the reading, except <link linkend="unprotect">UNPROTECT</link>.
517 </para>
518 </section>
519
520 <section id="unprotect">
521 <title>UNPROTECT</title>
522 <indexterm>
523 <primary>UNPROTECT</primary>
524 </indexterm>
525 <screen>
526 [wordform] UNPROTECT &lt;target&gt; [contextual_tests] ;
527 </screen>
528 <para>
529 Lifts the protection of <link linkend="protect">PROTECT</link>, so that other rules can once again target the reading.
530 </para>
531 </section>
532
533 <section id="select">
534 <title>SELECT</title>
535 <indexterm>
536 <primary>SELECT</primary>
537 </indexterm>
538 <screen>
539 [wordform] SELECT &lt;target&gt; [contextual_tests] ;
540 </screen>
541 <para>
542 Deletes all readings in the cohort except the ones matching the target set.
543 </para>
544 </section>
545
546 <section id="remove">
547 <title>REMOVE</title>
548 <indexterm>
549 <primary>REMOVE</primary>
550 </indexterm>
551 <screen>
552 [wordform] REMOVE &lt;target&gt; [contextual_tests] ;
553 </screen>
554 <para>
555 Deletes the readings matching the target set.
556 </para>
557 </section>
558
559 <section id="iff">
560 <title>IFF</title>
561 <indexterm>
562 <primary>IFF</primary>
563 </indexterm>
564 <screen>
565 [wordform] IFF &lt;target&gt; [contextual_tests] ;
566 </screen>
567 <para>
568 If the contextual tests are satisfied, <link linkend="select">select</link> the readings matching the target set. Otherwise, <link linkend="select">remove</link> the readings matching the target set.
569 <emphasis>
570 This had so little utility that VISLCG did not implement it. We have chosen to implement it in CG-3 because there was no reason to omit it, but admit there are almost no uses for it.
571 </emphasis>
572 </para>
573 </section>
574
575 <section id="restore">
576 <title>RESTORE</title>
577 <indexterm>
578 <primary>RESTORE</primary>
579 </indexterm>
580 <screen>
581 [wordform] RESTORE [DELAYED|IGNORED] &lt;restore_target&gt; &lt;target&gt; [contextual_tests] ;
582 </screen>
583 <para>
584 Restores readings that were previously removed. Only restores the readings matching the <code>restore_target</code> set.
585 If either of the flags <link linkend="rule-options-delayed">DELAYED</link> or <link linkend="rule-options-ignored">IGNORED</link> are enabled, the rule will look in those special buffers for the readings restore.
586 If neither flag, or the <link linkend="rule-options-immediate">IMMEDIATE</link> flag, is enabled, the rule will restore ordinarily remove readings.
587 </para>
588 <screen>
589 RESTORE (@func) TARGET (target) IF (-1 KC) ;
590 RESTORE DELAYED (@func) TARGET (target) IF (-1 KC) ;
591 RESTORE IGNORED (@func) TARGET (target) IF (-1 KC) ;
592 </screen>
593 </section>
594
595 <section id="taglists-sets">
596 <title>Tag Lists Can Be Sets</title>
597 <para>
598 For the rule types MAP, ADD, REPLACE, APPEND, COPY, SUBSTITUTE, ADDRELATION(S), SETRELATION(S), and REMRELATION(S),
599 the tag lists can be sets instead, including <link linkend="set-unification-tag">$$sets</link>
600 and <link linkend="set-unification-set">&amp;&amp;sets</link>.
601 This is useful for manipulating tags that you want to pull in from a context.
602 </para>
603 <para>
604 The sets are resolved and reduced to a list of tags during rule application. If the set reduces to multiple tags
605 where only one is required (such as for the Relation rules), only the first tag is used.
606 </para>
607 <screen>
608 LIST ROLE = &lt;human&gt; &lt;anim&gt; &lt;inanim&gt; (&lt;bench&gt; &lt;table&gt;) ;
609 MAP $$ROLE (target tags) (-1 KC) (-2C $$ROLE) ;
610 </screen>
611 </section>
612
613 <section id="named-rules">
614 <title>Named Rules</title>
615 <indexterm>
616 <primary>rule name</primary>
617 </indexterm>
618 <indexterm>
619 <primary>named rules</primary>
620 </indexterm>
621 <screen>
622 [wordform] MAP:rule_name &lt;tag&gt; &lt;target&gt; [contextual_tests] ;
623 [wordform] SELECT:rule_name &lt;target&gt; [contextual_tests] ;
624 </screen>
625 <para>
626 In certain cases you may want to name a rule to be able to refer to the same
627 rule across grammar revisions, as otherwise the rule line number may change.
628 It is optional to name rules, and names do not have to be unique which makes it easier to group
629 rules for statistics or tracing purposes.
630 The name of a rule is used in tracing and debug output in addition to the line number.
631 </para>
632 </section>
633
634 <section id="flow-control">
635 <title>Flow Control: JUMP, ANCHOR</title>
636 <indexterm>
637 <primary>JUMP</primary>
638 </indexterm>
639 <indexterm>
640 <primary>ANCHOR</primary>
641 </indexterm>
642 <para>
643 JUMP will allow you to mark named anchors and jump to them based on a context.
644 In this manner you can skip or repeat certain rules.
645 </para>
646 <screen>
647 ANCHOR &lt;anchor_name&gt; ;
648 SECTION [anchor_name ;]
649 [wordform] JUMP &lt;anchor_name&gt; &lt;target&gt; [contextual_tests] ;
650 </screen>
651 <para>
652 An anchor can be created explicitly with keyword ANCHOR. Sections can optionally be given a name which will make
653 them explicit anchor points. All named rules are also anchor points, but with lower precedence than explicit anchors,
654 and in the case of multiple rules with the same name the first such named rule is the anchor point for that name.
655 There are also two special anchors <code>START</code> and <code>END</code> which represent line 0 and infinity
656 respectively; jumping to START will re-run all currently active rules, while jumping to END will skip all remaining
657 rules.
658 </para>
659 </section>
660
661 <section id="with">
662 <title>WITH</title>
663 <indexterm>
664 <primary>WITH</primary>
665 </indexterm>
666 <screen>
667 WITH &lt;target&gt; [contextual_tests] { [rules] } ;
668 </screen>
669 <para>
670 Matches a pattern and runs a list of rules on the matched cohort only.
671 </para>
672 <screen>
673 WITH (det def) {
674 MAP @det (*) ;
675 SETPARENT (*) TO (1* (n)) ;
676 } ;
677
678 # is equivalent to
679
680 MAP @det (det def) ;
681 SETPARENT (det def) TO (1* (n)) ;
682 </screen>
683 <para>
684 Additionally, WITH creates magic sets _C1_ through _C9_ referring to the cohorts matched by the outer contextual tests. If _MARK_ is set, it will also be accessible to the inner rules. These sets are also accessible with the jump contextual positions jC1 through jC9 and jM. When using linked tests, the values of these magic sets can be controled with <link linkend="test-mark-with">the w contextual specifier</link>.
685 </para>
686 <screen>
687 # the following input
688 "&lt;the&gt;"
689 "the" det def
690 "&lt;silly&gt;"
691 "silly" adj
692 "&lt;example&gt;"
693 "example" n sg
694
695 # to this rule
696 WITH (n) IF (-1 (adj)) (-2 (det def)) {
697 SETCHILD REPEAT (*) TO (-1* _C1_ OR _C2_) (NOT p (*)) ;
698 } ;
699
700 # would output
701 "&lt;the&gt;"
702 "the" det def #1-&gt;3
703 "&lt;silly&gt;"
704 "silly" adj #2-&gt;3
705 "&lt;example&gt;"
706 "example" n sg #3-&gt;3
707
708 # this rule is approximately equivalent
709 WITH (n) IF (-1 (adj)) (-2 (det def)) {
710 SETCHILD (*) TO (jC1 (*)) (NOT p (*)) ;
711 SETCHILD (*) TO (jC2 (*)) (NOT p (*)) ;
712 } ;
713 </screen>
714 <para>
715 Note that rules inside WITH are only run once each time WITH is run, unless they have REPEAT, and thus without REPEAT, the rule above would otherwise attach only the adjective.
716 </para>
717 </section>
718
719 <section id="rule-options">
720 <title>Rule Options</title>
721 <para>
722 Rules can have options that affect their behavior.
723 Multiple options can be combined per rule and the order is not important, just separate them with space.
724 </para>
725 <screen>
726 # Remove readings with (unwanted) even if it is the last reading.
727 REMOVE UNSAFE (unwanted) ;
728
729 # Attach daughter to mother, even if doing so would cause a loop.
730 SETPARENT ALLOWLOOP (daughter) TO (-1* (mother)) ;
731 </screen>
732
733 <section id="rule-options-nearest">
734 <title>NEAREST</title>
735 <indexterm>
736 <primary>NEAREST</primary>
737 </indexterm>
738 <para>
739 Applicable for rules SETPARENT and SETCHILD.
740 Not compatible with option ALLOWLOOP.
741 </para>
742 <para>
743 Normally, if SETPARENT or SETCHILD cannot attach because doing so would cause a loop, they will seek
744 onwards from that position until a valid target is found that does not cause a loop.
745 Setting NEAREST forces them to stop at the first found candidate.
746 </para>
747 </section>
748
749 <section id="rule-options-allowloop">
750 <title>ALLOWLOOP</title>
751 <indexterm>
752 <primary>ALLOWLOOP</primary>
753 </indexterm>
754 <para>
755 Applicable for rules SETPARENT and SETCHILD.
756 Not compatible with option NEAREST.
757 </para>
758 <para>
759 Normally, SETPARENT and SETCHILD cannot attach if doing so would cause a loop.
760 Setting ALLOWLOOP forces the attachment even in such a case.
761 </para>
762 </section>
763
764 <section id="rule-options-allowcross">
765 <title>ALLOWCROSS</title>
766 <indexterm>
767 <primary>ALLOWCROSS</primary>
768 </indexterm>
769 <para>
770 Applicable for rules SETPARENT and SETCHILD.
771 </para>
772 <para>
773 If command line flag --dep-no-crossing is on,
774 SETPARENT and SETCHILD cannot attach if doing so would cause crossing branches.
775 Setting ALLOWCROSS forces the attachment even in such a case.
776 </para>
777 </section>
778
779 <section id="rule-options-delayed">
780 <title>DELAYED</title>
781 <indexterm>
782 <primary>DELAYED</primary>
783 </indexterm>
784 <para>
785 Applicable for rules SELECT, REMOVE, RESTORE, and IFF.
786 Not compatible with options IGNORED or IMMEDIATE.
787 </para>
788 <para>
789 Option DELAYED causes readings that otherwise would have been put in the deleted buffer to be put in
790 a special delayed buffer, in the grey zone between living and dead.
791 Delayed readings are removed at the end of the run.
792 </para>
793 <para>
794 Delayed readings can be looked at by contextual tests of rules that have option LOOKDELAYED,
795 or if the contextual test has position 'd'.
796 </para>
797 </section>
798
799 <section id="rule-options-immediate">
800 <title>IMMEDIATE</title>
801 <indexterm>
802 <primary>IMMEDIATE</primary>
803 </indexterm>
804 <para>
805 Applicable for rules SELECT, REMOVE, RESTORE, and IFF.
806 Not compatible with option DELAYED or IGNORED.
807 </para>
808 <para>
809 Option IMMEDIATE causes readings that otherwise would have been put in the special delayed buffer to be put in
810 the deleted buffer. This is mainly used to selectively override a global DELAYED flag
811 as rules are by default immediate.
812 </para>
813 </section>
814
815 <section id="rule-options-ignored">
816 <title>IGNORED</title>
817 <indexterm>
818 <primary>IGNORED</primary>
819 </indexterm>
820 <para>
821 Applicable for rules REMOVE and RESTORE.
822 Not compatible with options DELAYED or IMMEDIATE.
823 </para>
824 <para>
825 Option IGNORED causes readings that otherwise would have been put in the deleted buffer to be put in
826 a special ignored buffer, in the grey zone between living and dead.
827 Unlike delayed readings, ignored readings get restored at the end of the run.
828 </para>
829 <para>
830 Ignored readings can be looked at by contextual tests of rules that have option LOOKIGNORED,
831 or if the contextual test has position 'I'.
832 </para>
833 </section>
834
835 <section id="rule-options-lookdelayed">
836 <title>LOOKDELAYED</title>
837 <indexterm>
838 <primary>LOOKDELAYED</primary>
839 </indexterm>
840 <para>
841 Applicable for all rules.
842 </para>
843 <para>
844 Option LOOKDELAYED puts <link linkend="test-deleted-delayed">contextual position 'd'</link> on all tests done by that rule,
845 allowing them all to see delayed readings.
846 </para>
847 </section>
848
849 <section id="rule-options-lookignored">
850 <title>LOOKIGNORED</title>
851 <indexterm>
852 <primary>LOOKIGNORED</primary>
853 </indexterm>
854 <para>
855 Applicable for all rules.
856 </para>
857 <para>
858 Option LOOKIGNORED puts <link linkend="test-deleted-ignored">contextual position 'I'</link> on all tests done by that rule,
859 allowing them all to see ignored readings.
860 </para>
861 </section>
862
863 <section id="rule-options-lookdeleted">
864 <title>LOOKDELETED</title>
865 <indexterm>
866 <primary>LOOKDELETED</primary>
867 </indexterm>
868 <para>
869 Applicable for all rules.
870 </para>
871 <para>
872 Option LOOKDELETED puts <link linkend="test-deleted-deleted">contextual position 'D'</link> on all tests done by that rule,
873 allowing them all to see deleted readings.
874 </para>
875 </section>
876
877 <section id="rule-options-unmaplast">
878 <title>UNMAPLAST</title>
879 <indexterm>
880 <primary>UNMAPLAST</primary>
881 </indexterm>
882 <para>
883 Applicable for rules REMOVE and IFF.
884 Not compatible with option SAFE.
885 </para>
886 <para>
887 Normally, REMOVE and IFF will consider mapping tags as separate readings, and attempting to remove the last
888 mapping is the same as removing the last reading which requires UNSAFE. Setting flag UNMAPLAST causes it to
889 instead remove the final mapping tag but leave the reading otherwise untouched.
890 </para>
891 <para>
892 A rule <code>REMOVE UNMAPLAST @MappingList ;</code> is logically equivalent to
893 <code>REMOVE @MappingList ; UNMAP @MappingList ;</code>
894 </para>
895 </section>
896
897 <section id="rule-options-unsafe">
898 <title>UNSAFE</title>
899 <indexterm>
900 <primary>UNSAFE</primary>
901 </indexterm>
902 <para>
903 Regarding mapping, flag is applicable for rules REMOVE and IFF and UNMAP.
904 Regarding dependency, flag is applicable for SETPARENT.
905 Not compatible with option SAFE.
906 </para>
907 <para>
908 Normally, REMOVE and IFF cannot remove the last reading of a cohort.
909 Setting option UNSAFE allows them to do so.
910 </para>
911 <para>
912 For UNMAP, marking it UNSAFE allows it to work on more than the last reading in the cohort.
913 </para>
914 <para>
915 For SETPARENT, UNSAFE counters a global safe-setparent option.
916 </para>
917 </section>
918
919 <section id="rule-options-safe">
920 <title>SAFE</title>
921 <indexterm>
922 <primary>SAFE</primary>
923 </indexterm>
924 <para>
925 Regarding mapping, flag is applicable for rules REMOVE and IFF and UNMAP.
926 Regarding dependency, flag is applicable for SETPARENT.
927 Not compatible with option UNSAFE.
928 </para>
929 <para>
930 SAFE prevents REMOVE and IFF from removing the last reading of a cohort.
931 Mainly used to selectively override global --unsafe mode.
932 </para>
933 <para>
934 For UNMAP, marking it SAFE only lets it act if the cohort has exactly one reading.
935 </para>
936 <para>
937 For SETPARENT, SAFE prevents running if the cohort already has a parent.
938 </para>
939 </section>
940
941 <section id="rule-options-rememberx">
942 <title>REMEMBERX</title>
943 <indexterm>
944 <primary>REMEMBERX</primary>
945 </indexterm>
946 <para>
947 Applicable for all rules.
948 Not compatible with option RESETX.
949 </para>
950 <para>
951 Makes the contextual option X carry over to subsequent tests in the rule, as opposed to resetting itself
952 to the rule's target per test. Useful for complex jumps with the X and x options.
953 </para>
954 </section>
955
956 <section id="rule-options-resetx">
957 <title>RESETX</title>
958 <indexterm>
959 <primary>RESETX</primary>
960 </indexterm>
961 <para>
962 Applicable for all rules.
963 Not compatible with option REMEMBERX.
964 </para>
965 <para>
966 Default behavior.
967 Resets the mark for contextual option x to the rule's target on each test.
968 Used to counter a global REMEMBERX.
969 </para>
970 </section>
971
972 <section id="rule-options-keeporder">
973 <title>KEEPORDER</title>
974 <indexterm>
975 <primary>KEEPORDER</primary>
976 </indexterm>
977 <para>
978 Applicable for all rules.
979 Not compatible with option VARYORDER.
980 </para>
981 <para>
982 Prevents the re-ordering of contextual tests.
983 Useful in cases where a unifying set is not in the target of the rule.
984 </para>
985 <para>
986 You almost certainly need KEEPORDER if you use regex capture and varstring in separate contextual tests,
987 or if you use the special baseform or wordform regexes in unification in separate contextual tests.
988 </para>
989 </section>
990
991 <section id="rule-options-varyorder">
992 <title>VARYORDER</title>
993 <indexterm>
994 <primary>VARYORDER</primary>
995 </indexterm>
996 <para>
997 Applicable for all rules.
998 Not compatible with option KEEPORDER.
999 </para>
1000 <para>
1001 Allows the re-ordering of contextual tests.
1002 Used to selectively override a global KEEPORDER flag as test order is by default fluid.
1003 </para>
1004 </section>
1005
1006 <section id="rule-options-encl-inner">
1007 <title>ENCL_INNER</title>
1008 <indexterm>
1009 <primary>ENCL_INNER</primary>
1010 </indexterm>
1011 <para>
1012 Applicable for all rules.
1013 Not compatible with other ENCL_* options.
1014 </para>
1015 <para>
1016 Rules with ENCL_INNER will only be run inside the currently active parantheses enclosure.
1017 If the current window has no enclosures, the rule will not be run.
1018 </para>
1019 </section>
1020
1021 <section id="rule-options-encl-outer">
1022 <title>ENCL_OUTER</title>
1023 <indexterm>
1024 <primary>ENCL_OUTER</primary>
1025 </indexterm>
1026 <para>
1027 Applicable for all rules.
1028 Not compatible with other ENCL_* options.
1029 </para>
1030 <para>
1031 Rules with ENCL_OUTER will only be run outside the currently active parentheses enclosure.
1032 Previously expanded enclosures will be seen as outside on subsequent runs.
1033 If the current window has no enclosures, the rule will be run as normal.
1034 </para>
1035 </section>
1036
1037 <section id="rule-options-encl-final">
1038 <title>ENCL_FINAL</title>
1039 <indexterm>
1040 <primary>ENCL_FINAL</primary>
1041 </indexterm>
1042 <para>
1043 Applicable for all rules.
1044 Not compatible with other ENCL_* options.
1045 </para>
1046 <para>
1047 Rules with ENCL_FINAL will only be run once all parentheses enclosures have been expanded.
1048 If the current window has no enclosures, the rule will be run as normal.
1049 </para>
1050 </section>
1051
1052 <section id="rule-options-encl-any">
1053 <title>ENCL_ANY</title>
1054 <indexterm>
1055 <primary>ENCL_ANY</primary>
1056 </indexterm>
1057 <para>
1058 Applicable for all rules.
1059 Not compatible with other ENCL_* options.
1060 </para>
1061 <para>
1062 The default behavior.
1063 Used to counter other glocal ENCL_* flags.
1064 </para>
1065 </section>
1066
1067 <section id="rule-options-withchild">
1068 <title>WITHCHILD</title>
1069 <indexterm>
1070 <primary>WITHCHILD</primary>
1071 </indexterm>
1072 <para>
1073 Applicable for rule type MOVE.
1074 Not compatible with option NOCHILD.
1075 </para>
1076 <para>
1077 Normally, MOVE only moves a single cohort. Setting option WITHCHILD moves all its children along with it.
1078 </para>
1079 </section>
1080
1081 <section id="rule-options-nochild">
1082 <title>NOCHILD</title>
1083 <indexterm>
1084 <primary>NOCHILD</primary>
1085 </indexterm>
1086 <para>
1087 Applicable for rule type MOVE.
1088 Not compatible with option WITHCHILD.
1089 </para>
1090 <para>
1091 If the global option WITHCHILD is on, NOCHILD will turn it off for a single MOVE rule.
1092 </para>
1093 </section>
1094
1095 <section id="rule-options-iterate">
1096 <title>ITERATE</title>
1097 <indexterm>
1098 <primary>ITERATE</primary>
1099 </indexterm>
1100 <para>
1101 Applicable for all rule types.
1102 Not compatible with option NOITERATE.
1103 </para>
1104 <para>
1105 If the rule does anything that changes the state of the window, ITERATE forces a reiteration of the sections.
1106 Normally, only changes caused by rule types SELECT, REMOVE, IFF, DELIMIT, REMCOHORT, MOVE, and SWITCH will rerun the sections.
1107 </para>
1108 </section>
1109
1110 <section id="rule-options-noiterate">
1111 <title>NOITERATE</title>
1112 <indexterm>
1113 <primary>NOITERATE</primary>
1114 </indexterm>
1115 <para>
1116 Applicable for all rule types.
1117 Not compatible with option ITERATE.
1118 </para>
1119 <para>
1120 Even if the rule does change the state of the window, NOITERATE prevents the rule from causing a reiteration of the sections.
1121 </para>
1122 </section>
1123
1124 <section id="rule-options-reverse">
1125 <title>REVERSE</title>
1126 <indexterm>
1127 <primary>REVERSE</primary>
1128 </indexterm>
1129 <para>
1130 Applicable for rule types SETPARENT, SETCHILD, MOVE, SWITCH, ADDRELATION(S), SETRELATION(S), REMRELATION(S).
1131 </para>
1132 <para>
1133 Reverses the active cohorts. E.g., effectively turns a SETPARENT into a SETCHILD.
1134 </para>
1135 </section>
1136
1137 <section id="rule-options-subn">
1138 <title>SUB:N</title>
1139 <para>
1140 See the <link linkend="sub-grammar-subn">Sub-Readings SUB:N section</link>.
1141 </para>
1142 </section>
1143
1144 <section id="rule-options-output">
1145 <title>OUTPUT</title>
1146 <indexterm>
1147 <primary>OUTPUT</primary>
1148 </indexterm>
1149 <para>
1150 Applicable for rule types SETVARIABLE and REMVARIABLE.
1151 </para>
1152 <para>
1153 Causes a <link linkend="cmd-setvar">STREAMCMD</link> to be output for the given action.
1154 </para>
1155 </section>
1156
1157 <section id="rule-options-repeat">
1158 <title>REPEAT</title>
1159 <indexterm>
1160 <primary>REPEAT</primary>
1161 </indexterm>
1162 <para>
1163 Applicable for all rule types.
1164 </para>
1165 <para>
1166 If the rule does anything that changes the state of the window, REPEAT forces the rule to run through the
1167 window again after the current pass. Does not by itself cause a full section reiteration.
1168 Useful for making <link linkend="substitute">SUBSTITUTE</link> remove all matching tags instead of just one.
1169 </para>
1170 </section>
1171
1172 <section id="rule-options-nomapped">
1173 <title>NOMAPPED</title>
1174 <indexterm>
1175 <primary>NOMAPPED</primary>
1176 </indexterm>
1177 <para>
1178 Applicable for all rule types.
1179 </para>
1180 <para>
1181 NOMAPPED prevents the rule from running on mapped readings.
1182 A reading is considered mapped either via rule type MAP or from input.
1183 </para>
1184 </section>
1185
1186 <section id="rule-options-noparent">
1187 <title>NOPARENT</title>
1188 <indexterm>
1189 <primary>NOPARENT</primary>
1190 </indexterm>
1191 <para>
1192 Applicable for all rule types.
1193 </para>
1194 <para>
1195 NOPARENT prevents the rule from running on cohorts that have a dependency parent.
1196 </para>
1197 </section>
1198
1199 <section id="rule-options-detach">
1200 <title>DETACH</title>
1201 <indexterm>
1202 <primary>DETACH</primary>
1203 </indexterm>
1204 <para>
1205 Applicable for rule type MERGECOHORTS.
1206 </para>
1207 <para>
1208 Prevents the cohort created by the rule from inheriting all dependencies and relations of the merged cohorts.
1209 </para>
1210 </section>
1211 </section>
1212
1213 </chapter>