// 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.

[[_ugr.tools.ruta.language.syntax]]
= Syntax

UIMA Ruta defines its own language for writing rules and rule scripts.
This section gives a formal overview of its syntax. 

Structure: The overall structure of a UIMA Ruta script is defined by the following syntax. 

[source]
----
Script              -> PackageDeclaration? GlobalStatements Statements
PackageDeclaration  -> "PACKAGE" DottedIdentifier ";"
GlobalStatments     -> GlobalStatement*   
GlobalStatment      -> ("SCRIPT" | "ENGINE") 
                       DottedIdentifier2 ";"
                       | UimafitImport | ImportStatement
UimafitImport       -> "UIMAFIT" DottedIdentifier2 
                      ("(" DottedIdentifier2 
                      (COMMA DottedIdentifier2)+ ")")?;    
Statements          -> Statement*
Statement           -> Declaration | VariableDeclaration 
                        | BlockDeclaration | SimpleStatement ";"
----
Comments are excluded from the syntax definition.
Comments start with "//" and always go to the end of the line. 

Syntax of import statements: 

[source]
----
ImportStatement  -> (ImportType | ImportPackage | ImportTypeSystem) ";"
ImportType       -> "IMPORT" Type ("FROM" Typesystem)? 
                    ("AS" Alias)?
ImportPackage    -> "IMPORT" "PAKAGE" Package ("FROM" Typesystem)? 
                    ("AS" Alias)?
ImportTypeSystem -> "IMPORT" "PACKAGE" "*" "FROM" TypeSystem ("AS" Alias)?
                    | "IMPORT" "*" "FROM" Typesystem
                    | "TYPESYSTEM" Typesystem
Type             -> DottedIdentifier
Package          -> DottedIdentifier
TypeSystem       -> DottedIdentifier2
Alias            -> Identifier
----

Example beginning of a UIMA Ruta file: 

[source]
----
PACKAGE uima.ruta.example;

// import the types of this type system 
// (located in the descriptor folder -> types folder)
IMPORT * FROM types.BibtexTypeSystem;

SCRIPT uima.ruta.example.Author;
SCRIPT uima.ruta.example.Title;
SCRIPT uima.ruta.example.Year;
----

Syntax of declarations: 

[source]
----
Declaration -> "DECLARE" (AnnotationType)? Identifier ("," Identifier )*
               | "DECLARE" AnnotationType? Identifier ( "("
               FeatureDeclaration ")" )?
FeatureDeclaration  -> ( (AnnotationType | "STRING" | "INT" | "FLOAT"
                       "DOUBLE" | "BOOLEAN") Identifier) )+
VariableDeclaration -> (("TYPE" Identifier ("," Identifier)*
                                                   ("=" AnnotationType)?)
                     | ("STRING" Identifier ("," Identifier)*
                                                 ("=" StringExpression)?)
                     | (("INT" | "DOUBLE" | "FLOAT") Identifier
                               ("," Identifier)* ("=" NumberExpression)?)
                     | ("BOOLEAN" Identifier ("," Identifier)*
                                                ("=" BooleanExpression)?)
                     | ("ANNOTATION" Identifier("="AnnotationExpression)?)
                     | ("WORDLIST" Identifier ("=" WordListExpression 
                                                | StringExpression)?)
                     | ("WORDTABLE" Identifier ("=" WordTableExpression 
                                                | StringExpression)?)
                     | ("TYPELIST" Identifier ("=" TypeListExpression)?)
                     | ("STRINGLIST" Identifier
                                             ("=" StringListExpression)?)
                     | (("INTLIST" | "DOUBLELIST" | "FLOATLIST")
                                  Identifier ("=" NumberListExpression)?)
                     | ("BOOLEANLIST" Identifier
                                           ("=" BooleanListExpression)?))
                     | ("ANNOTATIONLIST" Identifier 
                                         ("=" AnnotationListExpression)?)
