Custom language aspect cookbook

Development cycle of custom aspects

1. Create a language to describe the aspect - you may reuse existing languages or create ones specific to the needs of the aspect. For example, each of the core MPS aspects uses its own set of languages, plus a few common ones, such as BaseLanguage or smodel.

2. Declare that this language (possibly with the help of some others) can be used to define some aspect of other languages' definitions - an appropriate aspect descriptor must be created in the language.

3. Develop a generator in the created language to generate aspect's runtime classes (if needed).

4. Develop the aspect subsystem that uses the aspect's runtime.

We'll further go through each step in detail.

Look around the sample project

If you open the customAspect sample project, you will get six modules.

The documentation language and its runtime solution are the key building blocks used to define the new documentation aspects for other language. The aspect subsystem is represented by the pluginSolution, which defines an action that shows the documentation for the concept of the currently focused node. The  sampleLanguage solution is an example of a language that utilizes this new aspect - it uses it to document its own concepts. The  sandbox solution shows the sampleLanguage's usage and allows the user to view the documentation as defined by the documentation aspect. The build solution defines a build script to package the sample project as an MPS plugin.

Language runtime

Before we move on, let's consider for a second how language aspects work at runtime.

• Language descriptor - For each language in MPS, a language descriptor is generated by MPS (the class is called Language.java).

• Aspect interface - Each aspect defines an API for its runtime as a set of interfaces. It must implement a marker interface ILanguageAspect.

• Language.createAspect() - Let's focus on the createAspect() method of the language descriptor here. Given an aspect interface as a parameter, the method returns a concrete implementation of this aspect for this language (let's call it AspectDescriptor).

• Aspect descriptor - The AspectDescriptor is an arbitrary class implementing the Aspect interface. We suggest that an AspectDescriptor contains no code except getters for entities used described by this aspect.

This is how a typical language runtime looks like:

The createAspect() method checks the type of the parameter expecting one of interfaces declared in aspects and returns a corresponding newly instantiated implementation.

This is how the interfaces defined in aspects may look like (this example is defined in the Intentions aspect):

Implementing a custom aspect

Let's look in detail into the steps necessary to implement your custom aspect using the customAspect sample project:

1. To make MPS treat some special model as a documentation aspect (that is our new custom aspect), an aspect declaration should be created in the documentation language. To do so, we create a plugin aspect in the language and import the jetbrains.mps.lang.aspect language.

   

2. Create an aspect declaration in the plugin model of the language and fill in its fields. This tells MPS that this language can be used to implement a new custom aspect for other languages. 

   

3. After making/rebuilding the documentation language, it's already possible to create a documentation aspect in the sample language and create a doc concept in it.

   

4. Instances of the ConceptDocumentation concept can be created in the documentation aspect

   

5. Now, we should move to the language runtime in order to specify the functionality of the new aspect as it should work inside MPS. In our example, let's create an interface that is able to retrieve and return the documentation for a chosen concept. To do so, we create a runtime solution, add it as a runtime module of our documentation language and create an interface in it. Note that the interface must extend the ILanguageAspect interface. Our interface here needs only a single method, that takes a concept as a parameter and returns a string with the corresponding documentation text.

   

6. In the generator for the documentation language we then need to provide an implementation of the interface. A conditional root rule and the following template will do the trick and generate the documentation descriptor class:

   

   The condition ensures that the rule only triggers for the models of your custom aspect, i.e. in our case models that hold the documentation definitions (jetbrains.mps.samples.customAspect.sampleLanguage.documentation ).The useful feature here is the concept switch construction, which allows you to ignore the concept implementation details. It simply loops through all documented concepts (the LOOP macro) and for each such concept creates a matching case (exactly ->$[ConceptDocumentation]) that returns a string value obtained from the associated ConceptDocumentation.

7. So we have an interface and an implementation class. Now, we need to tie them together - we have to generate the part of the createAspect method of the Language runtime class, which will instantiate our concept, i.e. whenever the documentation aspect is required (by passing the DocumentationAspectDescriptor interface), it will return the generated DocumentationDescriptor class.

   
   

   To understand how the following works, look at how the class Language.java is generated (see Language class in model j.m.lang.descriptor.generator.template.main). The descriptor instantiation is done by a template switch called AspectDescriptor_Instantiate in the jetbrains.mps.lang.descriptor class, which we have to extend in our new aspect language so that it works with one more aspect model:

   

   Essentially, we're adding a check for the  DocumentationAspectDescriptor interface to the generated Language class and return a fresh instance of the DocumentationDescriptor, if the requested aspectClass is our custom aspect interface.

8. The only thing left is using our new aspect. For that purpose, an action needs to be created that will show documentation for a concept of a node under cursor on demand:

   

   The model must be imported in order to be able to specify the context parameters. The action must be created as part of a (newly created) plugin solution (more on plugin solutions at Plugin) with a StandalonePluginDescriptor and hooked into the menu through an ActionGroupDeclaration:

   

9. 

   This way the IDE Code menu will be enhanced.

10. Let's now try it out! Rebuild the project, create or open a node of the DocumentedConcept concept in the sandbox solution and invoke the Show Documentation action from the Code menu: