ruta-docbook/src/docbook/tools.ruta.language.declarations.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.declarations">
  <title>Declarations</title>
  <para>
    There are three different kinds of declarations in the UIMA Ruta system:
    Declarations of types with optional feature definitions,
    declarations of variables and declarations for importing
    external resources, further UIMA Ruta scripts and UIMA components
    such as type systems and analysis engines.
  </para>
  <section id="ugr.tools.ruta.language.declarations.type">
    <title>Types</title>
    <para>
      Type declarations define new kinds of annotation types and
      optionally their features.
    </para>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[DECLARE SimpleType1, SimpleType2; // <- two new types with the parent 
                                  // type "Annotation"
DECLARE ParentType NewType (SomeType feature1, INT feature2); 
  // a new type "NewType" with parent type "ParentType" and two features]]></programlisting>
        </para>
        <para>
          Attention: Types with features need a parent type in their
          declarations. If no special parent type is
          requested, just use type Annotation as
          default parent type.
        </para>
      </section>
  </section>
  <section id="ugr.tools.ruta.language.declarations.variable">
    <title>Variables</title>
    <para>
      Variable declarations define new variables. There are 12 kinds of
      variables:
      <itemizedlist mark='opencircle'>
        <listitem>
          <para>
            Type variable: A variable that represents an annotation
            type.
          </para>
        </listitem>
        <listitem>
          <para>
            Type list variable: A variable that represents a list of
            annotation
            types.
          </para>
        </listitem>
        <listitem>
          <para>
            Integer variable: A variable that represents an integer.
          </para>
        </listitem>
        <listitem>
          <para>
            Integer list variable: A variable that represents a list of
            integers.
          </para>
        </listitem>
        <listitem>
          <para>
            Float variable: A variable that represents a
            floating-point
            number.
          </para>
        </listitem>
        <listitem>
          <para>
            Float list variable: A variable that represents a list of
            floating-point numbers in single precision.
          </para>
        </listitem>
        <listitem>
          <para>
            Double variable: A variable that represents a
            floating-point
            number.
          </para>
        </listitem>
        <listitem>
          <para>
            Double list variable: A variable that represents a list
            of
            floating-point numbers in double precision.
          </para>
        </listitem>
        <listitem>
          <para>
            String variable: A variable that represents a string.
          </para>
        </listitem>
        <listitem>
          <para>
            String list: A variable that represents a list of strings.
          </para>
        </listitem>
        <listitem>
          <para>
            Boolean
            variable: A variable that represents a boolean.
          </para>
        </listitem>
        <listitem>
          <para>
            Boolean list variable: A variable that represents a list of
            booleans.
          </para>
        </listitem>
        <listitem>
          <para>
            Annotation
            variable: A variable that represents an annotation.
          </para>
        </listitem>
        <listitem>
          <para>
            Annotation list variable: A variable that represents a list of
            annotations.
          </para>
        </listitem>
      </itemizedlist>
    </para>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[TYPE newTypeVariable;
TYPELIST newTypeList;
INT newIntegerVariable;
INTLIST newIntList;
FLOAT newFloatVariable;
FLOATLIST newFloatList;
DOUBLE newDoubleVariable;
DOUBLELIST newDoubleList;
STRING newStringVariable;
STRINGLIST newStringList;
BOOLEAN newBooleanVariable;
BOOLEANLIST newBooleanList;
ANNOTATION newAnnotationVariable;
ANNOTATIONLIST newAnnotationList;]]></programlisting>
        </para>
      </section>
  </section>
  <section id="ugr.tools.ruta.language.declarations.ressource">
    <title>Resources</title>
    <para>
      There are two kinds of resource declarations that make external
      resources available in the UIMA Ruta system:
      <itemizedlist mark='opencircle'>
        <listitem>
          <para>
            List: A list
            represents a normal text file with an entry per
            line
            or a compiled
            tree of a word list.
          </para>
        </listitem>
        <listitem>
          <para>
            Table: A table represents a comma separated
            file.
          </para>
        </listitem>
      </itemizedlist>
    </para>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[WORDLIST listName = 'someWordList.txt';
WORDTABLE tableName = 'someTable.csv';]]></programlisting>
        </para>
      </section>
  </section>
  <section id="ugr.tools.ruta.language.declarations.scripts">
    <title>Scripts</title>
    <para>
      Additional scripts can be imported and reused with the CALL action.
      The types of the imported rules are also available so that it
      is not necessary to import the Type System of the additional rule
      script.
    </para>
      <section>
        <title>
          <emphasis role="bold">Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[SCRIPT my.package.AnotherScript; // "AnotherScript.ruta" in the  
                     //package "my.package"
Document{->CALL(AnotherScript)}; // <- rule executes "AnotherScript.ruta"]]></programlisting>
        </para>
      </section>
  </section>
  <section id="ugr.tools.ruta.language.declarations.components">
    <title>Components</title>
    <para>
      There are three kinds of UIMA components that can be imported in a
      UIMA Ruta script:
      <itemizedlist mark='opencircle'>
        <listitem>
          <para>
            Type System (IMPORT or TYPESYSTEM): includes the types
            defined in an external type system. You can select which
            types or packages to import from a type system and how to
            alias them. If use IMPORT statements, consider enabling
            <link
            linkend='ugr.tools.ruta.ae.basic.parameter.strictImports'>strictImports</link>.
          </para>
        </listitem>
        <listitem>
          <para>
            Analysis Engine (ENGINE): loads the given descriptor and creates an external analysis
            engine. The descriptor  must be located in the descriptor paths.
            The type system needed for the analysis engine has
            to be imported separately. Please mind the filtering setting when
            calling an external analysis engine.
          </para>
        </listitem>
        <listitem>
          <para>
            Analysis Engine (UIMAFIT): loads the given class and creates an external analysis
            engine. Please mind that the implementation of the analysis engine needs to be available. 
            The type system needed for the analysis engine has
            to be imported separately. Please mind the filtering setting when
            calling an external analysis engine.
          </para>
        </listitem>
      </itemizedlist>
    </para>
      <section>
        <title>
          <emphasis role="bold">Type System Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[// Imports all the types from "ExternalTypeSystem.xml"
TYPESYSTEM my.package.ExternalTypeSystem;
IMPORT * FROM my.package.ExternalTypeSystem;

// Import my.package.SomeType from "ExternalTypeSystem.xml"
IMPORT my.package.SomeType FROM my.package.ExternalTypeSystem;

// Import my.package.SomeType from the typesystem available to
// the CAS at runtime. This can be useful when typesystems are
// loaded by uimaFIT
IMPORT my.package.SomeType;

// Import my.package.SomeType from "ExternalTypeSystem.xml" 
// and alias it to T1
IMPORT my.package.SomeType FROM my.package.ExternalTypeSystem AS T1;

// Import all types in my.package from "ExternalTypeSystem.xml"
IMPORT PACKAGE my.package FROM my.package.ExternalTypeSystem;

// Import package my.package from "ExternalTypeSystem.xml" 
// and alias it to p1 (p1.SomeType can now be used)
IMPORT PACKAGE my.package FROM my.package.ExternalTypeSystem AS p1; 

// Import all packages from "ExternalTypeSystem.xml" and alias them to p2
IMPORT PACKAGE * FROM my.package.ExternalTypeSystem AS p2;]]></programlisting>
        </para>
      </section>

      <section>
        <title>
          <emphasis role="bold">Analysis Engine Example:</emphasis>
        </title>
        <para>
          <programlisting><![CDATA[ENGINE my.package.ExternalEngine; // <- "ExternalEngine.xml" in the 
// "my.package" package (in the descriptor folder)
UIMAFIT my.implementation.AnotherEngine;

Document{->RETAINTYPE(SPACE,BREAK),CALL(ExternalEngine)}; 
// calls ExternalEngine, but retains white spaces
Document{-> EXEC(AnotherEngine, {SomeType})};]]></programlisting>
        </para>
      </section>
  </section>
</section>