Debian Codegraph @

manual/contexts.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="contexts">
5 <title>Contextual Tests</title>
6
7 <section id="test-position">
8 <title>Position Element Order</title>
9 <para>
10 CG-3 is not very strict with how a contextual position looks. Elements such as ** and C can be
11 anywhere before or after the offset number, and even the - for negative offsets does not have
12 to be near the number.
13 </para>
14 <para>
15 Examples of valid positions:
16 <screen>
17 *-1
18 1**-
19 W*2C
20 0**&gt;
21 cC
22 CsW
23 </screen>
24 </para>
25 </section>
26
27 <section id="test-number">
28 <title>1, 2, 3, etc</title>
29 <indexterm>
30 <primary>1</primary>
31 </indexterm>
32 <para>
33 A number indicates the topological offset from the rule target or linked cohort that the test should start at. For scanning tests, the sign of the number also influences which direction to scan. Positive numbers both start right and scan towards the right, and negative both start left and scan towards the left.
34 </para>
35 <screen>
36 # Test whether the cohort to the immediate right matches the set N
37 (1 N)
38
39 # Test whether the cohort two to the left, or any other cohorts leftwards of that, matches the set V
40 (-2* V)
41 </screen>
42 <para>
43 If the offset exceeds the window boundaries, the match proceeds as-if it was against a null cohort. For normal tests this means they automatically fail, and NOT and NEGATE tests will succeed.
44 </para>
45 </section>
46
47 <section id="test-absolute">
48 <title>@</title>
49 <indexterm>
50 <primary>@</primary>
51 </indexterm>
52 <para>
53 '@' is the topological absolute position in the window. It is often used to start a test at the beginning of the sentence without having to scan for <code>(-1* &gt;&gt;&gt;)</code> to find it. Positive numbers are offsets from the start of the window, and negative numbers are from the end of the window. Thus '@1' is the first cohort and '@-1' is the last cohort.
54 </para>
55 <para>
56 Special cases combined with window spanning: '@1&lt;' is the first word of the previous window, '@-1&lt;' is the last word of the previous window, '@1&gt;' is the first word of the next window, and '@-1&gt;' is the last word of the next window.
57 </para>
58 <screen>
59 # Test whether the first cohort in the window matches the set N
60 (@1 N)
61
62 # Test whether the last cohort in the window is a full stop
63 (@-1 ("."))
64 </screen>
65 </section>
66
67 <section id="test-careful">
68 <title>C</title>
69 <indexterm>
70 <primary>C</primary>
71 </indexterm>
72 <para>
73 'C' causes the test to be performed in a careful manner, this is it requires that all readings match the set. Normally a test such as <code>(1 N)</code> tests whether any reading matches the set N, but <code>(1C N)</code> requires that all readings match N.
74 </para>
75 </section>
76
77 <section id="test-not">
78 <title>NOT</title>
79 <indexterm>
80 <primary>NOT</primary>
81 </indexterm>
82 <para>
83 NOT will invert the result of the immediately following test.
84 </para>
85 <screen>
86 # The following cohort, if it exists, must not match the set N
87 (NOT 1 N)
88 </screen>
89 </section>
90
91 <section id="test-negate">
92 <title>NEGATE</title>
93 <indexterm>
94 <primary>NEGATE</primary>
95 </indexterm>
96 <para>
97 NEGATE is similar to, yet not the same as, NOT. Where NOT will invert the result of only the
98 immediately following test, NEGATE will invert the result of the entire LINK'ed chain that follows.
99 NEGATE is thus usually used at the beginning of a test.
100 <emphasis>
101 VISLCG emulated the NEGATE functionality for tests that started with NOT.
102 </emphasis>
103 </para>
104 </section>
105
106 <section id="test-scanning">
107 <title>Scanning</title>
108 <indexterm>
109 <primary>*</primary>
110 </indexterm>
111 <indexterm>
112 <primary>**</primary>
113 </indexterm>
114 <para>
115 '*' and '**' start at the given offset and then continues looking in that direction until they find a match or reach the window boundary. '*' stops at the first cohort that matches the set, regardless of whether that cohort satisfies any linked conditions. '**' searches until it finds a cohort that matches both the set and any linked conditions.
116 </para>
117 <screen>
118 # Find an adjective to the left and check whether that adjective has a noun to the immediate right. Stop at the first adjective.
119 (-1* ADJ LINK N)
120
121 # Find an adjective to the left and check whether that adjective has a noun to the immediate right. If it does not have a noun to the immediate right, scan further left and test next adjective position. Repeat.
122 (**-1 ADJ LINK N)
123 </screen>
124 </section>
125
126 <section id="test-barrier">
127 <title>BARRIER</title>
128 <indexterm>
129 <primary>BARRIER</primary>
130 </indexterm>
131 <para>
132 Halts a scan if it sees a cohort matching the set. Especially important to prevent '**' scans from looking too far.
133 </para>
134 <screen>
135 # Find an N to the right, but don't look beyond any V
136 (*1 N BARRIER V)
137 </screen>
138 </section>
139
140 <section id="test-cbarrier">
141 <title>CBARRIER</title>
142 <indexterm>
143 <primary>CBARRIER</primary>
144 </indexterm>
145 <para>
146 Like <link linkend="keyword-barrier">BARRIER</link> but performs the test in Careful mode,
147 meaning it only blocks if all readings in the cohort matches.
148 This makes it less strict than <link linkend="keyword-barrier">BARRIER</link>.
149 </para>
150 <screen>
151 (**1 SetG CBARRIER (Verb))
152 </screen>
153 </section>
154
155 <section id="test-spanning">
156 <title>Spanning Window Boundaries</title>
157 <indexterm>
158 <primary>W</primary>
159 </indexterm>
160 <indexterm>
161 <primary>&lt;</primary>
162 </indexterm>
163 <indexterm>
164 <primary>&gt;</primary>
165 </indexterm>
166 <para>
167 These options allows a test to find matching cohorts in any window currently in the buffer.
168 The buffer size can be adjusted with the --num-windows cmdline flag and defaults to 2.
169 Meaning, 2 windows on either side of the current one is preserved, so a total of 5 would be in
170 the buffer at any time.
171 </para>
172
173 <section id="test-span-both">
174 <title>Span Both</title>
175 <para>
176 Allowing a test to span beyond boundaries in either direction is denoted by 'W'.
177 One could also allow all tests to behave in this manner with the --always-span cmdline flag.
178 </para>
179 <screen>
180 (-1*W (someset))
181 </screen>
182 </section>
183
184 <section id="test-span-left">
185 <title>Span Left</title>
186 <para>
187 '&lt;' allows a test to span beyond boundaries in left direction only.
188 Use 'W' instead, unless it is a complex test or other good reason to require '&lt;'.
189 </para>
190 <screen>
191 (-3**&lt; (someset))
192 </screen>
193 </section>
194
195 <section id="test-span-right">
196 <title>Span Right</title>
197 <para>
198 '&gt;' allows a test to span beyond boundaries in right direction only.
199 Use 'W' instead, unless it is a complex test or other good reason to require '&gt;'.
200 </para>
201 <screen>
202 (2*&gt; (someset))
203 </screen>
204 </section>
205 </section>
206
207 <section id="test-mark">
208 <title>X Marks the Spot</title>
209 <indexterm>
210 <primary>X</primary>
211 </indexterm>
212 <indexterm>
213 <primary>x</primary>
214 </indexterm>
215 <indexterm>
216 <primary>A</primary>
217 </indexterm>
218 <indexterm>
219 <primary>w</primary>
220 </indexterm>
221 <para>
222 By default, linked tests continue from the immediately preceding test.
223 These options affect behavior.
224 </para>
225
226 <screen>
227 # Look right for (third), then from there look right for (seventh),
228 # then jump back to (target) and from there look right for (fifth)
229 SELECT (target) (1* (third) LINK 1* (seventh) LINK 1*x (fifth)) ;
230
231 # Look right for (fourth), then from there look right for (seventh) and set that as the mark,
232 # then from there look left for (fifth), then jump back to (seventh) and from there look left for (sixth)
233 SELECT (target) (1* (fourth) LINK 1*X (seventh) LINK -1* (fifth) LINK -1*x (sixth)) ;
234 </screen>
235
236 <section id="test-mark-set">
237 <title>Set Mark</title>
238 <para>
239 'X' sets the mark to the currently active cohort of the test's target.
240 If no test sets X then the mark defaults to the cohort from the rule's target.
241 See also <link linkend="set-mark">magic set _MARK_</link>.
242 </para>
243 </section>
244
245 <section id="test-mark-jump">
246 <title>Jump to Mark</title>
247 <para>
248 'x' jumps back to the previously set mark (or the rule's target if no mark is set), then proceeds from there.
249 </para>
250 </section>
251
252 <section id="test-mark-attach-to">
253 <title>Attach To / Affect Instead</title>
254 <para>
255 'A' sets the cohort to be attached or related against to the currently active cohort of the test's target.
256 See also <link linkend="set-attachto">magic set _ATTACHTO_</link>.
257 </para>
258 <para>
259 As of version 0.9.9.11032, 'A' can be used for almost all rules to change the cohort to be affected,
260 instead of the target of the rule.
261 </para>
262 </section>
263
264 <section id="test-mark-with">
265 <title>Merge With</title>
266 <para>
267 'w' sets the cohort to be merged with to the currently active cohort of the test's target.
268 Currently only used with <link linkend="mergecohorts">MergeCohorts</link>.
269 It can also be used in contextual tests for <link linkend="with">With</link> to specify which cohort should be accessible in the subrule context.
270 </para>
271 </section>
272
273 <section id="test-mark-jump-other">
274 <title>Jump to Cohort</title>
275 <para>
276 'j' jumps to a particular cohort: 'jM' for _MARK_ (identical to 'x'), 'jA' for _ATTACHTO_, 'jT' for _TARGET_, and 'jC1'-'jC9' for _C1_-_C9_.
277 </para>
278 </section>
279 </section>
280
281 <section id="test-deleted">
282 <title>Test Deleted/Delayed Readings</title>
283 <indexterm>
284 <primary>D</primary>
285 </indexterm>
286 <indexterm>
287 <primary>d</primary>
288 </indexterm>
289 <para>
290 By default, removed reading are not visible to tests.
291 These options allow tests to look at deleted and <link linkend="rule-options-delayed">delayed readings</link>.
292 </para>
293
294 <section id="test-deleted-deleted">
295 <title>Look at Deleted Readings</title>
296 <para>
297 'D' allows the current test (and any barrier) to look at readings that have previously been deleted
298 by SELECT/REMOVE/IFF.
299 Delayed readings are not part of 'D', but can be combined as 'Dd' to look at both.
300 </para>
301 </section>
302
303 <section id="test-deleted-delayed">
304 <title>Look at Delayed Readings</title>
305 <para>
306 'd' allows the current test (and any barrier) to look at readings that have previously been deleted
307 by SELECT/REMOVE/IFF <link linkend="rule-options-delayed">DELAYED</link>.
308 Deleted readings are not part of 'd', but can be combined as 'Dd' to look at both.
309 </para>
310 </section>
311
312 <section id="test-deleted-ignored">
313 <title>Look at Ignored Readings</title>
314 <para>
315 'I' allows the current test (and any barrier) to look at readings that have previously been ignored
316 by REMOVE IGNORED.
317 Can be combined with 'D' and 'd'.
318 </para>
319 </section>
320 </section>
321
322 <section id="test-origin">
323 <title>Scanning Past Point of Origin</title>
324 <indexterm>
325 <primary>--no-pass-origin</primary>
326 <secondary>-o</secondary>
327 </indexterm>
328 <indexterm>
329 <primary>O</primary>
330 </indexterm>
331 <indexterm>
332 <primary>o</primary>
333 </indexterm>
334 <para>
335 By default, linked scanning tests are allowed to scan past the point of origin.
336 These options affect behavior.
337 </para>
338
339 <section id="test-origin-cmdline">
340 <title>--no-pass-origin, -o</title>
341 <para>
342 The --no-pass-origin (or -o in short form) changes the default mode to not allow passing the origin,
343 and defines the origin as the target of the currently active rule.
344 This is equivalent to adding 'O' to the first test of each contextual test of all rules.
345 </para>
346 </section>
347
348 <section id="test-no-pass-origin">
349 <title>No Pass Origin</title>
350 <para>
351 'O' sets the point of origin to the parent of the contextual test, and disallows itself and all linked
352 tests to pass this point of origin. The reason it sets it to the parent is that otherwise there is no
353 way to mark the rule's target as the desired origin.
354 </para>
355 <screen>
356 # Will not pass the (origin) cohort when looking for (right):
357 SELECT (origin) IF (-1*O (left) LINK 1* (right)) ;
358
359 # Will not pass the (origin) cohort when looking for (left):
360 SELECT (something) IF (-1* (origin) LINK 1*O (right) LINK -1* (left)) ;
361 </screen>
362 </section>
363
364 <section id="test-pass-origin">
365 <title>Pass Origin</title>
366 <para>
367 'o' allows the contextual test and all its linked tests to pass the point of origin,
368 even in --no-pass-origin mode. Used to counter 'O'.
369 </para>
370 <screen>
371 # Will pass the (origin) cohort when looking for (right), but not when looking for (middle):
372 SELECT (origin) IF (-1*O (left) LINK 1* (middle) LINK 1*o (right)) ;
373 </screen>
374 </section>
375 </section>
376
377 <section id="test-nearest">
378 <title>Nearest Neighbor</title>
379 <indexterm>
380 <primary>0*</primary>
381 </indexterm>
382 <indexterm>
383 <primary>0**</primary>
384 </indexterm>
385 <para>
386 Usually a '*' or '**' test scans in only one direction, denoted by the value of the offset;
387 if offset is positive it will scan rightwards, and if negative leftwards.
388 In CG-3 the magic offset '0' will scan in both directions;
389 first one to the left, then one to the right, then two to the left, then two to the right, etc.
390 This makes it easy to find the nearest neighbor that matches.
391 <emphasis>
392 In earlier versions of CG this could be approximated with two seperate rules, and you
393 had to scan entirely in one direction, then come back and do the other direction.
394 </emphasis>
395 </para>
396 <para>
397 Caveat: (NOT 0* V) will probably not work as you expect; it will be true if either direction doesn't find set V.
398 What you want instead is (NEGATE 0* V) or split into (NOT -1* V) (NOT 1* V).
399 </para>
400 <screen>
401 (0* (someset))
402 (0**W (otherset))
403 </screen>
404 </section>
405
406 <section id="test-active">
407 <title>Active/Inactive Readings</title>
408 <indexterm>
409 <primary>T</primary>
410 </indexterm>
411 <indexterm>
412 <primary>t</primary>
413 </indexterm>
414 <para>
415 Position modifier 'T' makes the test only consider the currently active reading.
416 </para>
417 <para>
418 Position modifier 't' makes the test only consider readings other than the currently active one.
419 This can be combined with 'C' to mean all other readings.
420 </para>
421 <para>
422 These currently only make sense for contexts that look at the target cohort, such as position 0.
423 </para>
424 </section>
425
426 <section id="test-bag-of-tags">
427 <title>Bag of Tags</title>
428 <indexterm>
429 <primary>B</primary>
430 </indexterm>
431 <para>
432 Position modifier 'B' causes the test to look in a bag of tags, which is like a bag of words but with all
433 tags. 'B' alone looks for tags in the current window, but can be combined with the
434 <link linkend="test-spanning">window spanning modifiers</link> to also test the windows before and/or after.
435 Linking from a 'B' test behaves as if you linked from offset 0.
436 </para>
437 <para>
438 The bag is greedy and lazy. It will hold all tags added to the window at any time, but will not forget
439 tags as they are removed from the window through various means.
440 </para>
441 </section>
442
443 <section id="test-branch">
444 <title>Optional Frequencies</title>
445 <indexterm>
446 <primary>f</primary>
447 </indexterm>
448 <para>
449 Position modifer 'f' creates two branches based on the current test. In the first, the test remains exactly as
450 is written. In the second, all <link linkend="numerical-matches">numeric tags</link> are removed and
451 modifier 'C' is added. This is equivalent to making an inline template with OR'ed tests.
452 </para>
453 <para>
454 E.g., test <code>(-1*f (N &lt;W>50&gt;))</code> is equivalent to <code>(-1* (N &lt;W>50&gt;)) OR (-1*C (N))</code>.
455 This is all done at compile time.
456 The numeric tag removal will dig down through the whole target set and create new sets along the way as needed.
457 </para>
458 </section>
459
460 <section id="test-dependency">
461 <title>Dependencies</title>
462 <para>
463 CG-3 also introduces the p, c, cc, and s positions.
464 See the section about those in the <link linkend="dep-contextual-tests">Dependencies</link> chapter.
465 </para>
466 </section>
467
468 <section id="test-relations">
469 <title>Relations</title>
470 <para>
471 CG-3 also introduces the r:rel and r:* positions.
472 See the section about those in the <link linkend="rel-contextual-tests">Relations</link> chapter.
473 </para>
474 </section>
475
476 </chapter>