Generator Language

Mapping Configuration

Mapping Configuration is a container for generator rules, mapping label declarations and references to pre- and post-processing scripts. A generator model can contain any number of mapping configurations - all of them will be involved in the generation process, if the owning generator module is involved. Mapping configuration also serves as a minimal generator unit that can be referenced in the mapping priority rules.

Generator Rule

Rule	Description	Premise	Consequence
conditional root rule	Generates a root node in the output model. Applied only one time (max) during a single 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 the output model.	concept- applicable concept (concept of the 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 the output model.	root template (ref)
weaving rule	Allows to insert additional child nodes into the output model. Weaving rules are processed at the end of a generation micro-step just before map_src and reference resolving. The rule is applied on each input node of the specified concept. The parent node for insertion should be provided by the context function.	concept- same as above inheritors- same as above condition function (optional) - same as above	external template (ref) weave-each context - function that computes the (parent) output node into which the output node(s) generated by this rule will be inserted. anchor (available in Inspector) - specifies a node within the context collection, in front of which the nodes should be inserted, null means insert at the end of the collection
reduction rule	Transforms the input node while this node is being copied to the 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 the input node, which matches the 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 which otherwise would be copied into the output model.	applicable concept ( including all its sub-concepts) condition function (optional) - same as above	n/a
drop attribute rule	For a transformed node, controls which attributes get copied from the input node	concept- concept of the attribute node (subconcept of `jetbrains.mps.lang.core.structure.Attribute`) 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) - further restrictions to trigger the rule	n/a Attribute is not copied when the rule matches

Consequence	Usage	Description
root template (ref)	conditional root rule (root) mapping rule	Applies the root template
external template (ref)	weaving rule reduction rule pattern rule	Applies an external template. Parameters should be passed if required, they 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 the input node to the output model. The input node will be copied 'as is' (unless some other reduction rules are applicable). The user can also specify an error, warning or an information message.
abandon input	reduction rule pattern rule	Prevents the input node from being copied into the output model.

Root Template

External Template

Mapping Label

Macro

Macro	Description	Properties (if not mentioned above)
Property macro	Computes the value of a property.	value function: return type - string, boolean or int - depending on the property type. parameters - standard + templateValue- value in the template code wrapped by the macro.
Reference macro	Computes the referent node in the output model. Normally executed at the end of a generation micro-step, when the output model (tree) is already constructed. Can also be executed earlier, if the user code is trying to obtain the target of the reference. Reference macro supports `SNodeReference` as specification of a new target. With that, templates don't need access to a target's node model the moment they are applied.	referent function: return type node (type depends on the reference link declaration) `SNodeReference` string identifying the target node. parameters - standard + outputNode- source of the reference link (in the output model).
IF	The wrapped template code is applied only if the 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. It also introduces a LOOP variable that becomes available for queries on macros that are attached to nodes wrapped by the LOOP macro. The LOOP variable gives access to the node that is currently being processed by the LOOP macro. For example, `LOOP.index` holds the index of the current node in the iteration, `LOOP.inputNode` holds the current node itself.	mapped nodes function
INCLUDE	The wrapped template code is ignored (it only serves as an anchor for the INCLUDE-macro), a reusable external template will be used instead. Null input makes INCLUDE effectively a no-op.	mapped node function (optional) include template- reference to a reusable external template
CALL	Invokes template and replaces wrapped template code with the result of template invocation. Supports templates with parameters. Null input node is tolerated, and the template is ignored altogether in this case, i.e. CALL yields empty collection of nodes as a result when input/mapped node is null.	mapped node function (optional) call template- reference to a 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 the template code. The wrapped template code is applied, if none of switch cases is applicable and no default consequence is specified in #template switch. For null input node, SWITCH may react with a message (specified along with its rules), anchor template node is ignored, and SWITCH macro yields no results.	mapped node function (optional) template switch- reference to a template switch
CALL-SITE	Facilitates insertion of a node attributed with a SWITCH/CALL macro in a designated place of the invoked template. In the scenarios when the node wrapped with the SWITCH/CALL macro is relevant in the invoked template/switch, this macro attaches it as a 'call site node'. The node is in such cases processed as a regular template (including potential macros) and the outcome is then supplied to the invoked template/switch as an implicit argument, ready to get inserted into desired location. Templates and switch declarations have a flag (toggled by intention) that indicates that they like to use the call site node. It's an error to use the $CALL-SITE$ macro inside a template/switch that didn't flag the need to get call site. There's no need to specify any explicit argument in CALL/SWITCH, The MPS generator notices that a template/switch needs its call site and in such cases evaluates further templates (including the macros) prior to processing it. This functionality comes handy in scenarios like conditional type casts `(IF needCast (Type) expression ELSE expression)` or conversions when there are multiple sources of expression that may serve as an input, and it's therefore impractical to have dedicated switch/template for each case: `switch { case Double : Double.valueOf(expression); case Integer : Integer.valueOf(expression, 16); ... }`
COPY-SRC	Copies an input node to the output model. The wrapped template code is ignored.	mapped node function - computes the input node to be copied.
COPY-SRCL	Copies input nodes to the 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 a mapping label; replacing the current input node with a new one; perform a non-template based transformation; accessing the output node for some reason. The MAP-SRC macro is executed at the end of a generator micro-step - after all node- and property-macros, but before any reference-macro is run.	mapped node function (optional) mapping func function (optional) - performs non-template based transformation. If defined then the wrapped template code will be ignored. Parameters: standard + parentOutputNode- parent node in the output model. post-processing function (optional) - give access to the output node. Parameters: standard + outputNode
MAP-SRCL	Same as MAP-SRC but can handle many new input nodes (similar to the LOOP-macro)	mapped nodes function mapping func function (optional) post-processing function (optional)
WEAVE	Allows to insert additional child nodes into the output model in a similar way Weaving rules are used. The node wrapped in the WEAVE macro (or provided by the use input function) will have the supplied template applied to it and the generated nodes will be inserted.	use input a function returning a collection of nodes to apply the macro to weave reference to a template to weave into the nodes supplied as the input
VAR	Introduces one or more named values into the generator context, which can then be obtained from the genContext object. The stored variables are read-only and live in the generator context within the scope of the VAR macro.	Each variable has the following parameters: type the optional BaseLanguage type of the stored value, defaults to the type inferred from the value function. value function - returns the value to store in the variable.

