MTL Plug-ins Features Overview

Authors:	Laurent Goubet
Contact:	Laurent.Goubet@obeo.fr

Introduction

This document provides an overview of the user-visible features of the MTL plug-ins which make it easy to develop and run MTL modules inside Eclipse. It assumes some familiarity with the language itself, although you do not need to be an expert to start using the plug-ins: using the provided example projects and the powerful completion feature of the MTL editor, it is very easy to get started once you understand the basic principles.

Concerning the language, almost all of the MTL keywords are supported (those marked with an asterisk are not fully supported yet):

module, import, extends, template, query, public, private, protected, guard, init,
overrides, each, before, after, for, if, elseif, else, let, elselet, trace*, macro*,
file, mode, text_explicit*, code_explicit*, super, stdout

For all the details about these keywords and the MTL language in general, you can consult the official MTL Specification available at the OMG website.

Requirements

MTL depends on:

EMF runtime ( 2.4.X )
OCL runtime ( 1.2.X )

MTL Modules and Projects

The MTL plugins come with a perspective called MTL. To open this perspective, select Window -> Open perspective -> Others, then click on MTL.

To create a new MTL Module project, open the New project Eclipse wizard, and in the Model to Text Transformation category select MTL Module Project. On the next page, enter the project name. You can then click Finish directly to create an empty MTL project, or go to the next page to create one or several initial template files:

In the Template information section, you can specify the location and name of the new .mtl file to create. In this section, you can also initialize the contents of the template with either a fixed example file (Copy example content), or an existing Acceleo or Xpand template (respectively Migrate .mt content and Migrate .xpt content).

The Metamodel information section allows you to specify the input metamodel of your template, either from the list of registered metamodels or directly by URI. You can also specify the input type of the template.

When you have filled in all required information, you can either click Finish to create the project in the workspace or, if you have enabled the Create more templates on next pages checkbox, go to the Next page to configure more initial templates.

Note that MTL Module projects are also Eclipse Plug-in projects. MTL modules themselves are stored inside the project's source folder, following the same conventions as Java files: a module whose qualified name is com::example::mtl::myModule must be stored in the file com/example/mtl/myModule.mtl in one of the project's source folders.

MTL Template Editor Features

The MTL template editor is associated with MTL source files (.mtl files) and provides all the features of a modern programming editor to make you more productive when developing modules:

Syntax highlighting
Smart completion
Navigation to definitions and references
Error highlighting
Dynamic outline
Code folding

Some of these features are described in details below.

Smart Completion on MTL Syntax Constructs

The MTL editor provides smart completion on all the available MTL language constructs. It is activated by default using the Ctrl+Space key combination.

The completion mechanism is smart enough to only present you the syntactically correct choices in the context where it is invoked. For example, when invoked at the top-level of a file (outside any template), only the top-level MTL constructs are shown:

The context is also used to sort the proposed choices. For example, inside an [if] block, the [elsif] and [else] choices appear at the top of the completion proposals:

Note that although the choices are presented as keywords inside brackets (e.g. [for], [file], etc.), you do not have to type the opening bracket but can simply type the first letters :

Smart Completion on Scripts and Meta-model Elements

Smart completion also works inside MTL expressions, where it can be invoked using Ctrl+Space. It is also auto-activated after a small delay in some circumstances, like after a dot (.).

Inside expressions, completion choices include elements of the meta-models compatible with the context and visible MTL elements (variables, templates and queries, modules) alike.

In the example below, the p variable is a UML property, so completion on the partial expression p.n proposes both features and operations of the UML2 Property class which start with n:

Starting from an empty expression, the completion proposes all the visible MTL variables and templates which can be invoked in addition to features and operations of the current elements (the latter are not visible on the screenshot):

Open Declaration

The MTL editor also support the "Open Declaration" feature (F3 by default), which allows easy navigation from any element to its definition. This works for almost any kind of element you can find in MTL modules: variables, modules, templates and queries, types, features and operations of meta-model elements, even the meta-model themselves from their URI.

Search References

The "Search references" feature can be seen as the reverse of "Open Declaration": instead of navigating from one specific usage of an element to its definition, it searches for all the usages of a particular element. This feature is invoked by default using the Ctrl+Shift+g key combination. It can be used either from the definition of an element (a variable, template, query, etc.) or any particular usage of it.

In the example below, the cursor was on the definition of the iteration variable p in a for loop. Invoking "Search references" by pressing Ctrl+Shift+g opened the Eclipse search view with all the references to this variable inside the current module, and potential matches in other modules in the same project:

As for "Open Declaration", the "Search References" feature works for all kinds of elements: MTL variables, templates, queries and modules, meta-model types, features and operations.

Running and debugging MTL modules

MTL modules can be run and debugged very easily using the standard Eclipse mechanisms.

Inside your MTL modules, you can annotate some of your templates using a special comment [comment @main /]. This identifies these templates as entry points for the generation. When a module contains at least one such entry point, the MTL project builder automatically creates a Java class which can be used to launch the generation.

That Java class contains a main() method which can be used to invoke a generation from that module. It can be called by itself as a normal Java program (including outside of Eclipse), or using the more convenient MTL Application launcher. That program requires two input arguments:

the input model (for example a .uml file)
the target folder

Launching a Module

To launch a generation using an MTL module, open the Eclipse Run configurations dialog, and create a new configuration of type MTL Application.

You can also right-click on a .mtl file and select Run as > MTL Application to open the same dialog with some of the information already configured to run this template.

The mandatory parameters are:

Project: the project containing the module to use
Main class: the Java class generated from your module (if it contains entry points)
Model: the input model for the generation
Target: the target folder in which to put the generated files
Properties: if the templates which serve as entry points to the generation expect arguments, you can specify them in this text area, one per line.
Runner: you have the choice between MTL Plug-in Application (the default) and Java Application. Using the Java Application runner is strictly equivalent to invoking the generated Java class with the input model file and target folder as parameters. This is useful to check that your generator runs correctly in standalone mode (outside of Eclipse), but in this mode it is not possible to debug the MTL templates as such. On the other hand, because the MTL Plug-in Application runner is aware that it is executing an MTL generation, it gives you access to the MTL template debugger described in the next section.

Once you have specified all the required information, the configuration can be invoked like any Eclipse launch configuration.

Debugging your Modules

The MTL plug-ins also include a debugger for you MTL modules. The debugger allows you to set breakpoints inside your MTL templates and thus follow their execution step by step.

To debug an MTL module, follow the sames steps as described above to create a launch configuration, but use the Debug as menu instead of Run as. Once you have a launch configuration, it can be invoked either as a normal launch or as a debug launch.

To put a breakpoint in a template, simply double-click inside the left margin of the MTL editor on the target line. Note that you can only put breakpoints on lines which contain MTL expressions, not on lines which have only fixed text output.

The MTL debugger has some support for conditional breakpoints: once you have set a breakpoint, simply click on it in the left margin. A dialog box appears where you can enter a name pattern:

Once you have set a name pattern, the breakpoint will only be triggered when on elements which names match the pattern (note that currently breakpoint conditions are only taken into account for the next debug session).

When you launch a debug session on your module, if you have breakpoints and they are enabled, the generation will pause when they are hit. If you then switch to the Debug perspective, you should see the familiar debug views:

In the Debug view itself (top left), you can see the current template call stack. If you select a frame, the MTL editor (below) will open on the corresponding file and line. The Variables view (top right) allows you to inspect the current object for the expression being executed.

As in Java, you can use the Step Into, Step Over and Step Return actions to execute the template step by step, Resume the execution until the end or another breakpoint is hit, or simply Stop the session.