~~NOCACHE~~

====== Annotation Syntax ======

In [[vmtl:semantics|VMTL transformations]], patterns are expressed as model fragments in the host modeling language. VMTL defines its own textual annotation language for such model fragments. VMTL annotations support pattern specification, model manipulation, and transformation execution control.

As a prerequisite for using VMTL, the host modeling language **must support annotations** that can be **anchored to specific model elements**. It must be possible to anchor an annotation to more than one model element, as well as leave it un-anchored.

VMTL annotations are declarative. They consist of one or more **clauses** connected by logic operators, where a clause is an assertion made about the annotated model elements or about its containing pattern/rule/transformation as a whole. **Special variables** are used for execution control, and user-defined dynamically-typed **variables** are used to pass values between clauses and between different patterns.

===== User-Defined Variables =====

User-defined variables can be used in any VMTL pattern. They may appear wherever the host modeling language accepts a user-defined meta-attribute value, such as for representing the name of a model element. In addition, they can be manipulated via operators within VMTL annotations. 

User-defined variables have **global scope** within a rule application: once declared, their value can be accessed in all patterns included in the applied rule. Their global scope makes variables suitable for identifying corresponding model elements located in different patterns.

VMTL defines a naming convention for user-defined variables: all variable names are prefixed by the ''$'' character.

===== Data Types =====

Apart from the **Boolean**, **Integer**, **Real**, and **String** types found in many general-purpose languages, VMTL defines the **Element** type used for variables holding host language model elements.

Regardless of their type, all VMTL variables accept the **undefined** value: ''*''. When a variable has this value, it is interpreted as representing any valid value of that data type.

^Type^Description^Examples^
|Boolean | Boolean logic value | ''true'', ''false'' |
|Integer | Integer value. Implementation details (e.g. minimum and maximum values) depend on the execution engine. | ''1'', ''-1'' |
|Real | Floating point value. Implementation details (e.g. minimum and maximum values) depend on the execution engine. | ''1.3'', ''-1.0'' |
|String | Character string enclosed in double quotes. Implementation details (e.g. maximum length) depend on the execution engine. | ''"a string"'' |
|Element | A model element | -- |

===== Operators =====

VMTL defines operators that can be used on both VMTL variables and model element properties. The arithmetic, comparison, and logic operators are similar to those found in many general-purpose languages. The ''.'' model navigation operator is used to access model element properties.

^Operator^Type^Description^Examples^
|''+'', ''-'', ''*'', ''/'' | Arithmetic | Arithmetic operators applicable to Integer and Real values | ''1+3'', ''1.1-0.1'' |
|''='', ''<>'', ''<'', ''<='', ''>'', ''>='' | Comparison | Comparison operators applicable to any values | ''$x="name"'', ''$x>1'' |
|'','' \\ ''and'' | Logic | Conjunction | ''$x=1 , $y=2'' \\ ''$x=1 and $y=2'' |
|'';'' \\ ''or'' | Logic | Disjunction | ''$x=1 ; $x=2'' \\ ''$x=1 or $x=2'' |
|''!'' \\ ''not'' | Logic | Negation | ''!$x'' \\ ''not $x''|
|''->'' \\ ''if <e> then <c>'' | Logic | Implication | ''$x=true -> $y:=1'' \\ ''if $x=true then $y:=1'' |
| ''if <e> then <c1> else <c2>'' | Logic | Executes clause ''<c1>'' if expression ''<e>'' evaluates to true, otherwise executes clause ''<c2>''. Equivalent to ''<e>  ->  <c1>  ;  <c2>''. | ''if $x=1 then $y:=1 else $y:=2'' |
|''.'' | Model navigation | Navigates through attributes, association ends, and operations of a model element. | ''$x.visibility:="private"'' |

===== Special Variables =====

VMTL defines **special variables** as a method of controlling transformation execution (the ''injective'', ''priority'', and ''steps'' variables) and accessing the contents of the source model (the ''id'', ''self'', and ''type'' variables). From a syntactic perspective, special variables are treated just like regular variables.

