Build your own textual DSL with Tools from the Eclipse Modeling Project

Xtext projects are based on the well-known Eclipse plug-in architecture. In fact, to create a new textual DSL with Xtext, you'll need up to three projects that depend on each other. But fear not - Xtext comes with a handy wizards to get you up and running in no time.

To create a new Xtext project,

The wizard creates three projects, my.dsl, my.dsl.editor, and my.dsl.generator:

Now that you have created a new Xtext project, you can define the grammar for your DSL. The grammar specifies the metamodel and the concrete syntax for your domain specific language. This allows for fast roundtrips and an incremental development of your language, as you will see later.

To specify the grammar, you will be using the Xtext grammar language. The Xtext documentation contains an extensive reference of all grammar elements. However, to make it easier for you to follow along this tutorial, we have included the relevant grammar rules here.

In this tutorial, we will develop a DSL for entities (since entities are something most developers know quite well).

Model:
  (types+=Type)*;            

Type:
  DataType | Entity;         

DataType:
  "datatype" name=ID;        

Entity:
  "entity" name=ID "{"
    (features+=Feature)*     
  "}";

Feature:
  type=[Type|ID] name=ID;    
			

	The Model rule specifies that a model contains zero or more Types.
	The Type rule is an abstract rule. It specifies that a Type may either be a DataType or an Entity
	The DataType rule specifies that a DataType starts with the literal datatype, followed by a name. The name must comply with the (built-in) rule for identifiers (that is, only characters followed by zero or more characters mixed with any number of numbers are valid).
	The Entity rule specifies that an Entity starts with the literal entity, followed by the name of the entity (which, in turn, must be an identifier). An entity definition has a body which is surrounded by curly braces. The body may then contain any number (zero or more) of Features.
	A Feature has a reference to a Type and a name. The reference to Type is particularly interesting, because by appending the |ID modifier, we point out that the reference to Type will be determined by an ID.

Your grammar should now look like in Figure 1, “DSL grammar”.

Figure 1. DSL grammar

Having specified the grammar, we can now generate the DSL editor.

Figure 2. Generate Xtext artifacts

To run the generated editor, you have to start a new Eclipse workbench with the DSL plug-ins enabled.

Figure 3. Setting up a new Eclipse workbench to test the DSL plug-ins

Figure 4. Creating a new Eclipse run configuration

Figure 5. Increasing maximum heap size

You should now see the same workspace as before. To check out the DSL editor, create a new mydsl project and model in the runtime instance:

The wizard will now create a new project for you, including an empty sample model.

Key in the following model to see your editor in action. Note how the outline reflects the contents of your model. While typing, try using the content assist feature by pressing CTRL-Space.

datatype String
datatype String

entity Person {
	String name
	String lastName
	Address home
	Address business
}

entity Address {
	String street
	String zip
	String city
}		
			

Xtext-based editors support a number of features right out of the box:

It is important to note that all those features have been derived from the grammar you defined earlier. If you make changes to the grammar, the generated tooling will reflect these changes as well, as you will see in a minute.

First, let's enhance code completion. Let's assume you want to assist the user of your editor in choosing the right data types. In most projects, there's probably only about five or six different data types in use, so why not provide them in the suggestion list for the datatype grammar rule?

To do so, open my.dsl.editor/src/org.example.dsl/ContentAssist.ext and insert the following lines at the end of the file:

/* proposals for Feature DataType::name */
List[Proposal] completeDataType_name(emf::EObject ctx, String prefix) :
	{
		newProposal("String"), 
		newProposal("Date"), 
		newProposal("Boolean"), 
		newProposal("Long"), 
		newProposal("int")
	};
			

The name of he extension function must match the following rule: complete<name of the metatype>_<name of the attribute to be completed>. In this sample, the extension function will be invoked as soon as the user requests content assist for the name of a DataType.

After saving the extension file, the DSL editor display the new proposals:

Figure 6. Enhanced content assist in action

You may have noticed that although the generated DSL editor detects syntax violations in your models, it is still possible to define illegal models, e.g. by defining several datatype definitions with the same name.

The Check language from the openArchitectuerWare stack can be used to define constraints that ensure the validity of your models.

Let's define a constraint that ensures that a model does not contain more than one data type with the same name. To do so, open my.dsl/src/org.example.dsl/Checks.chk and add the following contraint to the end of the file:

context Type ERROR "Duplicate type detected: " + this.name :
	allElements().typeSelect(Type).select(e|e.name == this.name).size ==1;
			

This constraint basically means the following:

After saving the check file, the DSL editor now issues an error if you enter two types with the same name:

Figure 7. Constraint fails on duplicate data types

The Xtext wizard already created a generator project for us. We are going to write an Xpand template, which generates simple JavaBeans from our entities. It is assumed, that there is a Java data type corresponding to the data types used in the models (e.g. String). So, we do not need to care about mapping data types.

So just open the Xpand template (Main.xpt) and modify it like this:

Figure 8. Xpand template

The definition main is invoked from the workflow file. It is declared for elements of type mydsl::Model, which corresponds to the root node of our DSL models. Within this definition, another definition (javaBean) is called («EXPAND javaBean...») for each model element (...FOREACH...) contained in the reference 'types' of Model which is of type Entity. (typeSelect(Entity)).

The definition javaBean is declared for elements of type Entity. In this definition, we open a file («FILE ...»). The path name of the file is defined by an expression. In this case, it corresponds to the name of the entity suffixed with '.java'. It is going to be generated into the src-gen directory directly.

All text contained between «FILE ...» and «ENDFILE» will go to the new file. Xpand provides control statements (FOR, IF, ELSEIF, ...), as well as evaluation of expression, in order to create the desired code. See the openArchitectureWare reference documentation for details.

To see our template in action, we have to run the code generator: