Debian Codegraph @

manual/sets.xml

raw
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter SYSTEM "docbook-dtd-45/docbookx.dtd">
3
4 <chapter id="sets">
5 <title>Sets</title>
6
7 <section id="set-definition">
8 <title>Defining Sets</title>
9
10 <section id="set-list">
11 <title>LIST</title>
12 <indexterm>
13 <primary>LIST</primary>
14 </indexterm>
15 <para>
16 Defines a new set based on a list of tags, or appends to an existing set.
17 Composite tags in <code>()</code> require that all tags match.
18 <code>LIST</code> cannot perform set operations - all elements of a <code>LIST</code> definition is parsed as literal tags, not other sets.
19 </para>
20 <screen>
21 LIST setname = tag othertag (mtag htag) ltag ;
22
23 LIST setname += even more tags ;
24 </screen>
25 <para>
26 If the named set for <code>+=</code> is of <link linkend="keyword-set">SET-type</link>, then the new tags will be in a set OR'ed onto the existing one.
27 See <link linkend="set-manipulation">set manipulation</link>.
28 </para>
29 <para>
30 Avoid cluttering your grammar with <code>LIST N = N;</code> definitions by using <link linkend="list-tags">LIST-TAGS</link> or <link linkend="strict-tags">STRICT-TAGS</link> instead.
31 </para>
32 </section>
33
34 <section id="set-set">
35 <title>SET</title>
36 <indexterm>
37 <primary>SET</primary>
38 </indexterm>
39 <para>
40 Defines a new set based on <link linkend="set-operators">operations</link> between existing sets.
41 To include literal tags or composite tags in operations, define an inline set with <code>()</code>.
42 </para>
43 <screen>
44 SET setname = someset + someotherset - (tag) ;
45 </screen>
46 </section>
47 </section>
48
49 <section id="set-operators">
50 <title>Set Operators</title>
51
52 <section id="set-operator-union">
53 <title>Union: OR and |</title>
54 <para>
55 Equivalent to the mathematical set union &#x222a; operator.
56 </para>
57 <screen>
58 LIST a = a b c d ;
59 LIST b = c d e f ;
60
61 # Logically yields a set containing tags: a b c d e f
62 # Practically a reading must match either set
63 SET r = a OR b ;
64 SET r = a | b ;
65 </screen>
66 </section>
67
68 <section id="set-operator-except">
69 <title>Except: -</title>
70 <para>
71 Equivalent to the SQL Except operator.
72 </para>
73 <screen>
74 LIST a = a b c d ;
75 LIST b = c d e f ;
76
77 # Logically yields a set containing tags: a b !c !d !e !f
78 # Practically a reading must match the first set and must not match the second set
79 SET r = a - b ;
80 </screen>
81 </section>
82
83 <section id="set-operator-difference">
84 <title>Difference: \</title>
85 <para>
86 Equivalent to the mathematical set complement &#x2216; operator.
87 The symbol is a normal backslash.
88 </para>
89 <screen>
90 LIST a = a b c d ;
91 LIST b = c d e f ;
92
93 # Logically yields a set containing tags: a b
94 SET r = a \ b ;
95 </screen>
96 </section>
97
98 <section id="set-operator-symdiff">
99 <title>Symmetric Difference: &#x2206;</title>
100 <para>
101 Equivalent to the mathematical set symmetric difference &#x2206; operator.
102 The symbol is the Unicode code point U+2206.
103 </para>
104 <screen>
105 LIST a = a b c d ;
106 LIST b = c d e f ;
107
108 # Logically yields a set containing tags: a b e f
109 SET r = a &#x2206; b ;
110 </screen>
111 </section>
112
113 <section id="set-operator-intersection">
114 <title>Intersection: &#x2229;</title>
115 <para>
116 Equivalent to the mathematical set intersection &#x2229; operator.
117 The symbol is the Unicode code point U+2229.
118 </para>
119 <screen>
120 LIST a = a b c d ;
121 LIST b = c d e f ;
122
123 # Logically yields a set containing tags: c d
124 SET r = a &#x2229; b ;
125 </screen>
126 </section>
127
128 <section id="set-operator-product">
129 <title>Cartesian Product: +</title>
130 <para>
131 Equivalent to the mathematical set cartesian product &#x00d7; operator.
132 </para>
133 <screen>
134 LIST a = a b c d ;
135 LIST b = c d e f ;
136
137 # Logically yields a set containing tags: (a c) (b c) c (d c) (a d) (b d) d (a e)
138 # (b e) (c e) (d e) (a f) (b f) (c f) (d f)
139 # Practically a reading must match both sets
140 SET r = a + b ;
141 </screen>
142 </section>
143
144 <section id="set-operator-failfast">
145 <title>Fail-Fast: ^</title>
146 <para>
147 On its own, this is equivalent to set difference -. But, when followed by other sets it becomes a blocker.
148 In <code>A - B OR C + D</code> either <code>A - B</code> or <code>C + D</code> may suffice for a match.
149 However, in <code>A ^ B OR C + D</code>, if B matches then it blocks the rest and fails the entire set match
150 without considering C or D.
151 </para>
152 </section>
153 </section>
154
155 <section id="set-magic">
156 <title>Magic Sets</title>
157
158 <section id="set-any">
159 <title>(*)</title>
160 <para>
161 A set containing the (*) tag becomes a magic "any" set and will always match.
162 This saves having to declare a dummy set containing all imaginable tags.
163 Useful for testing whether a cohort exists at a position, without needing details about it.
164 Can also be used to match everything except a few tags with the set operator -.
165 </para>
166 <screen>
167 (*-1 (*) LINK 1* SomeSet)
168 SELECT (*) - NotTheseTags ;
169 </screen>
170 </section>
171
172 <section id="set-delimiters">
173 <title>_S_DELIMITERS_</title>
174 <para>
175 The magic set _S_DELIMITERS_ is created from the
176 <link linkend="keyword-delimiters">DELIMITERS</link> definition.
177 This saves having to declare and maintain a seperate set for matching delimiters in tests.
178 </para>
179 <screen>
180 SET SomeSet = OtherSet OR _S_DELIMITERS_ ;
181 </screen>
182 </section>
183
184 <section id="set-soft-delimiters">
185 <title>_S_SOFT_DELIMITERS_</title>
186 <para>
187 The magic set _S_SOFT_DELIMITERS_ is created from the
188 <link linkend="keyword-soft-delimiters">SOFT-DELIMITERS</link> definition.
189 </para>
190 <screen>
191 (**1 _S_SOFT_DELIMITERS_ BARRIER BoogieSet)
192 </screen>
193 </section>
194
195 <section id="set-target">
196 <title>Magic Set _TARGET_</title>
197 <para>
198 A magic set containing the single tag (_TARGET_).
199 This set and tag will only match when the currently active cohort is the target of the rule.
200 </para>
201 </section>
202
203 <section id="set-mark">
204 <title>Magic Set _MARK_</title>
205 <para>
206 A magic set containing the single tag (_MARK_).
207 This set and tag will only match when the currently active cohort is the mark set with X,
208 or if no such mark is set it will only match the target of the rule.
209 </para>
210 </section>
211
212 <section id="set-attachto">
213 <title>Magic Set _ATTACHTO_</title>
214 <para>
215 A magic set containing the single tag (_ATTACHTO_).
216 This set and tag will only match when the currently active cohort is the mark set with A.
217 </para>
218 </section>
219
220 <section id="set-same-basic">
221 <title>Magic Set _SAME_BASIC_</title>
222 <para>
223 A magic set containing the single tag (_SAME_BASIC_).
224 This set and tag will only match when the currently active reading has the same basic tags (non-mapping tags)
225 as the target reading.
226 </para>
227 </section>
228 </section>
229
230 <section id="set-manipulation">
231 <title>Set Manipulation</title>
232
233 <section id="set-manipulation-undef">
234 <title>Undefining Sets</title>
235 <para>
236 <link linkend="keyword-undef-sets"><code>UNDEF-SETS</code></link> lets you undefine/unlink sets so later definitions can reuse the name.
237 This does not delete a set, nor can it alter past uses of a set. Prior uses of a set remain linked to the old set.
238 </para>
239 <screen>
240 LIST ADV = ADV ;
241 LIST VFIN = (V FIN) ;
242
243 UNDEF-SETS = VINF ADV ;
244 SET ADV = A OR D OR V ;
245 LIST VFIN = VFIN ;
246 </screen>
247 </section>
248
249 <section id="set-manipulation-append">
250 <title>Appending to Sets</title>
251 <para>
252 <link linkend="keyword-list"><code>LIST</code> with <code>+=</code></link> lets you append tags to an existing LIST or SET.
253 This does not alter past uses of a set. Prior uses of a set remain linked to the old definition.
254 </para>
255 <para>
256 For <link linkend="keyword-list"><code>LIST</code></link>-type sets, this creates a new set that is a combination of all tags from the existing set plus all the new tags.
257 </para>
258 <para>
259 For <link linkend="keyword-set"><code>SET</code></link>-type sets, the new tags are OR'ed onto the existing set. This can lead to surprising behavior if the existing set is complex.
260 </para>
261 <screen>
262 LIST VFIN = (V FIN) ;
263
264 LIST VFIN += VFIN ;
265 </screen>
266 </section>
267 </section>
268
269 <section id="set-unification">
270 <title>Unification</title>
271
272 <section id="set-unification-tag">
273 <title>Tag Unification</title>
274 <para>
275 Each time a rule is run on a reading, the tag that first satisfied the set must be the same
276 as all subsequent matches of the same set in tests.
277 </para>
278 <para>
279 A set is marked as a tag unification set by prefixing $$ to the name when used in a rule.
280 You can only prefix existing sets; inline sets in the form of $$(tag tags) will not work,
281 but $$Set + $$OtherSet will; that method will make 2 unification sets, though.
282 </para>
283 <para>
284 The regex tags &lt;.*&gt;r ".*"r "&lt;.*&gt;"r are special and will unify to the same exact tag of that type.
285 This is useful for e.g. mandating that the baseform must be exactly the same in all places.
286 </para>
287 <para>
288 For example
289 <screen>
290 LIST ROLE = &lt;human&gt; &lt;anim&gt; &lt;inanim&gt; (&lt;bench&gt; &lt;table&gt;) ;
291 SELECT $$ROLE (-1 KC) (-2C $$ROLE) ;
292 </screen>
293 which would logically be the same as
294 <screen>
295 SELECT (&lt;human&gt;) (-1 KC) (-2C (&lt;human&gt;)) ;
296 SELECT (&lt;anim&gt;) (-1 KC) (-2C (&lt;anim&gt;)) ;
297 SELECT (&lt;inanim&gt;) (-1 KC) (-2C (&lt;inanim&gt;)) ;
298 SELECT (&lt;bench&gt; &lt;table&gt;) (-1 KC) (-2C (&lt;bench&gt; &lt;table&gt;)) ;
299 </screen>
300 </para>
301 <para>
302 Caveat: The exploded form is not identical to the unified form. Unification rules are run as normal
303 rules, meaning once per reading. The exploded form would be run in-order as seperate rules per reading.
304 There may be side effects due to that.
305 </para>
306 <para>
307 Caveat 2: The behavior of this next rule is undefined:
308 <screen>
309 SELECT (tag) IF (0 $$UNISET) (-2* $$UNISET) (1** $$UNISET) ;
310 </screen>
311 Since the order of tests is dynamic, the unification of $$UNISET will be initialized with essentially random
312 data, and as such cannot be guaranteed to unify properly. Well defined behavior can be enforced in various ways:
313 <screen>
314 # Put $$UNISET in the target
315 SELECT (tag) + $$UNISET IF (-2* $$UNISET) (1** $$UNISET) ;
316
317 # Only refer to $$UNISET in a single linked chain of tests
318 SELECT (tag) IF (0 $$UNISET LINK -2* $$UNISET LINK 1** $$UNISET) ;
319
320 # Use rule option KEEPORDER
321 SELECT KEEPORDER (tag) IF (0 $$UNISET) (-2* $$UNISET) (1** $$UNISET) ;
322 </screen>
323 Having the unifier in the target is usually the best way to enforce behavior.
324 </para>
325 </section>
326
327 <section id="set-unification-set">
328 <title>Top-Level Set Unification</title>
329 <para>
330 Each time a rule is run on a reading, the top-level set that first satisfied the match must be the same
331 as all subsequent matches of the same set in tests.
332 </para>
333 <para>
334 A set is marked as a top-level set unification set by prefixing &amp;&amp; to the name when used in a rule.
335 You can only prefix existing sets; inline sets in the form of &amp;&amp;(tag tags) will not work,
336 but &amp;&amp;Set + &amp;&amp;OtherSet will; that method will make 2 unification sets, though.
337 </para>
338 <para>
339 For example
340 <screen>
341 LIST SEM-HUM = &lt;human&gt; &lt;person&gt; &lt;sapien&gt; ;
342 LIST SEM-ANIM = &lt;animal&gt; &lt;beast&gt; &lt;draconic&gt; ;
343 LIST SEM-INSECT = &lt;insect&gt; &lt;buzzers&gt; ;
344 SET SEM-SMARTBUG = SEM-INSECT + (&lt;sapien&gt;) ;
345 SET SAME-SEM = SEM-HUM OR SEM-ANIM + SEM-SMARTBUG ; # During unification, OR and + are ignored
346 SELECT &amp;&amp;SAME-SEM (-1 KC) (-2C &amp;&amp;SAME-SEM) ;
347 </screen>
348 which would logically be the same as
349 <screen>
350 SELECT SEM-HUM (-1 KC) (-2C SEM-HUM) ;
351 SELECT SEM-ANIM (-1 KC) (-2C SEM-ANIM) ;
352 SELECT SEM-SMARTBUG (-1 KC) (-2C SEM-SMARTBUG) ;
353 </screen>
354 </para>
355 <para>
356 Note that the unification only happens on the first level of sets, hence named top-level unification.
357 Note also that the set operators in the prefixed set are ignored during unification.
358 </para>
359 <para>
360 You can use the same set for different unified matches by prefixing the set name with a number and colon.
361 E.g., <code>&amp;&amp;SAME-SEM</code> is a different match than <code>&amp;&amp;1:SAME-SEM</code>.
362 </para>
363 <para>
364 The same caveats as for <link linkend="set-unification-tag">Tag Unification</link> apply.
365 </para>
366 </section>
367 </section>
368
369 </chapter>