MPS 2021.1 Help

Generator Demos

Generator Tutorial

Welcome to the updated Generator Tutorial, which will guide you through the process of defining and extending language generators in MPS.
The tutorial has seven parts with gradually increasing complexity. All the demos share the same underlying story - a transformation of XML code into Java Swing components. Each demo is based on the previous one and demonstrates more advanced (or sometimes just different) features, practices and approaches.

Although all the demos are logically related, for educational purposes, we will create a fresh generator in each of the demos. Since generators don't exist in vacuum and always belong to a concrete language, we will create a new language  for each of the demos to wrap the generator. Those languages (except for demo 6 and 7) do not introduce their own new  concepts  (aka syntax). Instead, they give new semantic to the existing concepts.

For instance, the xml element with name 'button' is not just an xml element any more, but a 'virtual concept' representing a GUI component button.

How to Use This Documentation

The best approach is to install JetBrains MPS on your computer, set-up a new empty demo project and carry out all the steps described in demos. This way you will gain great experience in generators development and beyond.

The second option is to read the documentation and, perhaps, browse generator demo project included in the MPS distribution. The generator demo project includes all the demo languages and generators, as well as the test models, which we are going to create in these demos.
The generator demo project is located at: {mps}/samples/generator_demo

Setting-Up Demo Project

If you go the more educative way and plan to build the code from scratch, you need to do some little setup work before starting the individual exercises.

New Project

  • choose File->New Project

  • create a new empty  project

  • enter project name: 'generator_demo'

Gd1

In this demos we are going to define new semantics for xml elements, create test models with some xml in them and generate java code from that xml. The syntax for the XML language has already been defined for you in the SampleXML  sample language, which is also bundled with MPS distributions as a sample project. The SampleXML  project is located at:

$HOME/MPSSamples3.0/samples/sampleXML

You can obviously try the SampleXML  project separately by opening it in MPS. In our demos, however, we will reuse the jetbrains.mps.sampleXML  language only. To start with, let's add the jetbrains.mps.sampleXML  language to the 'generator_demo' project.

  • Right-click on the generator_demo  node in the left-hand side Project View  panel and choose Project Paths. The Alt+Enter  key shortcut will have the same effect.

  • Hit the +  button to add a new module

  • Choose the $HOME/MPSSamples.3.0/sampleXML/languages/sampleXML/jetbrains.mps.sampleXML.mpl  file

  • Gd2

Now the 'jetbrains.mps.sampleXML' language is easily accessible.

Gd3

Right-click the  sampleXML  language node and choose "Rebuild language ..." so that the language is ready to be used.

New Demo Solution

  • choose New Solution in project's popup menu

  • enter the solution name: 'test_models'

  • Gd8

New Test Model

  • choose New Model solution's popup menu

  • enter the model name: 'generator_demo.test1'

Gd4

  • add the 'jetbrains.mps.sampleXML' language to the  Used Language section in the model properties dialog

Gd5

Now you should have a solution with a single model in it and be ready for writing some xml using the just imported simpleXML  language.

In the 'text1' model create new  Document  node and give it name 'Button'.

  • create a Document 'Button' in the model 'test1'

  • add root element 'button' to this document

  • in the same manner create Document 'Label' containing element 'label'

Gd6

Test Generation

  • choose Generate Text in popup menu of the model 'test1'

Gd7

The result of the text generation will be shown as new tabs in the MPS editor and it will be more or less identical to the input.

Now we are all set to go on and define semantics for those otherwise meaningless xml concepts!

What's Inside

Demo 1

This is an easy start. We will transform two types of XML elements into labels and buttons and practice how to use  root mapping rulesroot templateproperty-macroSWITCH-macro and a  template switch  along the way.

Demo 2

This demo will teach you the usage of conditional root rulesLOOP-macros and abandon root rules.

Demo 3

Demonstrates usage of template declarations and template fragments; mapping labels; the ' unique name' service; reference-macros and IF/INCLUDE/MAP_SRC macros.

Demo 4

Demonstrates usage of reduction rules, COPY_SRC-macros and more advanced reference-macros with reference resolving by mapping labels.

Demo 5

Explains how to use generation scripts and how to create utility classes in the generator.

Demo 6

In this demo we will create a 'real' language defining its own higher-level concepts (button and label) and see how languages are integrated together.
This demo explains in greater details the generation process in MPS and demonstrates the usage of transient models and the  generation tracer tool.

Demo 7

Demonstrates usage of  weaving ruletemplate declaration  and  template fragmentmapping label; 'unique name' service;  reference-macro  and  IF/INCLUDE/MAP_SRC  macros.

Last modified: 23 March 2021