Package jetbrains.mps.generator.runtime

Interface TemplateExecutionEnvironment

All Superinterfaces:

GeneratorQueryProvider.Source

All Known Implementing Classes:

TemplateExecutionEnvironmentImpl

public interface TemplateExecutionEnvironment
extends GeneratorQueryProvider.Source

Mediator between template/rule and the generation process, provides access to facilities not specific to particular template being executed. With delegation mechanism to resort to other generator rules/templates (i.e. not part of the active generator; whether interpreted or generated), TemplateExecutionEnvironment is inherently associated with an active generation thread (IMPLEMENTATION NOTE: at the moment, there's one instance per thread/per root).

It's deemed to serve as a mediator between generated and interpreted templates, although present implementation of interpreted templates not always resort to facilities provided by this class.

Unlike TemplateContext, which is call stack for particular template/rule, this class is of broader scope/life-cycle.

This interface is not deemed to be implemented by clients. Generator subsystem provides implementation of this interface, which is an API to generator facilities. New API methods may be added as needed, depecation of existing methods shall respect generated code out there.

See Also:

Evgeny Gryaznov, 10/22/10

Method Summary

Modifier and Type	Method	Description
Collection<SNode>	applyTemplate(SNodeReference templateDeclaration, SNodeReference templateNode, TemplateContext context, Object... arguments)	Deprecated. This method implies instances of TemplateDeclaration rt class are per-invocation (well, technically, one could implement this method in a way to keep cache of TD instances and to configure them with arguments on each apply, it's just more natural to keep TD instances in the place we call this applyTemplate from, like TemplateProcessor's CALL/INCLUDE macros).
List<SNode>	copyNodes(Iterable<SNode> inputNodes, SNodeReference templateNode, String templateNodeId, TemplateContext templateContext)	Copies nodes from input model, trying to apply reduction rules
SNode	createOutputNode(SConcept concept)
TemplateDeclarationKey	createTemplateKey(String modelRef, String nodeId, String templateName)	Intended for use from generated templates to obtain key for findTemplate(TemplateDeclarationKey, SNodeReference) FIXME PROVISIONAL CODE, PLEASE CONSIDER ANOTHER APPROACH see method impl for details
TemplateDeclaration	findTemplate(TemplateDeclarationKey templateDeclaration, SNodeReference callSite)	Retrieve reusable runtime instance that represents TemplateDeclaration.
TemplateGenerator	getGenerator()
IGeneratorLogger	getLogger()
SModel	getOutputModel()
QueryExecutionContext	getQueryExecutor()
ITemplateProcessor	getTemplateProcessor()
GenerationTrace	getTrace()	Access 2nd-generation trace facility
SNode	insertNode(SNode node, SNodeReference templateNode, TemplateContext templateContext)	Support for $INSERT$ macro, adopt a node, prepare it to get inserted into output model
void	nodeCopied(TemplateContext context, SNode outputNode, String templateNodeId)
void	postProcess(NodePostProcessor postProcessor)	Support for $MAP-SRC$ macro, to substitute and/or process nodes in output model once transformation step is over and output model is almost ready.
NodeWeaveFacility	prepareWeave(NodeWeaveFacility.WeaveContext context, SNodeReference templateNode)
void	registerLabel(SNode inputNode, Iterable<SNode> outputNodes, String mappingLabel)
void	registerLabel(SNode inputNode, SNode outputNode, String mappingLabel)
void	resolve(ReferenceResolver resolver)	ReferenceMacro support
void	resolveInTemplateLater(SNode outputNode, SReferenceLink role, SNodeReference templateSourceNode, String templateTargetNodeId, String resolveInfo, TemplateContext context)	Support for references between template nodes
Collection<SNode>	trySwitch(SNodeReference _switch, TemplateContext context)

Methods inherited from interface jetbrains.mps.generator.impl.query.GeneratorQueryProvider.Source

getQueryProvider

Method Detail

getOutputModel

SModel getOutputModel()

createOutputNode

@NotNull
SNode createOutputNode(@NotNull
                       SConcept concept)

Parameters:

concept - we don't expect templates to instantiate interface concepts.

Returns:

instance of the concept, instantiated using output model as a factory, not belonging to the model, though.

getGenerator

@NotNull
TemplateGenerator getGenerator()

getTrace

@NotNull
GenerationTrace getTrace()

Access 2nd-generation trace facility

getLogger

IGeneratorLogger getLogger()

getQueryExecutor

@NotNull
QueryExecutionContext getQueryExecutor()

getTemplateProcessor

@NotNull
ITemplateProcessor getTemplateProcessor()

copyNodes

List<SNode> copyNodes(@NotNull
                      Iterable<SNode> inputNodes,
                      @NotNull
                      SNodeReference templateNode,
                      @NotNull
                      String templateNodeId,
                      @NotNull
                      TemplateContext templateContext)
               throws GenerationCanceledException,
                      GenerationFailureException

Copies nodes from input model, trying to apply reduction rules

Parameters:

inputNodes - nodes to copy

templateNode - element of template model (e.g. one with attached COPY-SRC macro)

templateNodeId - same as previous, as a string representation of a reference

templateContext - context where COPY-SRC was invoked. If context bears any label, output nodes get associated with it, too.

Returns:

copied nodes, or empty list if none copied

Throws:

GenerationCanceledException

GenerationFailureException

insertNode

SNode insertNode(SNode node,
                 SNodeReference templateNode,
                 TemplateContext templateContext)
          throws GenerationCanceledException,
                 GenerationFailureException

Support for $INSERT$ macro, adopt a node, prepare it to get inserted into output model

Throws:

GenerationCanceledException

GenerationFailureException

trySwitch

@Nullable
Collection<SNode> trySwitch(SNodeReference _switch,
                            TemplateContext context)
                     throws GenerationException

Throws:

GenerationException

applyTemplate

@Deprecated
Collection<SNode> applyTemplate(@NotNull
                                SNodeReference templateDeclaration,
                                @NotNull
                                SNodeReference templateNode,
                                @NotNull
                                TemplateContext context,
                                Object... arguments)
                         throws GenerationException

Deprecated.

This method implies instances of TemplateDeclaration rt class are per-invocation (well, technically, one could implement this method in a way to keep cache of TD instances and to configure them with arguments on each apply, it's just more natural to keep TD instances in the place we call this applyTemplate from, like TemplateProcessor's CALL/INCLUDE macros). However, it's fine as frontend for generated code and perhaps, shall stay as one, while interpreted code might get alternative facility to access cacheable TD instances. Nevertheless, existing API is bad, templateNode and context are just to report errors, which could be done by caller, if necessary. Besides, mix of Collection and List in API is inconvenient. Has been replaced with findTemplate(TemplateDeclarationKey, SNodeReference).

Throws:

GenerationException

findTemplate

@NotNull
TemplateDeclaration findTemplate(@NotNull
                                 TemplateDeclarationKey templateDeclaration,
                                 @NotNull
                                 SNodeReference callSite)

Retrieve reusable runtime instance that represents TemplateDeclaration. Clients may keep an instance for subsequent reuse during the same transformation session.

Parameters:

templateDeclaration - identifies template to load

callSite - identifies location where invocation happens

Returns:

never null, non necessarily exact generated class, might be a decorator that traces uses or reports errors.

Since:

2018.3

createTemplateKey

TemplateDeclarationKey createTemplateKey(String modelRef,
                                         String nodeId,
                                         String templateName)

Intended for use from generated templates to obtain key for findTemplate(TemplateDeclarationKey, SNodeReference) FIXME PROVISIONAL CODE, PLEASE CONSIDER ANOTHER APPROACH see method impl for details

Since:

2018.3

nodeCopied

void nodeCopied(TemplateContext context,
                SNode outputNode,
                String templateNodeId)

registerLabel

void registerLabel(SNode inputNode,
                   SNode outputNode,
                   String mappingLabel)

registerLabel

void registerLabel(SNode inputNode,
                   Iterable<SNode> outputNodes,
                   String mappingLabel)

resolveInTemplateLater

void resolveInTemplateLater(@NotNull
                            SNode outputNode,
                            @NotNull
                            SReferenceLink role,
                            SNodeReference templateSourceNode,
                            String templateTargetNodeId,
                            @Nullable
                            String resolveInfo,
                            TemplateContext context)

Support for references between template nodes

resolve

void resolve(@NotNull
             ReferenceResolver resolver)

ReferenceMacro support

Since:

3.4

postProcess

void postProcess(@NotNull
                 NodePostProcessor postProcessor)

Support for $MAP-SRC$ macro, to substitute and/or process nodes in output model once transformation step is over and output model is almost ready. As MPS documentation put it, "MAP-SRC macro is executed in the end of generator micro-step - after all node- and property-macro but before reference-macro."

Since:

3.3

prepareWeave

@NotNull
NodeWeaveFacility prepareWeave(@NotNull
                               NodeWeaveFacility.WeaveContext context,
                               @NotNull
                               SNodeReference templateNode)

Parameters:

context - knows where to put weaved nodes (parent/context and anchor function)

templateNode - call site for the weave (for target template to apply, see NodeWeaveFacility.weaveTemplate(SNodeReference, Object...)

Returns:

utility capable of node weaving with respect to the given context

Since:

3.3