ruta-docbook/src/docbook/tools.ruta.language.expressions.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
<!ENTITY imgroot "images/tools/tools.ruta/" >
<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" >  
%uimaents;
]>
<!-- 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 http://www.apache.org/licenses/LICENSE-2.0 Unless required 
  by applicable law or agreed to in writing, software distributed under the 
  License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 
  OF ANY KIND, either express or implied. See the License for the specific 
  language governing permissions and limitations under the License. -->

<section id="ugr.tools.ruta.language.expressions">
  <title>Expressions</title>
  <para>
    UIMA Ruta provides five different kinds of expressions. These are
    type expressions, number expressions, string expressions,
    boolean expressions and list expressions.
  </para>
  <para>
  <emphasis role="bold">Definition:</emphasis>
<programlisting><![CDATA[RutaExpression  ->   TypeExpression | NumberExpression | 
                           StringExpression | BooleanExpression
                           | ListExpression]]></programlisting>
  </para>
  <section id="ugr.tools.ruta.language.expressions.type">
    <title>Type Expressions</title>
    <para>
      UIMA Ruta provides two kinds of type expressions.
      <orderedlist numeration="arabic">
        <listitem>
          Declared annotation types (see
          <xref linkend='ugr.tools.ruta.language.declarations.type' />
          ).
        </listitem>
        <listitem>
          Type variables
          (see
          <xref linkend='ugr.tools.ruta.language.declarations.variable' />
          ).
        </listitem>
      </orderedlist>
      <section>
        <title>
          <emphasis role="bold">Definition:</emphasis>
        </title>
        <para>
<programlisting><![CDATA[TypeExpression  ->  AnnotationType | TypeVariable]]></programlisting>
        </para>
      </section>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[DECLARE Author;  // Author defines a type, therefore it is 
                 // a type expression
TYPE typeVar;    // type variable typeVar is a type expression 
Document{->ASSIGN(typeVar, Author)};]]></programlisting>
        </para>
      </section>
    </para>
  </section>

  <section id="ugr.tools.ruta.language.expressions.number">
    <title>Number Expressions</title>
    <para>
      UIMA Ruta provides several possibilities to define number
      expressions. As expected, every number expression evaluates to a
      number. UIMA Ruta supports integer and floating-point numbers. A
      floating-point number can be in single or in double precision. To get
      a complete overview, have a look at the following syntax definition
      of number expressions.
      </para>
      <section>
        <title>
          <emphasis role="bold">Definition:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[NumberExpression         -> AdditiveExpression
AdditiveExpression       -> MultiplicativeExpression ( ( "+" | "-" ) 
                            MultiplicativeExpression )*
MultiplicativeExpression -> SimpleNumberExpression ( ( "*" | "/" | "%" ) 
                            SimpleNumberExpression )*
                            | ( "EXP" | "LOGN" | "SIN" | "COS" | "TAN" ) 
                            "(" NumberExpression ")"
SimpleNumberExpression   -> "-"? ( DecimalLiteral | FloatingPointLiteral 
                            | NumberVariable) | "(" NumberExpression ")"
DecimalLiteral        -> ('0' | '1'..'9' Digit*) IntegerTypeSuffix?
IntegerTypeSuffix     ->  ('l'|'L')
FloatingPointLiteral  -> Digit+ '.' Digit* Exponent? FloatTypeSuffix?
                         |   '.' Digit+ Exponent? FloatTypeSuffix?
                         |   Digit+ Exponent FloatTypeSuffix?
                         |   Digit+ Exponent? FloatTypeSuffix
FloatTypeSuffix       ->  ('f'|'F'|'d'|'D')
Exponent              -> ('e'|'E') ('+'|'-')? Digit+
Digit                 -> ('0'..'9') ]]></programlisting>
        </para>
      </section>
      <para>
        For more information on number variables, see
        <xref linkend='ugr.tools.ruta.language.declarations.variable' />
        .
      </para>
      <section>
        <title>
          <emphasis role="bold">Examples:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[98     // a integer number literal
104   // a integer number literal
170.02   // a floating-point number literal
1.0845 // a floating-point number literal]]></programlisting>
        </para>
        <para>
          <programlisting><![CDATA[INT intVar1;
INT intVar2;
...
Document{->ASSIGN(intVar1, 12 * intVar1 - SIN(intVar2))};]]></programlisting>
        </para>
      </section>
  </section>

  <section id="ugr.tools.ruta.language.expressions.string">
    <title>String Expressions</title>
    <para>
      There are two kinds of string expressions in UIMA Ruta.
       
      <orderedlist numeration="arabic">
        <listitem>
         <para>
          String literals: String literals are defined by any sequence of
          characters within quotation marks.
           </para>
        </listitem>
        <listitem>
         <para>
          String variables (see
          <xref linkend='ugr.tools.ruta.language.declarations.variable' />
          )
         </para>
        </listitem>
      </orderedlist>
      </para>
      <section>
        <title>
          <emphasis role="bold">Definition:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[StringExpression   ->   SimpleStringExpression
SimpleStringExpression  ->  StringLiteral ("+" StringExpression)* 
                            | StringVariable]]></programlisting>
        </para>
      </section>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[STRING strVar; // define string variable
// add prefix "strLiteral" to variable strVar
Document{->ASSIGN(strVar, "strLiteral" + strVar)};]]></programlisting>
        </para>
      </section>
  </section>

  <section id="ugr.tools.ruta.language.expressions.boolean">
    <title>Boolean Expressions</title>
    <para>
      UIMA Ruta provides several possibilities to define boolean
      expressions. As expected, every boolean expression evaluates to
      either
      true or false. To get a complete overview, have a look at the
      following syntax definition of boolean expressions.
      </para>
      <section>
        <title>
          <emphasis role="bold">Definition:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[BooleanExpression          ->  ComposedBooleanExpression 
                               | SimpleBooleanExpression
ComposedBooleanExpression  ->  BooleanCompare | BooleanTypeExpression 
                               | BooleanNumberExpression | BooleanFunction
SimpleBooleanExpression     ->  BooleanLiteral | BooleanVariable
BooleanCompare           ->  SimpleBooleanExpression ( "==" | "!=" ) 
                               BooleanExpression
BooleanTypeExpression    ->  TypeExpression ( "==" | "!=" ) TypeExpression
BooleanNumberExpression  ->  "(" NumberExpression ( "<" | "<=" | ">" 
                               | ">=" | "==" | "!=" ) NumberExpression ")"
BooleanFunction   ->  XOR "(" BooleanExpression "," BooleanExpression ")"
BooleanLiteral    ->  "true" | "false"]]></programlisting>
        </para>
        <para>
          Boolean variables are defined in
          <xref linkend='ugr.tools.ruta.language.declarations.variable' />
          .
        </para>
      </section>
      <section>
        <title>
          <emphasis role="bold">Examples:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[Document{->ASSIGN(boolVar, false)};]]></programlisting>
        </para>
        <para>
          The boolean literal 'false' is assigned to boolean variable
          boolVar.
        </para>
        <para>
          <programlisting><![CDATA[Document{->ASSIGN(boolVar, typeVar == Author)};]]></programlisting>
        </para>
        <para>
          If the type variable typeVar represents annotation type Author,
          the
          boolean
          type expression evaluates to true, otherwise it evaluates
          to
          false. The result is assigned to boolean variable boolVar.
        </para>
        <para>
          <programlisting><![CDATA[Document{->ASSIGN(boolVar, (intVar == 10))};]]></programlisting>
        </para>
        <para>
          This rule shows a boolean number expression. If the value in
          variable intVar is equal to 10, the boolean number expression
          evaluates to true, otherwise it evaluates to
          false. The result is
          assigned to boolean variable boolVar. The brackets
          surrounding the number expression are necessary.
        </para>
        <para>
          <programlisting><![CDATA[Document{->ASSIGN(booleanVar1, booleanVar2 == (10 > intVar))};]]></programlisting>
        </para>
        <para>
          This rule shows a more complex boolean expression. If the
          value
          in
          variable intVar is equal to 10, the boolean number
          expression
          evaluates to true, otherwise it evaluates to
          false. The
          result of
          this
          evaluation is compared to booleanVar2. The end result
          is
          assigned to
          boolean variable boolVar1. Realize that the syntax
          definition defines
          exactly this order. It is not possible to have
          the
          boolean number
          expression on the left side of the complex number
          expression.
        </para>
      </section>
  </section>
  

