Child pages
  • Generator Language
Skip to end of metadata
Go to start of metadata

Generator Language Reference

Mapping Configuration

Mapping Configuration is a container for generator rules, mapping label declarations and references on pre- and post-processing scripts. A generator model can contain any number of mapping configurations - all of them will be involved in generation process if the owner generator module is involved. Mapping configuration is a minimal generator unit that can be referenced in mapping priority rules (see Generation Process: Defining the Order of Priorities).

Generator Rule

Generator Rule specifies a transformation of an input node to an output node (except for the conditional root rule which doesn't have an input node). All rules consist of two parts - premise and consequence (except for the abandon root rule which doesn't have a consequence). Any generator rule can be tagged by a mapping label.

All generator rules functions have following parameters:

  • node - current input node (all except condition-function in conditional root rule)
  • genContext - generation context - allows searching of output nodes, generating of unique names and others (see #generation context)

Generator Rules:

Rule

Description

Premise

Consequence

conditional root rule

Generates root node in output model. Applied only one time (max) during the generation step.

condition function (optional), missing condition function is equivalent to a function always returning true.

root template (ref)

root mapping rule

Generates a root node in output model.

concept - applicable concept (concept of input node)
inheritors - if true then the rule is applicable to the specified concept and all its sub-concepts. If false (default) then the sub-concepts are not applicable.
condition function (optional) - see conditional root rule above.
keep input root - if false then the input root node (if it's a root node) will be dropped. If true then input root will be copied to output model.

root template (ref)

weaving rule

Allows to insert additional child nodes into output model. Weaving rules are processed at the end of generation micro-step just before map_src and reference resolving. Rule is applied on each input node of specified concept. Parent node for insertion should be provided by context function.
(see #Model Transformation)

concept - same as above
inheritors - same as above
condition function (optional) - same as above

  • external template (ref)
  • weave-each
    context function - computes (parent) output node into which the output node(s) generated by this rule will be inserted.

reduction rule

Transforms input node while this node is being copied to output model.

concept - same as above
inheritors - same as above
condition function (optional) - same as above

  • external template (ref)
  • in-line template
  • in-line switch
  • dismiss top rule
  • abandon input

pattern rule

Transforms input node, which matches pattern.

pattern - pattern expression
condition function (optional) - same as above

  • external template (ref)
  • in-line template
  • dismiss top rule
  • abandon input

abandon root rule

Allows to drop an input root node with otherwise would be copied into output model.

applicable concept ((warning) including all its sub-concepts)
condition function (optional) - same as above

n/a

Rule Consequences:

Consequence

Usage

Description

root template (ref)

  • conditional root rule
  • (root) mapping rule

Applies root template

external template (ref)

  • weaving rule
  • reduction rule
  • pattern rule

Applies an external template. Parameters should be passed if required, can be one of:

  • pattern captured variable (starting with # sign)
  • integer or string literal
  • null, true, false
  • query function

weave-each

weaving rule

Applies an external template to a set of input nodes.
Weave-each consequence consists of:

  • foreach function - returns a sequence of input nodes
  • reference on an external template

in-line template

  • reduction rule
  • pattern rule

Applies the template code which is written right here.

in-line switch

reduction rule

Consists of set of conditional cases and a default case.
Each case specify a consequence, which can be one of:

  • external template (ref)
  • in-line template
  • dismiss top rule
  • abandon input

dismiss top rule

  • reduction rule
  • pattern rule

Drops all reduction-transformations up to the point where this sequence of transformations has been initiated by an attempt to copy input node to output model. The input node will be copied 'as is' (unless some other reduction rules are applicable). User can also specify an error, warning or information message.

abandon input

  • reduction rule
  • pattern rule

Prevents input node from being copied into output model.

Root Template

Root Template is used in conditional root rules and (root) mapping rules. Generator language doesn't define specific concept for root template. Any root node in output language is treated as a Root Template when created in generator model. The generator language only defines a special kind of annotation - root template header, which is automatically added to each new root template. The root template header is used for specifying of an expected input concept (i.e. concept of input node). MPS use this setting to perform a static type checking in a code in various macro-functions which are used in the root template.

External Template

External Template is a concept defined in the generator language. It is used in weaving rules and reduction rules.

In external template user specifies the template name, input concept, parameters and a content node.

The content node can be any node in output language. The actual template code in external templates is surrounded by template fragment 'tags' (the template fragment is also a special kind of annotation concept). The code outside template fragment serves as a framework (or context) for the real template code (template fragment) and is ignored by the generator. In external template for weaving rule, the template's context node is required (it is a design-time representation of the rule's context node), while template for reduction rule can be just one context-free template fragment. External template for a reduction rule must contain exactly one template fragment, while a weaving rule's template can contain more than one template fragments.

Template fragment has following properties (edited in inspector view):

  • mapping label
  • fragment context - optional function returning new context node which will replace main context node while applying the code in fragment. (warning) Can only be used in weaving rules.

Mapping Label

Mapping Label is declared in mapping configuration and references on this declaration are used to label generator rules, macros and template fragments. Such marks allow finding of an output node by input node (see #generation context).

Properties:

  • name
  • input concept (optional) - expected concept of input node of transformation performed by the tagged rule, macro or template fragment
  • output concept (optional) - expected concept of output node of transformation performed by the tagged rule, macro or template fragment

MPS makes use of the input/output concept settings to perform static type checking in get output ... operations (see #generation context).

Macro

Macro is a special kind of an annotation concept which can be attached to any node in template code. Macro brings dynamic aspect into otherwise static template-based model transformation.

Property- and reference-macro is attached to property- and reference-cell, and node-macro (which comes in many variations - LOOP, IF etc.) is attached to a cell representing the whole node in cell-editor. All properties of macro are edited using inspector view.

All macro have the mapping label property - reference on a mapping label declaration. All macro can be parameterized by various macro-functions - depending on type of the macro. Any macro-function has at least three following parameters:

  • node - current input node;
  • genContext - generation context - allows searching of output nodes, generating of unique names and others;
  • operationContext - instance of jetbrains.mps.smodel.IOperationContext interface (used rarely).

Many of macro have mapped node or mapped nodes function. This function computes new input node - substitution for current input node. If mapped node function returns null or mapped nodes function returns an empty sequence, then generator will skip this macro altogether. I.e. no output will be generated in this place.

Macro

Description

Properties (if not mentioned above)

Property macro

Computes value of property.

value function:

  • return type - string, boolean or int - depending on the property type.
  • parameters - standard + templateValue - value in template code wrapped by the macro.

Reference macro

Computes referent node in output model.
Normally executed in the end of a generation micro-step, when the output model (tree) is already constructed.
Can also be executed earlier if a user code is trying to obtain the target of the reference.

referent function:

  • return type - node (type depends on the reference link declaration) or, in many cases, string identifying the target node (see note).
  • parameters - standard + outputNode - source of the reference link (in output model).

IF

Wrapped template code is applied only if condition is true. Otherwise the template code is ignored and an 'alternative consequence' (if any) is applied.

condition function
alternative consequence (optional) - any of:

  • external template (ref)
  • in-line template
  • abandon input
  • dismiss top rule

LOOP

Computes new input nodes and applies the wrapped template to each of them.

mapped nodes function

INCLUDE

Wrapped template code is ignored (it only serves as an anchor for the INCLUDE-macro), a reusable external template will be used instead.

mapped node function (optional)
include template - reference on reusable external template

CALL

Invokes template, replaces wrapped template code with the result of template invocation. Supports templates with parameters.

mapped node function (optional)
call template - reference on reusable external template

argument - one of

  • pattern captured variable
  • integer or string literal
  • null, true, false
  • query function

SWITCH

Provides a way to many alternative transformations in the given place in template code.
The wrapped template code is applied if none of switch cases is applicable and no default consequence is specified in #template switch.

mapped node function (optional)
template switch - reference on template switch

COPY-SRC

Copies input node to output model. The wrapped template code is ignored.

mapped node function - computes the input node to be copied.

COPY-SRCL

Copies input nodes to output model. The wrapped template code is ignored.
Can be used only for children with multiple aggregation cardinality.

mapped nodes function - computes the input nodes to be copied.

MAP-SRC

Multifunctional macro, can be used for:

  • marking a template code with mapping label;
  • replacing current input node with new one;
  • perform none-template based transformation;
  • accessing output node for some reason.
    MAP-SRC macro is executed in the end of generator micro-step - after all node- and property-macro but before reference-macro.

mapped node function (optional)
mapping func function (optional) - performes none-template based transformation.
If defined then the wrapped template code will be ignored.
Parameters: standard + parentOutputNode - parent node in output model.
post-processing function (optional) - give an access to output node.
Parameters: standard + outputNode

MAP-SRCL

Same as MAP-SRC but can handle many new input nodes (similar to LOOP-macro)

mapped nodes function
mapping func function (optional)
post-processing function (optional)

Note

Icon

Reference resolving by identifier is only supported in BaseLanguage.
The identifier string for classes and class constructors may require (if class is not in the same output model) package name in square brackets preceding the class name:
[package.name]ClassName

Template Switch

Template switch is used in pair with SWITCH-macro (can be re-used in many different SWITCH-macro). Template switch consists of set of cases and one default case. Each switch case is a reduction rule, i.e. template switch contains list of reduction rules actually (see #reduction rule).

The default case consequence can be one of:

  • external template (ref)
  • in-line template
  • abandon input
  • dismiss top rule
    .. or can be omitted. In this case the template code surrounded by corresponding SWITCH-macro will be applied.

Template switch can inherit reduction rules from other switches via the extends property. When generator is executing a SWITCH-macro it tries to find most specific template switch (available in scope). Therefore the actually executed template switch is not necessarily the same as it is defined in template switch property in SWITCH-macro.

In the null-input message property user can specify an error, warning or info message, which will be shown in MPS messages view in case when the mapped node function in SWITCH-macro returns null (by default no messages are shown and macro is skipped altogether).

Generation Context (operations)

Generation context (genContext parameter in macro- and rule-functions) allows finding of nodes in output model, generating unique names and provides other useful functionality.

Generation context can be used not only in generator models but also in utility models - as a variable of type gencontext.

Operations of genContext are invoked using familiar dot-notation: genContext.operation

Finding Output Node

get output <mapping label>

Returns output node generated by labeled conditional root rule.
Issues an error if there are more than one matching output nodes.

get output <mapping label> for ( <input node> )

Returns output node generated from the input node by labeled generator rule, macro or template fragment.
Issues an error if there are more than one matching output nodes.

pick output <mapping label> for ( <input node> )

(warning) only used in context of the referent function in reference-macro and only if the required output node is target of reference which is being resolved by that reference-macro.
Returns output node generated from the input node by labeled generator rule, macro or template fragment. Difference with previous operation is that this operation can automatically resolve the many-output-nodes conflict - it picks the output node which is visible in the given context (see search scope).

get output list <mapping label> for ( <input node> )

Returns list of output nodes generated from the input node by labeled generator rule, macro or template fragment.

get copied output for ( <input node> )

Returns output node which has been created by copying of the input node. If during the copying, the input node has been reduced but concept of output node is the same (i.e. it wasn't reduced into something totally different), then this is still considered 'copying'.
Issues an error if there are more than one matching output nodes.

Generating of Unique Name

unique name from <base name> in context <node>

The uniqueness is secured throughout the whole generation session.
(warning) Clashing with names that wasn't generated using this service is still possible.

The context node is optional, though we recommend to specify it to guarantee generation stability. If specified, then MPS tries its best to generated names 'contained' in a scope (usually a root node). Then when names are re-calculated (due to changes in input model or in generator model), this won't affect other names outside the scope.

Template Parameters

#patternvar

Value of captured pattern variable
(warning) available only in rule consequence

param

Value of template parameter
(warning) available only in external template

Getting Contextual Info

inputModel

Current input model

originalModel

Original input model

outputModel

Current output model

invocation context

Operation context (jetbrains.mps.smodel.IOperationContext java interface) associated with module - owner of the original input model

scope

Scope - jetbrains.mps.smodel.IScope java interface

templateNode

Template code surrounded by macro.
Only used in macro-functions

get prev input <mapping label>

Returns input node that has been used for enclosing template code surrounded by the labeled macro.
Only used in macro-functions.

Transferring User Data

During a generation MPS maintains three maps user objects, each have different life span:

  • session object - kept throughout whole generation session;
  • step object - kept through a generation step;
  • transient object - only live during a micro step.

Developer can access user object maps using an array (square brackets) notation:

The key can be any object (java.lang.Object).

binding user data with particular node

Icon

The session- and step-object cannot be used to pass a data associated with a particular input node across steps and micro-steps because neither an input node nor its id can serve as a key (output nodes always have different id).
To pass such data use methods: putUserObject, getUserObject and removeUserObject defined in class jetbrains.mps.smodel.SNode.
The data will be transferred to all output copies of the input node. The data will be also transferred to output node if a slight reduction (i.e. without changing of the node concept) took place while the node copying.

Logging

Creates message in MPS message view. If the node parameter is specified then clicking on the message will navigate to that node. In case of an error message, MPS will also output some additional diagnostic info.

Utilities (Re-usable Code)

If you have duplicated code (in rules, macros, etc.) and want to say, extract it to re-usable static methods, then you must create this class in a separate, non-generator model.

If you create an utility class in the generator model (i.e. in a model with the 'generator' stereotype), then it will be treated as a root template (unused) and no code will be generated from it.

Mapping Script

Mapping script is a user code which is executed either before a model transformation (pre-processing script) or after it (post-processing script). It should be referenced from #Mapping Configuration to be invoked as a part of it's generation step. Mapping script provides the ability to perform a non-template based model transformation.

Pre-processing scripts are also commonly used for collecting certain information from input model that can be later used in the course of template-based transformation. The information collected by script is saved as a transient-, step- or session-object (see generation context).

Script sample:

Properties:

script kind

  • pre-process input model - script is executed in the beginning of generation step, before template-based transformation;
  • post-process output model - script is executed at the end of generation step, after template-based transformation.

modifies model

only available if script kind = pre-process input model
If set true and input model is the original input model, then MPS will create a transient input model before applying the script.
If set false but script tries to modify input model, then MPS will issue an error.

Code context:

model

Current model

genContext

Generation context to access transient/session or step objects.

invocation context

Operation context (jetbrains.mps.smodel.IOperationContext java interface) associated with module - owner of the original input model

  • No labels