AnnotationType      ->  BasicAnnotationType | declaredAnnotationType
BasicAnnotationType ->  ('COLON'| 'SW' | 'MARKUP' | 'PERIOD' | 'CW'| 'NUM'
                      | 'QUESTION' | 'SPECIAL' | 'CAP' | 'COMMA'
                      | 'EXCLAMATION' | 'SEMICOLON' | 'NBSP'| 'AMP' | '_'
                      | 'SENTENCEEND' | 'W' | 'PM' | 'ANY' | 'ALL'
                      | 'SPACE' | 'BREAK')
BlockDeclaration    -> "BLOCK" "(" Identifier ")" RuleElementWithCA
                                                       "{" Statements "}"
actionDeclaration   -> "ACTION" Identifier "(" ("VAR"? VarType 
                       Identifier)? ("," "VAR"? VarType Identifier)*")"  
                      "=" Action ( "," Action)* ";"
conditionDeclaration-> "CONDITION" Identifier "(" ("VAR"? VarType 
                       Identifier)? ("," "VAR"? VarType Identifier)*")"  
                      "=" Condition ( "," Condition)* ";"
----

Syntax of statements and rule elements: 

[source]
----
SimpleStatement        -> SimpleRule | RegExpRule | ConjunctRules 
                          | DocumentActionRule
SimpleRule             -> RuleElements ";"
RegExpRule             -> StringExpression "->" GroupAssignment 
                          ("," GroupAssignment)* ";"
ConjunctRules          -> RuleElements ("%" RuleElements)+ ";"
DocumentActionRule     -> Actions ";"
GroupAssignment        -> TypeExpression 
                        | NumberEpxression "=" TypeExpression
RuleElements           -> RuleElement+
RuleElement            -> (Identifier ":")? "@"? 
                        RuleElementType | RuleElementLiteral
                        | RuleElementComposed | RuleElementWildCard
                        | RuleElementOptional
RuleElementType        ->  AnnotationTypeExpr OptionalRuleElementPart
RuleElementWithCA      ->  AnnotationTypeExpr ("{" Conditions?  
                           Actions? "}")?
AnnotationTypeExpr     -> (TypeExpression | AnnotationExpression
						   TypeListExpression | AnnotationListExpression) 
                          (Operator)? Expression ("{" Conditions "}")?
FeatureMatchExpression -> TypeExpression ( "." Feature)+ 
                          ( Operator (Expression | "null"))?
RuleElementLiteral     ->  SimpleStringExpression OptionalRuleElementPart
RuleElementComposed    -> "(" RuleElement ("&" RuleElement)+ ")"
                          | "(" RuleElement ("|" RuleElement)+ ")"
                          | "(" RuleElements ")"
                          OptionalRuleElementPart
OptionalRuleElementPart-> QuantifierPart? ("{" Conditions?  Actions? "}")?
                          InlinedRules?
InlinedRules           ->  ("<-" "{" SimpleStatement+ "}")*
                           ("->"  "{" SimpleStatement+ "}")*
RuleElementWildCard    -> "#"("{" Conditions?  Actions? }")? InlinedRules?
RuleElementOptional    -> "_"("{" Conditions?  Actions? }")? InlinedRules?
QuantifierPart         -> "*" | "*?" | "+" | "+?" | "?" | "??"
                        | "[" NumberExpression "," NumberExpression "]"
                        | "[" NumberExpression "," NumberExpression "]?"
Conditions             -> Condition ( "," Condition )*
Actions                -> "->" (Identifier ":")? Action 
                         ( "," (Identifier ":")? Action)*
----
Since each condition and each action has its own syntax, conditions and actions are described in their own section.
For conditions see <<_ugr.tools.ruta.language.conditions>> , for actions see <<_ugr.tools.ruta.language.actions>>.
The syntax of expressions is explained in <<_ugr.tools.ruta.language.expressions>>. 

It is also possible to use specific expression as implicit conditions or action additionally to the set of available conditions and actions. 

[source]
----
Condition -> BooleanExpression | FeatureMatchExpression
Action    -> TypeExpression | FeatureAssignmentExpression 
              | VariableAssignmentExpression
----

Identifier: 
[source]
----
DottedIdentifier    ->  Identifier ("." Identifier)*
DottedIdentifier2   ->  Identifier (("."|"-") Identifier)*
Identifier          ->  letter (letter|digit)*
----