blob: 5f524b33ccdb89fc31c14f2edffb6ee3c2ab2729 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<!ENTITY imgroot "images/tools/ruta/language/" >
<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor
license agreements. See the NOTICE file distributed with this work for additional
information regarding copyright ownership. The ASF licenses this file to
you under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of
the License at Unless required
by applicable law or agreed to in writing, software distributed under the
OF ANY KIND, either express or implied. See the License for the specific
language governing permissions and limitations under the License. -->
<section id="">
<title>Rule elements and their matching order</title>
If not specified otherwise, then the UIMA Ruta rules normally start the matching
process with their first rule element. The first rule element searches for possible positions for its matching
condition and then will advise the next rule element to continue the matching process.
For that reason, writing rules that contain a first rule element with an optional quantifier is discouraged
and will result in ignoring the optional attribute of the quantifier.
The starting rule element can also be manually specified by adding <quote>@</quote> directly in front of the matching condition.
In the following example, the rule first searches for capitalized words (CW) and then checks whether
there is a period in front of the matched word.
<programlisting><![CDATA[PERIOD @CW;]]></programlisting>
This functionality can also be used for rules that start with an optional rule element by manually specifying a later
rule element to start the matching process.
The choice of the starting rule element can greatly influence the performance speed of the rule execution.
This circumstance is illustrated with the following example that contains two rules, whereas already an annotation
of the type <quote>LastToken</quote> was added to the last token of the document:
<programlisting><![CDATA[ANY LastToken;
ANY @LastToken;]]></programlisting>
The first rule matches on each token of the document and checks whether the next annotation is the last token of the document.
This will result in many index operations because all tokens of the document are considered.
The second rule, however, matches on the last token and then checks if there is any token in front of it. This
rule, therefore, considers only one token.
The UIMA Ruta language provides also a concept for automatically selecting the starting rule element called dynamic anchoring.
Here, a simple heuristic concerning the position of the rule element and the involved types is applied in order to identify
the favorable rule element. This functionality can be activated in the <link linkend="">configuration parameters</link> of the analysis engine or
directly in the script file with the <link linkend="">DYNAMICANCHORING</link> action.
A list of rule elements normally specifies a sequential pattern. The rule is able to match if the first rule element successfully matches
and then the following rule element at the position after the match of the first rule element, and so on. There are three language constructs that break up that
sequential matching: <quote><![CDATA[&]]></quote>, <quote>|</quote> and <quote>%</quote>. A composed rule element where all inner rule elements are linked by the symbol <quote><![CDATA[&]]></quote>
matches only if all inner rule elements successfully match at the given position. A composed rule element with inner rule elements linked by the
symbol <quote>|</quote> matches if one of the inner rule element successfully matches. These composed rule elements therefore specify a conjunction (<quote>and</quote>)
and a disjunction (<quote>or</quote>) of its rule element at the given position. The symbol <quote>%</quote> specifies a different use case.
Here, rules themselves are linked and they are only able to fire if each one of the linked rules successfully matched. In contrast to <quote><![CDATA[&]]></quote>,
this linkage of rule elements does not introduce constraints for the matched positions. In the following, a few examples of these three language constructs are given.
<programlisting><![CDATA[(Token.posTag=="DET" & Lemma.value=="the");]]></programlisting>
This rule is fulfilled, if there is a token whose feature <quote>posTag</quote> has the value <quote>DET</quote> and an annotation of the type <quote>Lemma</quote> whose feature <quote>value</quote>
has the value <quote>the</quote>. Both rule elements need to be fulfilled at the same position.
<programlisting><![CDATA[NUM (W{REGEXP("Peter") -> Name} & (ANY CW{PARTOF(Name)}));]]></programlisting>
This rule matches on a number and then validates if the next word is <quote>Peter</quote> and if next but one token is capitalized and part of an annotation of the type <quote>Name</quote>.
If all rule elements successfully matched, then a new annotation of the type <quote>Name</quote> will be created covering the largest match of the linked rule elements. In this example,
the new annotation covers also the token after the word <quote>Peter</quote> even if the actions was specified at the rule element with the smaller match.
<programlisting><![CDATA[((W{REGEXP("Peter")} CW) | ("Mr" PERIOD CW)){-> Name};]]></programlisting>
In this example, an annotation of the type <quote>Name</quote> will be created for the token <quote>Peter</quote> followed by a
capitalized word or the word <quote>Mr</quote> followed by a period and a capitalized word.
<programlisting><![CDATA[(Animal ((COMMA | "and") Animal)+){-> AnimalEnum};]]></programlisting>
This rule annotates enumerations of animal annotations whereas each animal annotation is separated by either a comma or the word <quote>and</quote>.
<programlisting><![CDATA[BLOCK(forEach) Sentence{}{
CW NUM % SW NUM{-> MARK(Found, 1, 2)};
Here, annotations of the type <quote>Found</quote> are created if a sentence contains a capitalized word followed by a number and a small written word followed by a number
regardless of where these annotations occur in the sentence.