Template Switch

A template switch can accept parameters, the same way as template declarations. A use of parametrized switch mandates arguments to be supplied in the SWITCH macro. The TemplateSwitchMacro concept supports switches both with and without arguments.

Generation Context (operations)

Finding Output Node

get output <mapping label> for model ( <model> )	Returns the output node generated by a labeled conditional root rule in a specified model. Issues an error, if there is more than one matching output node.
get output <mapping label> for ( <input node> )	Returns the output node generated from the input node by a labeled generator rule, a macro or a template fragment. Issues an error if there is more than one matching output node.
pick output <mapping label> for ( <input node> )	only used in the context of the referent function in a reference-macro and only if the required output node is a target of the reference, which is being resolved by that reference-macro. Returns the output node generated from the input node by a labeled generator rule, a macro or a template fragment. The difference between this and the 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.
get output list <mapping label> for ( <input node> )	Returns a list of output nodes generated from the input node by a labeled generator rule, a macro or a template fragment.
get copied output for ( <input node> )	Returns the output node, which has been created by copying of an input node. If during the copying, the input node has been reduced, but the concept of the 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 is more than one matching output node.

#patternvar	Value of the captured pattern variable available only in rule consequences
param	Value of the template parameter available only in external templates

Getting Contextual Info

inputModel	The current input model
originalModel	The original input model
outputModel	The current output model
templateNode	The template code surrounded by the macro. It is only used in macro-functions The primary flaw is that this operation implies interpreted templates. There is no template model when templates are generated. Besides, contract of the operation is vague (i.e. what does it give in a context of argument query for a template call).
get prev input <mapping label>	Returns the input node that has been used for enclosing the template code surrounded by the labeled macro. It is only used in macro-functions.

Transferring User Data

session object [ <key> ]
step object [ <key> ]
transient object [ <key> ]

Logging

show info <message text> -> <node>
show error <message text> -> <node>
show warning <message text> -> <node>

Mapping Script

mapping script myPreProcessingScript

script kind : pre-process input model
modifies model : false

(model, genContext, operationContext)->void {
  for (node<MyConcept> te : model.nodes(MyConcept)) {
    genContext.transient object [ MyConceptUtil.KEY_ID ] = ....;
  }
}

script kind	pre-process input model- the script is executed at the beginning of a generation step, before the template-based transformation; post-process output model- the script is executed at the end of a generation step, after the template-based transformation.
modifies model	only available if script kind = pre-process input model If set true and the input model is the original input model, then MPS will create a transient input model before applying the script. If set false but the script tries to modify the input model, then MPS will issue an error.

model	The current model
genContext	The generation context to give access to transient/session or step objects.
invocation context	Operation context (jetbrains.mps.smodel.IOperationContext java interface) associated with the module - the owner of the original input model

model

The current model

genContext

The generation context to give access to transient/session or step objects.

invocation context

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

Generator Language﻿