Each special variable has a **scope**, identifying the fragment of the transformation specification to which the value of the variable is applicable. For instance, every VMTL rule has its own priority, which is independent from the priority of other rules. Therefore, the scope of the ''priority'' special variable is limited to one rule.

^Variable^Type^Scope^Description^Patterns^Examples^
|''id'' | String | Annotated element | Stores an optional user-defined pattern element identifier in order to facilitate the identification of corresponding elements across patterns. | Find, Produce, Update, Require, Forbid | ''id := "1"'' |
|''injective'' | Boolean | Rule | If the value of this special variable is ''true'', each pattern element can be matched to at most one source model element. Otherwise, each pattern element can be matched to several source model elements. | Find, Produce, Update, Require, Forbid | ''injective := true''  |
| ''priority'' | Integer | Rule | Determines the application priority of a rule. Only positive values are allowed, with lower values implying a higher execution priority. The default rule priority is ∞.| Find, Produce, Update, Require, Forbid | ''priority := 1'' |
| ''self'' | Element | Annotated element | Represents the annotated model element. | Find, Produce, Update, Require, Forbid | ''self.visibility := "public"'' |
| ''type'' | String | Annotated element | Provides access to the name of the annotated model element's metaclass. Assigning a new value to this special variable modifies the annotated model element's metaclass. | Find, Produce, Update, Require, Forbid | ''type := "Actor"'' |
| ''steps'' | Integer | Annotated element | States that the annotated model element, which must represent a relation, can be matched to a chain of relations of the same type (i.e. its transitive closure) in the source model. The length of the relations chain is determined by the value of the ''steps'' special variable. | Find, Update, Require, Forbid | ''steps := 3'' \\ ''steps > 3'' \\ ''steps := *'' |
===== Clauses =====

Clauses are the building blocks of VMTL annotations. Each annotation contains one or more clauses connected by logic operators. Clauses are assertions made about the pattern model elements to which they are anchored, about their containing pattern/rule/transformation as a whole, or about special or regular variables. 

Some clauses dictate modifications to the source model (''create'', ''delete''), while others act as constraints on valid matches (''either'', ''indirect'', ''omit'', ''optional''). Variable assignment ('':='') is also treated as a clause.

The ''either'' clause can only be included in annotations anchored to several pattern model elements. All other clauses can be included in annotations anchored to one or more pattern model elements. Anchoring  a clause to several model elements promotes compactness of specification. Finally, the variable assignment clause ('':='') can also appear un-anchorerd to any pattern model elements.

^Clause^Description^Patterns^Examples^
|'':='' | Assigns a value to a variable, special variable, or element attribute. | Find, Produce, Update, Forbid, Require | ''$x':='1'', ''self.name := "User"'' |
|''create'' | Creates the annotated pattern model element in the target model. \\ \\ If a model element not included in the ''Find'' pattern of a rule is included in the rule's ''Produce'' pattern, the element is implicitly created in the target model. In such cases, using the ''create'' clause is optional.|Produce, Update | ''create'' |
|''create singleton'' | Creates the annotated pattern model element in the target model only if it does not exist in the source model. |Produce, Update | ''create'' |
|''delete'' | Deletes the annotated pattern model element from the source model. \\ \\ If a model element included in the ''Find'' pattern of a rule is not included in the rules's ''Produce'' pattern, the element is implicitly deleted in the target model. In such cases, using the ''delete'' clause is optional. | Produce, Update | ''delete'' |
|''either''| Exactly one of the annotated model elements must be matched in the source model. | Find, Forbid, Require | ''either'' |
|''indirect''| The annotated model element, which must represent a relation, can be matched to a chain of relations of the same type (i.e. its transitive closure) in the source model. | Find, Forbid, Require | ''indirect'' |
|''omit'' | The annotated model element must not be matched in the source model. | Find, Forbid, Require | ''omit'' |
|''optional'' | The annotated model element may or may not be matched in the source model. | Find, Forbid, Require | ''optional'' |
| ''unique'' | The annotated model element must be unique within its scope (e.g. package) in the matched model. \\ \\ When this annotation is included in an ''Update'' pattern, the uniqueness condition is applied to both the source and the target model. | Find, Produce, Update, Forbid, Require | ''unique'' |