The purpose of this tutorial is to illustrate the definition of external DSLs using tools form the Eclipse Modeling Project (EMP). The main focus is on the Xtext framework. We will start by defining our own DSL in an Xtext grammar. Then we will use the Xtext framework to generate a parser, an Ecore-based metamodel and a textual editor for Eclipse. Afterwards we will see how to refine the DSL and its editor by means of Xtend extensions. Finally, we will learn how one can generate code out of textual models using the template language Xpand.
The actual content of this example is rather trivial – our DSL will describe entities with properties and references between them from which we generate Java classes according to the JavaBean conventions – a rather typical data model. In a real setting, we might also generate persistence mappings, etc. from the same models. We skipped this to keep the tutorial simple.
To follow this tutorial, you will need to install the following components
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).
my.dsl/src/mydsl.xtxt
Model: (types+=Type)*;Type: DataType | Entity;
DataType: "datatype" name=ID;
Entity: "entity" name=ID "{" (features+=Feature)*
"}"; Feature: type=[Type|ID] name=ID;
![]()
Your grammar should now look like in Figure 18, “DSL grammar”.
Having specified the grammar, we can now generate the DSL editor.
To see the generated editor in action, you have to run the plug-ins in an Eclipse installation. The most convenient way to do this is to start a new Eclipse application from within the running Eclipse:
The generated editor can also be deployed into an existing Eclipse installation. Note that you have to redeploy the editor on every change you apply to the plug-ins. To install the editor into the Eclipse we are currently running, perform the following steps:
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 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:
Syntax coloring
Code completion (press CTRL-Space to invoke)
Navigation (either by holding the CTRL key and left-clicking an identifier or by pressing the F3 key when the cursor is on an identifier)
Find References (place the cursor on an identifier and press CTRL-SHIFT-G)
Folding
Outline
Quick Outline (press CTRL-O)
Syntax checking / Error markers
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.
While Xtext-based DSL editors have a collection of great feature that come for free, they can be easily customized to your needs. In the following section, we will add some extra features that improve your editor's usability. As you will see, implementing those features will not cost us much effort.
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") };
After saving the extension file (and after redeploying the plug-ins and restarting Eclipse, if you are working from an deployed editor), the DSL editor display the new proposals:
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:
From the collection of all model elements,
select all elements that are of type Type (i.e, all DataTypes and all Entities).
Of the resulting collection, select all elements whose name equals the name of the current Type.
Finally, check whether the size of the resulting collection is exactly one (1).
In other words: each model may only have exactly one Type with the same name.
After saving the check file (and after redeploying the plug-ins and restarting Eclipse, if you are working from an deployed editor), the DSL editor now issues an error if you enter two types with the same name:
Now, that we have a DSL, we may want to do something useful with it. DSLs are essentially small programming languages. A programming language has to be understandable by a computer. There are basically two ways to make a language "understandable" by a computer. The first one is to write a compiler which transforms expressions made in one language into another language, which is already understandable by a computer. For example, a Java compiler transforms Java programs to bytecode programs. Bytecode is understandable, because there are VMs which translate expressions in Java bytecode into more native instructions. This is usually done at runtime. Translating a language at runtime is called interpretation (ignoring special cases like just-in-time compilation here).
With Xtext, models one can either create a compiler (also called generator) or an interpreter. Although there are good reasons for both approaches, we will just discuss how one creates a generator in this tutorial.
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:
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:
If you are working from a deployed editor, reexport the plug-ins as described in the section the section called “Running the Editor” and restart Eclipse.
Locate the oAW workflow file mydslproject.oaw in your mydslproject plug-in.
Right-click on it and choose Run as > oAW Workflow from the context menu.
You can see the generator running and logging into the Console view.
The result will be stored in a new source folder src-gen in the mydslproject project.
[java_download] Sun's Java SDK. http://java.sun.com/javase/downloads/index.jsp .
[eclipse_sdk] Eclipse SDK. http://www.eclipse.org/downloads .
[oaw_download] openArchitectureWare download page. http://www.openarchitectureware.org/staticpages/index.php/download .
[oaw_update_site] openArchitectureWare update site. http://www.openarchitectureware.org/updatesite/milestone/site.xml .
[oaw_reference_documentation] openArchitectureWare reference documentation. http://www.openarchitectureware.org/staticpages/index.php/documentation .