blob: e26f707adbec23b20e390955c0996e8d79090dd7 [file] [log] [blame]
Nils Diewald7cad8402014-07-08 17:06:56 +00001% content main => begin
2
3<h2>KorAP-Tutorial: Poliqarp+</h2>
4
Nils Diewald2fe12e12015-03-06 16:47:06 +00005<p><%= kalamar_tut_link_to 'Back to Index', '/tutorial' %></p>
Nils Diewald4e9fbcb2014-07-15 11:45:09 +00006
7<p>The following tutorial introduces all features provided by our version of the Poliqarp Query Language and some KorAP specific extensions.</p>
8
9<section id="tut-segments">
Nils Diewald7cad8402014-07-08 17:06:56 +000010<h3>Simple Segments</h3>
11
12<p>The atomic elements of Poliqarp queries are segments. Most of the time segments represent words and can be simply queried:</p>
13%# footnote: In the polish national corpus, Poliqarp can join multiple segments when identifying a single word.
14
Nils Diewald2fe12e12015-03-06 16:47:06 +000015%= kalamar_tut_query poliqarp => 'Baum'
Nils Diewald7cad8402014-07-08 17:06:56 +000016
17<p>Sequences of simple segments are expressed using a space delimiter:</p>
18
Nils Diewald2fe12e12015-03-06 16:47:06 +000019%= kalamar_tut_query poliqarp => 'der Baum'
Nils Diewald7cad8402014-07-08 17:06:56 +000020
21<p>Simple segments always refer to the surface form of a word. To search for surface forms without case sensitivity, you can use the <code>/i</code> flag.</p>
22
Nils Diewald2fe12e12015-03-06 16:47:06 +000023%= kalamar_tut_query poliqarp => 'laufen/i'
Nils Diewald7cad8402014-07-08 17:06:56 +000024
25<p>The query above will find all occurrences of <code>laufen</code> irrespective of the capitalization of letters, so <code>wir laufen</code> will be find as well as <code>das Laufen</code> and even <code>&quot;GEH LAUFEN!&quot;</code>.
26</section>
27
Nils Diewald4e9fbcb2014-07-15 11:45:09 +000028<section id="tut-regexp">
Nils Diewald7cad8402014-07-08 17:06:56 +000029 <h3>Regular Expressions</h3>
30
Nils Diewald2fe12e12015-03-06 16:47:06 +000031<p>Segments can also be queried using <%= kalamar_tut_link_to 'regular expressions', '/tutorial/regular-expressions' %> - by surrounding the segment with double quotes.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000032
Nils Diewald2fe12e12015-03-06 16:47:06 +000033%= kalamar_tut_query poliqarp => '"l(au|ie)fen"'
Nils Diewald7cad8402014-07-08 17:06:56 +000034
35<p>Regular expression segments will always match the whole segment, meaning the above query will find words starting with <code>l</code> and ending with <code>n</code>. To support subqueries, you can use the <code>/x</code> flag.
36
Nils Diewald2fe12e12015-03-06 16:47:06 +000037%= kalamar_tut_query poliqarp => '"l(au|ie)fen"/x', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +000038
39<p>The <code>/x</code> will search for all segments that contain a sequence of characters the regular expression matches. That means the above query is equivalent to:</p>
40
Nils Diewald2fe12e12015-03-06 16:47:06 +000041%= kalamar_tut_query poliqarp => '".*?l(au|ie)fen.*?"', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +000042
43<p>The <code>/x</code> flag can also be used in conjuntion with strict expressions to search for substrings:</p>
44
Nils Diewald2fe12e12015-03-06 16:47:06 +000045%= kalamar_tut_query poliqarp => 'trenn/xi', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +000046
47<p>The above query will find all occurrences of segments including the string <code>trenn</code> case insensitive, like &quot;Trennung&quot;, &quot;unzertrennlich&quot;, or &quot;Wettrennen&quot;.</p>
48
Nils Diewald4e9fbcb2014-07-15 11:45:09 +000049<blockquote class="warning">
50 <p>Beware: These kinds of queries (with prepended <code>.*</code> expressions) are extremely slow!</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000051</blockquote>
52
53<p>You can again apply the <code>/i</code> flag to search case insensitive.</p>
54
Nils Diewald2fe12e12015-03-06 16:47:06 +000055%= kalamar_tut_query poliqarp => '"l(au|ie)fen"/xi', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +000056
57</section>
58
Nils Diewald4e9fbcb2014-07-15 11:45:09 +000059<section id="tut-complex">
Nils Diewald7cad8402014-07-08 17:06:56 +000060 <h3>Complex Segments</h3>
61
Nils Diewald955ca872014-11-07 03:38:31 +000062<p>Complex segments are expressed in square brackets and contain additional information on the resource of the term under scrutiny by providing key/value pairs, separated by an equal-sign.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000063
64<p>The KorAP implementation of Poliqarp provides three special segment keys: <code>orth</code> for surface forms, <code>base</code> for lemmata, and <code>pos</code> for Part-of-Speech. The following complex query finds all surface forms of <code>Baum</code>.</p>
65
66%# There are more special keys in Poliqarp, but KorAP doesn't provide them.
67
Nils Diewald2fe12e12015-03-06 16:47:06 +000068%= kalamar_tut_query poliqarp => '[orth=Baum]'
Nils Diewald7cad8402014-07-08 17:06:56 +000069
70<p>The query is thus equivalent to:</p>
71
Nils Diewald2fe12e12015-03-06 16:47:06 +000072%= kalamar_tut_query poliqarp => 'Baum'
Nils Diewald7cad8402014-07-08 17:06:56 +000073
Nils Diewald955ca872014-11-07 03:38:31 +000074<p>Complex segments expect simple expressions as values, meaning that the following expression is valid as well:</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000075
Nils Diewald2fe12e12015-03-06 16:47:06 +000076%= kalamar_tut_query poliqarp => '[orth="l(au|ie)fen"/xi]', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +000077
Nils Diewald2fe12e12015-03-06 16:47:06 +000078<p>Another special key is <code>base</code>, refering to the lemma annotation of the <%= kalamar_tut_link_to 'default foundry', '/tutorial/foundries' %>.
Nils Diewald955ca872014-11-07 03:38:31 +000079The following query finds all occurrences of segments annotated as the lemma <code>Baum</code> by the default foundry.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000080
Nils Diewald2fe12e12015-03-06 16:47:06 +000081%= kalamar_tut_query poliqarp => '[base=Baum]'
Nils Diewald7cad8402014-07-08 17:06:56 +000082
Nils Diewald2fe12e12015-03-06 16:47:06 +000083<p>The third special key is <code>pos</code>, refering to the part-of-speech annotation of the <%= kalamar_tut_link_to 'default foundry', '/tutorial/foundries' %>.
Nils Diewald955ca872014-11-07 03:38:31 +000084The following query finds all attributive adjectives:</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000085
Nils Diewald2fe12e12015-03-06 16:47:06 +000086%= kalamar_tut_query poliqarp => '[pos=ADJA]'
Nils Diewald7cad8402014-07-08 17:06:56 +000087
Nils Diewald955ca872014-11-07 03:38:31 +000088<p>Complex segments requesting further token annotations can have keys following the <code>foundry/layer</code> notation.
89For example to find all occurrences of plural words in the mate foundry, you can search using the following query:</p>
Nils Diewald7cad8402014-07-08 17:06:56 +000090
Nils Diewald2fe12e12015-03-06 16:47:06 +000091%= kalamar_tut_query poliqarp => '[mate/m=number:pl]'
Nils Diewald7cad8402014-07-08 17:06:56 +000092
Nils Diewald955ca872014-11-07 03:38:31 +000093<h4>Negation</h4>
94<p>Negation of terms in complex expressions can be expressed by prepending the equal sign with an exclamation mark or by prepending the expression with one.</p>
95
Nils Diewald2fe12e12015-03-06 16:47:06 +000096%= kalamar_tut_query poliqarp => '[pos!=ADJA]'
97%= kalamar_tut_query poliqarp => '[!pos=ADJA]'
Nils Diewald955ca872014-11-07 03:38:31 +000098
Nils Diewald4e9fbcb2014-07-15 11:45:09 +000099<blockquote class="warning">
Nils Diewald955ca872014-11-07 03:38:31 +0000100 <p>Beware: Negated complex segments can't be searched solely in the Lucene index.
101 However, they work in case they are part of a <a href="#tut-syntagmatic-operators-sequence">sequence</a>.</p>
102</blockquote>
103
Nils Diewalde2c83812014-11-11 21:13:18 +0000104<h4 id="empty-segments">Empty Segments</h4>
Nils Diewald955ca872014-11-07 03:38:31 +0000105
106<p>A special segment is the empty segment, that matches every word in the index.</p>
107
Nils Diewald2fe12e12015-03-06 16:47:06 +0000108%= kalamar_tut_query poliqarp => '[]'
Nils Diewald955ca872014-11-07 03:38:31 +0000109
110<p>Empty segments are useful to express distances of words by using <a href="tut-syntagmatic-operators-repetitions">repetitions</a>.</p>
111
112<blockquote class="warning">
113 <p>Beware: Empty segments can't be searched solely in the Lucene index.
114 However, they work in case they are part of a <a href="#tut-syntagmatic-operators-sequence">sequence</a>.</p>
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000115</blockquote>
116
Nils Diewald7cad8402014-07-08 17:06:56 +0000117</section>
118
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000119<section id="tut-spans">
Nils Diewald7cad8402014-07-08 17:06:56 +0000120<h3>Span Segments</h3>
121
Nils Diewald955ca872014-11-07 03:38:31 +0000122<p>Not all segments are bound to words - some are bound to concepts spanning multiple words, for example noun phrases, sentences, or paragraphs.
123Span segments can be searched for using angular brackets instead of square brackets.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +0000124
Nils Diewald2fe12e12015-03-06 16:47:06 +0000125%= kalamar_tut_query poliqarp => '<xip/c=INFC>'
Nils Diewald955ca872014-11-07 03:38:31 +0000126
127<p>Otherwise they can be treated in exactly the same way as simple or complex segments.</p>
Nils Diewalde2c83812014-11-11 21:13:18 +0000128
Nils Diewald7cad8402014-07-08 17:06:56 +0000129</section>
130
Nils Diewald955ca872014-11-07 03:38:31 +0000131
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000132<section id="tut-paradigmatic-operators">
Nils Diewald7cad8402014-07-08 17:06:56 +0000133<h3>Paradigmatic Operators</h3>
Nils Diewaldf7366232014-07-25 15:57:08 +0000134
Nils Diewald955ca872014-11-07 03:38:31 +0000135<p>A complex segment can have multiple properties a token has to fulfill.
136For example to search for all words with the surface form <code>laufe</code> (no matter if capitalized or not) that have the lemma <code>lauf</code> (and not, for example, <code>laufen</code>, which would indicate a verb or a gerund), you can search for:</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000137
Nils Diewald2fe12e12015-03-06 16:47:06 +0000138%= kalamar_tut_query poliqarp => '[orth=laufe/i & base=Lauf]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000139
Nils Diewald955ca872014-11-07 03:38:31 +0000140<p>The ampersand combines multiple properties with a logical AND.
141Terms of the complex segment can be negated as introduced before.</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000142
Nils Diewald2fe12e12015-03-06 16:47:06 +0000143%= kalamar_tut_query poliqarp => '[orth=laufe/i & base!=Lauf]'
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000144
Nils Diewald955ca872014-11-07 03:38:31 +0000145<p>The following query is therefore equivalent:</p>
Nils Diewald7cad8402014-07-08 17:06:56 +0000146
Nils Diewald2fe12e12015-03-06 16:47:06 +0000147%= kalamar_tut_query poliqarp => '[orth=laufe & !base=Lauf]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000148
Nils Diewald955ca872014-11-07 03:38:31 +0000149<p>Alternatives can be expressed by using the pipe symbol:</p>
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000150
Nils Diewald2fe12e12015-03-06 16:47:06 +0000151%= kalamar_tut_query poliqarp => '[base=laufen | base=gehen]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000152
Nils Diewald955ca872014-11-07 03:38:31 +0000153<p>All these sub expressions can be grouped using round brackets to form
154complex boolean expressions:</p>
155
Nils Diewald2fe12e12015-03-06 16:47:06 +0000156%= kalamar_tut_query poliqarp => '[(base=laufen | base=gehen) & tt/pos=VVFIN]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000157</section>
158
Nils Diewald955ca872014-11-07 03:38:31 +0000159
Nils Diewald4e9fbcb2014-07-15 11:45:09 +0000160<section id="tut-syntagmatic-operators">
Nils Diewald7cad8402014-07-08 17:06:56 +0000161<h3>Syntagmatic Operators</h3>
162
Nils Diewald955ca872014-11-07 03:38:31 +0000163<h4 id="tut-syntagmatic-operators-sequence">Sequences</h4>
164
165<p>Sequences can be used to search for segments in order.
166For example to search for the word &quot;alte&quot; preceded by &quot;der&quot; and followed by &quot;Mann&quot;, you can simple search for the sequence of simple expressions separated by whitespaces.</p>
167
Nils Diewald2fe12e12015-03-06 16:47:06 +0000168%= kalamar_tut_query poliqarp => 'der alte Mann'
Nils Diewald955ca872014-11-07 03:38:31 +0000169
170<p>However, you can obviously search using complex segments as well:</p>
171
Nils Diewald2fe12e12015-03-06 16:47:06 +0000172%= kalamar_tut_query poliqarp => '[orth=der][orth=alte][orth=Mann]'
Nils Diewald955ca872014-11-07 03:38:31 +0000173
174<p>Now you may see the benefit of the empty segment to search for words you don't know:</p>
175
Nils Diewald2fe12e12015-03-06 16:47:06 +0000176%= kalamar_tut_query poliqarp => '[orth=der][][orth=Mann]'
Nils Diewald955ca872014-11-07 03:38:31 +0000177
Nils Diewalde2c83812014-11-11 21:13:18 +0000178<p>You are also able to mix segments and spans in sequences, for example to search for the word &quot;Der&quot; at the beginning of a sentence (which can be interpreted as the first word after the end of a sentence).</p>
179
Nils Diewald2fe12e12015-03-06 16:47:06 +0000180%= kalamar_tut_query poliqarp => '<s>[orth=Der]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000181
Nils Diewaldf7366232014-07-25 15:57:08 +0000182<h4>Groups</h4>
183
184<h4>Alternation</h4>
185
Nils Diewald955ca872014-11-07 03:38:31 +0000186<p>Alternations allow for searching alternative segments or sequences of segments,
187similar to the paradigmatic operator.
188You already have seen that you can search for both sequences of
189<code>der alte Mann</code> and <code>der junge Mann</code> by typing in:</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000190
Nils Diewald2fe12e12015-03-06 16:47:06 +0000191%= kalamar_tut_query poliqarp => 'der [orth=alte | orth=junge] Mann'
Nils Diewaldf7366232014-07-25 15:57:08 +0000192
193<p>However, this formulation has problems in case you want to search for alternations of sequences rather than terms. If you want to search for both sequences of <code>dem jungen Mann</code> and <code>der alte Mann</code> you can use syntagmatic alternations and groups:</p>
194
Nils Diewald2fe12e12015-03-06 16:47:06 +0000195%= kalamar_tut_query poliqarp => '(dem jungen | der alte) Mann'
Nils Diewaldf7366232014-07-25 15:57:08 +0000196
197<p>The pipe symbol works the same way as with the paradigmatic alternation, but supports sequences of different length as operands. The above query for <code>der alte Mann</code> and <code>der junge Mann</code> can therefor be reformulated as:</p>
198
Nils Diewald2fe12e12015-03-06 16:47:06 +0000199%= kalamar_tut_query poliqarp => 'der (junge | alte) Mann'
Nils Diewaldf7366232014-07-25 15:57:08 +0000200
Nils Diewald955ca872014-11-07 03:38:31 +0000201<h4 id="tut-syntagmatic-operators-repetitions">Repetition</h4>
Nils Diewald7cad8402014-07-08 17:06:56 +0000202
Nils Diewald2fe12e12015-03-06 16:47:06 +0000203<p>Repetitions in Poliqarp are realized as in <%= kalamar_tut_link_to 'regular expressions', '/tutorial/regular-expressions' %>, by giving quantifieres in curly brackets.</p>
Nils Diewald57a262e2014-07-22 15:18:38 +0000204<p>To search for a sequence of three occurrences of <code>der</code>, you can formulate your query in any of the following ways - they will have the same results:</p>
205
Nils Diewald2fe12e12015-03-06 16:47:06 +0000206%= kalamar_tut_query poliqarp => 'der der der'
207%= kalamar_tut_query poliqarp => 'der{3}'
208%= kalamar_tut_query poliqarp => '[orth=der]{3}'
Nils Diewald57a262e2014-07-22 15:18:38 +0000209
Nils Diewaldf7366232014-07-25 15:57:08 +0000210<p>In difference to regular expressions, the repetition operation won't refer to the match but to the pattern given. So the following query will give you a sequence of three words having the term <code>der</code> as a substring - but the words don't have to be identical. The following query for example will match a sequence of three words all starting with <code>la</code>.</p>
Nils Diewald57a262e2014-07-22 15:18:38 +0000211
Nils Diewald2fe12e12015-03-06 16:47:06 +0000212%= kalamar_tut_query poliqarp => '"la.*?"/i{3}'
Nils Diewald57a262e2014-07-22 15:18:38 +0000213
Nils Diewaldf7366232014-07-25 15:57:08 +0000214<p>The same is true for annotations. The following query will find a sequence of 3 to 4 adjectives as annotated by the TreeTagger foundry, that is preceded by the lemma <code>ein</code> as annotated by the default foundry and followed by a noun as annotated by the XIP foundry. The adjectives do not have to be identical though.</p>
Nils Diewald57a262e2014-07-22 15:18:38 +0000215
Nils Diewald2fe12e12015-03-06 16:47:06 +0000216%= kalamar_tut_query poliqarp => '[base=ein][tt/p=ADJA]{3,4}[xip/p=NOUN]'
Nils Diewald7cad8402014-07-08 17:06:56 +0000217
Nils Diewaldf7366232014-07-25 15:57:08 +0000218<p>In addition to numbered quantities, it is also possible to pass repetition information as Kleene operators <code>?</code>, <code>+</code>, and <code>+</code>.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +0000219
Nils Diewaldf7366232014-07-25 15:57:08 +0000220<p>To search for a sequence of the lemma <code>der</code> followed by the lemma <code>baum</code> as annotated by the base foundry, but allowing an optional adjective as annotated by the TreeTagger foundry in between, you can search for:</p>
Nils Diewald7cad8402014-07-08 17:06:56 +0000221
Nils Diewald2fe12e12015-03-06 16:47:06 +0000222%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA]?[base=Baum]'
Nils Diewaldf7366232014-07-25 15:57:08 +0000223
224<p>This query is identical to the numbered quantification of:</p>
225
Nils Diewald2fe12e12015-03-06 16:47:06 +0000226%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA]{,1}[base=Baum]'
Nils Diewaldf7366232014-07-25 15:57:08 +0000227
228<p>To search for the same sequences but with unlimited adjectives as annotated by the TreeTagger foundry in between, you can use the Kleene Star:</p>
229
Nils Diewald2fe12e12015-03-06 16:47:06 +0000230%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA]*[base=Baum]'
Nils Diewaldf7366232014-07-25 15:57:08 +0000231
232<p>And to search for this sequence but with at least one adjective in between, you can use the Kleene Plus (all queries are identical):</p>
233
Nils Diewald2fe12e12015-03-06 16:47:06 +0000234%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA]+[base=Baum]', cutoff => 1
235%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA]{1,}[base=Baum]', cutoff => 1
236%= kalamar_tut_query poliqarp => '[base=die][tt/pos=ADJA][tt/pos=ADJA]*[base=Baum]', cutoff => 1
Nils Diewaldf7366232014-07-25 15:57:08 +0000237
238<blockquote class="warning">
Nils Diewalde2c83812014-11-11 21:13:18 +0000239 <p>Repetition operators like <code>{,4}</code>, <code>?</code>, and <code>*</code> make segments or groups of segments optional. In case these queries are used separated and not in a sequence (and there are no mandatory segments in the query), you will be warned by the system that your query won't be treated as optional.</p>
240 <p>Keep in mind that optionality may be somehow <i>inherited</i>, for example when you search for <code>(junge|alte)?|tote</code>, one segment of the alternation is optional, which makes the whole query optional as well.</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000241</blockquote>
242
Nils Diewalde2c83812014-11-11 21:13:18 +0000243<p>Repetition can also be used to express distances between segments by using <a href="#empty-segments">empty segments</a>.</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000244
Nils Diewald2fe12e12015-03-06 16:47:06 +0000245%= kalamar_tut_query poliqarp => '[base=die][][base=Baum]'
246%= kalamar_tut_query poliqarp => '[base=die][]{2}[base=Baum]', cutoff => 1
247%= kalamar_tut_query poliqarp => '[base=die][]{2,}[base=Baum]', cutoff => 1
248%= kalamar_tut_query poliqarp => '[base=die][]{,3}[base=Baum]', cutoff => 1
Nils Diewalde2c83812014-11-11 21:13:18 +0000249
250<p>Of course, Kleene operators can be used with empty segments as well.</p>
251
Nils Diewald2fe12e12015-03-06 16:47:06 +0000252%= kalamar_tut_query poliqarp => '[base=die][]?[base=Baum]'
253%= kalamar_tut_query poliqarp => '[base=die][]*[base=Baum]', cutoff => 1
254%= kalamar_tut_query poliqarp => '[base=die][]+[base=Baum]', cutoff => 1
Nils Diewaldf7366232014-07-25 15:57:08 +0000255
256<h4>Position</h4>
Nils Diewald7cad8402014-07-08 17:06:56 +0000257
Nils Diewalde2c83812014-11-11 21:13:18 +0000258<p>Sequences as shown above can all be nested in further complex queries and treated as subqueries (see <a href="#tut-class-operators">class operators</a> on how to later access these subqueries directly).</p>
259<p>Positional operators compare two matches of subqueries and will match, in case a certain condition regarding the position of both is true.</p>
260<p>The <code>contains()</code> operation will match, when a second subquery matches inside the span of a first subquery.</p>
261
Nils Diewald2fe12e12015-03-06 16:47:06 +0000262%= kalamar_tut_query poliqarp => 'contains(<s>, [tt/p=KOUS])', cutoff => 1
Nils Diewalde2c83812014-11-11 21:13:18 +0000263
264<p>The <code>startsWith()</code> operation will match, when a second subquery matches at the beginning of the span of a first subquery.</p>
265
Nils Diewald2fe12e12015-03-06 16:47:06 +0000266%= kalamar_tut_query poliqarp => 'startsWith(<s>, [tt/p=KOUS])', cutoff => 1
Nils Diewalde2c83812014-11-11 21:13:18 +0000267
268<p>The <code>endsWith()</code> operation will match, when a second subquery matches at the end of the span of a first subquery.</p>
269
Nils Diewald2fe12e12015-03-06 16:47:06 +0000270%= kalamar_tut_query poliqarp => 'endsWith(<s>, [opennlp/p=NN])', cutoff => 1
Nils Diewalde2c83812014-11-11 21:13:18 +0000271
272<p>The <code>matches()</code> operation will match, when a second subquery has the exact same span of a first subquery.</p>
273
Nils Diewald2fe12e12015-03-06 16:47:06 +0000274%= kalamar_tut_query poliqarp => 'matches(<s>,[tt/p=CARD][tt/p="N.*"])', cutoff => 1
Nils Diewalde2c83812014-11-11 21:13:18 +0000275
Nils Diewaldf2e02a92014-11-12 18:31:05 +0000276<p>The <code>overlaps()</code> operation will match, when a second subquery has an overlapping span with the first subquery.</p>
277
Nils Diewald2fe12e12015-03-06 16:47:06 +0000278%= kalamar_tut_query poliqarp => 'overlaps([][tt/p=ADJA],{1:[tt/p=ADJA]}[])', cutoff => 1
Nils Diewald7cad8402014-07-08 17:06:56 +0000279
Nils Diewaldf7366232014-07-25 15:57:08 +0000280<blockquote class="warning">
Nils Diewalde2c83812014-11-11 21:13:18 +0000281 <p>Positional operators are still experimental and may change in certain aspects in the future (although the behaviour defined is intended to be stable). There is also known incorrect behaviour which will be corrected in future versions.</p>
282 <p>Optional operands in position operators, like in <code>contains(&lt;s&gt;,[orth=Baum]*)</code>, have to be mandatory at the moment and will be reformulated to occur at least once.</p>
Nils Diewaldf7366232014-07-25 15:57:08 +0000283 <p>This behaviour may change in the future.</p>
284</blockquote>
285
Nils Diewalde2c83812014-11-11 21:13:18 +0000286<!--
Nils Diewald7cad8402014-07-08 17:06:56 +0000287<blockquote>
Nils Diewaldf21aa152014-07-18 19:10:21 +0000288 <p>The KorAP implementation of Poliqarp also supports the postfix <code>within</code> operator, that works similar to the <code>contains()</code> operator, but is not nestable.</p>
Nils Diewald7cad8402014-07-08 17:06:56 +0000289</blockquote>
Nils Diewalde2c83812014-11-11 21:13:18 +0000290-->
Nils Diewald7cad8402014-07-08 17:06:56 +0000291
Nils Diewald955ca872014-11-07 03:38:31 +0000292</section>
293<section id="tut-class-operators">
Nils Diewald7cad8402014-07-08 17:06:56 +0000294
Nils Diewald955ca872014-11-07 03:38:31 +0000295<h3>Class Operators</h3>
296
297<p>Classes are used to group sub matches by surrounding curly brackets and a class number <code>{1:...}</code>.
298Classes can be used to refer to sub matches in a query, similar to captures in regular expressions.
299In Poliqarp+ classes have multiple purposes, with highlighting being the most intuitive one:</p>
300
Nils Diewald2fe12e12015-03-06 16:47:06 +0000301%= kalamar_tut_query poliqarp => 'der {1:{2:[]} Mann}'
Nils Diewald955ca872014-11-07 03:38:31 +0000302
Nils Diewald2fe12e12015-03-06 16:47:06 +0000303%#= kalamar_tut_query poliqarp => 'der {1:{2:[]{1,4}} {3:Baum}} {4:[]}'
Nils Diewald955ca872014-11-07 03:38:31 +0000304
305<p>In KorAP classes can be defined from 1 to 128. In case a class number is dismissed, the class defaults to the class number 1: <code>{...}</code> is equal to <code>{1:...}</code>.</p>
306
307<h4>Match Modification</h4>
308
309<p>Based on classes, matches may be modified. The <code>focus()</code> operator restricts the span of a match to the boundary of a certain class.</p>
310
Nils Diewald2fe12e12015-03-06 16:47:06 +0000311%= kalamar_tut_query poliqarp => 'focus(der {Baum})'
Nils Diewald955ca872014-11-07 03:38:31 +0000312
313<p>The query above will search for the sequence <code>der Baum</code> but the match will be limited to <code>Baum</code>.
314You can think of <code>der</code> in this query as a positive look-behind zero-length assertion in regular expressions.</p>
315
316<p>But focus is way more useful if you are searching for matches without knowing the surface form. For example, to find all terms between the words &quot;der&quot; and &quot;Mann&quot; you can search:</p>
317
Nils Diewald2fe12e12015-03-06 16:47:06 +0000318%= kalamar_tut_query poliqarp => 'focus(der {[]} Mann)'
Nils Diewald955ca872014-11-07 03:38:31 +0000319
Nils Diewaldf2e02a92014-11-12 18:31:05 +0000320<p>This will limit the match to all interesting terms in between &quot;der&quot; and &quot;Mann&quot;. Or you may want to search for all words following the sequence &quot;der alte und&quot; immediately:</p>
Nils Diewald955ca872014-11-07 03:38:31 +0000321
Nils Diewald2fe12e12015-03-06 16:47:06 +0000322%= kalamar_tut_query poliqarp => 'focus(der alte und {[]})'
Nils Diewald955ca872014-11-07 03:38:31 +0000323
324<!--
325<p><code>focus()</code> is especially useful if you are searching for matches in certain areas, for example in quotes using positional operators.
326While not being interested in the whole quote as a match, you can focus on what's really relevant to you.</p>
327
Nils Diewald2fe12e12015-03-06 16:47:06 +0000328%= kalamar_tut_query poliqarp => 'focus(1:contains(er []{,10} sagte, 1{Baum}))'
Nils Diewald955ca872014-11-07 03:38:31 +0000329-->
330
331<p>In case a class number is dismissed, the focus operator defaults to the class number 1: <code>focus(...)</code> is equal to <code>focus(1: ...)</code>.</p>
332
333<blockquote class="warning">
334 <p>As numbers in curly brackets can be ambiguous in certain circumstances, for example <code>[]{3}</code> can be read as either &quot;any word repeated three times&quot; or &quot;any word followed by the number 3 highlighted as class number 1&quot;, numbers should always be expressed as <code>[orth=3]</code> for the latter case.</p>
335</blockquote>
336
Nils Diewald7cad8402014-07-08 17:06:56 +0000337
338</section>
339
340% end