<section id="ugr.tools.ruta.language.expressions.lists">
    <title>List Expressions</title>
    <para>
      List expression are a rather simple kind of expression.
      </para>
      <section>
        <title>
          <emphasis role="bold">Definition:</emphasis>
        </title>
        <para>
<programlisting><![CDATA[ListExpression  ->   WordListExpression | WordTableExpression |
                     TypeListExpression | NumberListExpression |
                     StringListExpression | BooleanListExpression
WordListExpression     ->  RessourceLiteral | WordListVariable
WordTableExpression    ->  RessourceLiteral | WordTableVariable
TypeListExpression     ->  TypeListVariable
                           | "{" TypeExpression ("," TypeExpression)* "}"
NumberListExpression   ->  IntListVariable | FloatListVariable 
                           | DoubleListVariable
                           | "{" NumberExpression 
                              ("," NumberExpression)* "}"
StringListExpression   ->  StringListVariable
                           | "{" StringExpression 
                              ("," StringExpression)* "}"
BooleanListExpression  ->  BooleanListVariable
                           | "{" BooleanExpression 
                              ("," BooleanExpression)* "}"
AnnotationListExpression  ->  AnnotationListVariable
                           | "{" AnnotationExpression 
                              ("," AnnotationExpression)* "}"
]]></programlisting>
    A ResourceLiteral is something
    like 'folder/file.txt' (Attention: Use single quotes).
        </para>
        <para>
          List variables are defined in
          <xref linkend='ugr.tools.ruta.language.declarations.variable' />.
        </para>
      </section>
  </section>
  <section id="ugr.tools.ruta.language.expressions.features">
    <title>Feature Expressions</title>
    <para>
     Feature expression can be used in different situations, e.g., for restricting the match of a rule element, 
     as an implicit condition or as an implicit action.
    <programlisting><![CDATA[FeatureExpression           -> TypeExpression "." DottedIdentifier
FeatureMatchExpression      -> FeatureExpression 
                               ("==" | "!=" | "<=" | "<" | ">=" | ">") 
                               Expression
FeatureAssignmentExpression -> FeatureExpression "=" Expression
]]></programlisting>
    </para>
    <para>
      The covered text of an annotation can be referred to with "coveredText" or "ct". 
      The latter one is an abbreviation and returns the covered text of an annotation
      only if the type of the annotation does not define a feature with the name "ct". 
      The following example creates an annotation of the type TypeA for each word with the 
      covered text "A".
      <programlisting><![CDATA[W.ct == "A" {-> TypeA};]]></programlisting>
    </para>
  </section>
</section>