The VM* Wiki

Official documentation for the VM* family of model manipulation languages.

User Tools

Site Tools


vmtl:annotations

Annotation Syntax

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

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

OperatorTypeDescriptionExamples
+, -, *, / 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.

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

ClauseDescriptionPatternsExamples
:= 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
vmtl/annotations.txt · Last modified: 2015/09/22 17:02 by rvac