VIATRA2/Examples/VTCL/VTCL Basics

This page gives a quick tour of the contents of VTCL source files.

Machine declaration

The contents of the file form a single GTASM machine, indicated by the machine keyword. The machine declaration is often preceded by namespace header to declare a namespace for the machine; the full name of the machine (as seen in the VIATRA2 Model Spaces view) will consist of this namespace, a dot, and the regular name. The other type of header is import, which references a namespace in the VPM metamodel; type names below that namespace can be shortened to their relative qualified names throughout the file.

ASM rules

The procedure/method-like basic execution unit of ASM is the ASM rule. A rule is defined by code blocks introduced by the rule keyword, followed by the rule name, and then an arbitrary number of input (in), output (out), or in-out (inout) parameters enclosed in parentheses and tailed by an equality sign. A machine can have a main rule, which serves as an entry point; it is executed when the user runs the transformation from the GUI (the dialog box will ask for input parameters). The rest of the ASM rules can be invoked by a call instruction in other rules of the same machine, or a different machine (qualifying the rule name by the full name of the called machine).

Graph Patterns

Declarative model queries are called Graph Patterns. They are defined in code blocks indicated by the pattern (or shareable pattern) keyword, the pattern name, and an arbitrary number of (symbolic) parameters enclosed in parentheses (here, there is no distinction between input and output parameters). The pattern body follows, enclosed in curly braces; it describes constraints that the substituted value of the parameters must fulfill. Sometimes, there are multiple disjunctive pattern bodies separated by or. A match of the pattern is a substitution of each of its parameters (usually to model elements in the model space, less often to other values), such that all constraints are observed in at least one of the disjunctive pattern bodies. Patterns can be incorporated within each other (or a condition expression) using the pattern call feature (find keyword). Additionally, ASM rules can quantify the parameter values universally over all matches of a pattern (forall loop), or existentially just to find one match (choose keyword).

Graph Transformation Rules

Declarative and semi-declarative model manipulations are called Graph Transformation Rules or GT rules for short. They are defined in code blocks indicated by the gtrule keyword, the GT rule name, an input-output parameter list like the one found at ASM rule declarations, and an equality sign followed by a pair of curly braces enclosing GT rule elements (precondition, postcondition, action). GT rules describe some model manipulation or other effect that is to be executed for matches of a precondition pattern (also known as left-hand-side or LHS). To define this effect, a GT rule contains either a declarative postcondition (right-hand-side or RHS), an imperative action sequence, or both. The precondition is indicated by the keyword precondition, followed either by a pattern call (find keyword) to the precondition pattern, or the inline definition of the precondition pattern. The optional postcondition is defined similarly. The optional imperative action sequence is indicated by the action keyword, followed by a pair of curly braces enclosing a sequence of instructions (similar to seq in ASM rule bodies). A rule application consists of taking a match of the LHS, replace it with the corresponding image of the RHS graph pattern (if any), and executing the action sequence (if any). The quantification syntax (forall, choose) can be used to apply gtrules on all possible or on one single match of the LHS.

ASM Functions

As a less common GTASM element, ASM functions are a global associative (key-value) storage, that contributes to the state of the machine (but not to that of the model, i.e. it is not persisted on saving the model space). Keys are tuples of a chosen number of arguments (arity). ASM funtions are defined by the keyword asmfunction, followed by the name of the ASM function, a slash, and the arity. Optionally, the contents can be initialized by an initialization block containing key-value assignments. The contents of the ASM function can be read or written all throughout the machine, as well as from other machines (the ASM function name will have to be qualified with the full name of the defining machine).

Variables

Variables are used throughout the language. Variable names are required to start with capital letters, to be easily distinguishable from model elements, that usually start with a lower case letter. To avoid ambiguities, the name of model elements starting with capital letters sometimes need to be enclosed in single quotation marks, e.g. 'Activity'. The variables of the VTCL language are untyped by default; they can hold any kinds of value, including model elements (conforming to any type in the metamodel), strings, integers, etc., even arbitrary Java objects. In addition to the parameters, additional local variables can be used in patterns, GT rules and ASM rules. In ASM rules, they have to be introduced by the let variable = initialValue, variable2 = initialValue2 in block construct, or by quantification (over pattern matches or rule applications). Often variables will be initialized with the special value undef to indicate that they have not yet been assigned.

Comments and Annotations

VTCL uses C-like comments: // causes the VTCL parser to ignore the whole following line, while a pair of /* and */ ignore anything between them. Annotations (e.g. @incremental or @random) are not comments; they are parsed and may provide special options on how certain elements should be interpreted. Many GTASM elements (most importantly, pattern and GT rule definitions) can be preceded by annotations, marked by a @ and an annotation name, followed by an optional parentheses-enclosed list of key-value pairs.

Exercise

This exercise relies on the Activity Diagrams to Petri Nets example transformation included in the example transformations package. Make sure the corresponding VIATRA2 project is in your Eclipse workspace.

Open the Activity2PetriNet.vtcl file included in the project. A VTCL Text Editor will appear, highlighting various elements of the syntax, as well as displaying warning or error indicators. The editor has some useful keystrokes, including Alt+P for parsing + loading the machine (same as dragging & dropping the file from the Navigator to the entry in the VIATRA2 Model Spaces view), or Ctrl+S for saving + parsing + loading.

Take a closer look at the vtcl code. Identify the GTASM machine and its entry point. Find the ASM rule, GT rule and graph pattern definitions, and identify their name and parameters. Take a look at the bodies of some of these definitions, and try to identify the variables. Try to find some ASM rule invocations and GT rule applications in the code (call and apply keywords, respectively); hint: hit Ctrl+F while the VTCL file is selected to search in the text. Try to find some graph patterns used as part of a GT rule, either by local declaration or remote reference (find keyword). Try to find some graph patterns used within other graph patterns (find keyword). Try to find some patterns used for pattern matching in ASM rules, iterating over all matches (forall+find structure). Inspect the comments placed in the file, and try to discover which part of the code is responsible for what part of the process.