DSL Exercise: XText presentation

DSL Exercise: XText presentation A. Marechal May 20th, 2009

1

XText introduction

XText is part of the OpenWarchitercureWeb framework, it’s main purpose is to allow the creation and management of textual DSLs. Complete documentation can be found in the OpenArchitectureWeb website: http://www.openarchitectureweb.org This website includes a nice tutorial for XText, that could help you during the creation of your projects. XText provides some nice utilities for your DSLs. We will use two of its most important features in this exercise: the custom editor and the code generator. To install XText, just follow the standard procedure to install an Eclipse plugin: • In Eclipse, go to Help → Software Updates • Clic on Available Software • Clic on Add site • Enter the OpenArchitectureWeb update site (http://www.openarchitectureware.org/updatesite/milestone/site.xml ) • Select the website you just added and clic on install. Install the whole contents of the website.

1

2

Project creation

Once XText is installed in your Eclipse application, you are able to start the DSL creation. In this exercise, we will create a DSL to specify P/T Petri Nets. The abstract syntax we will use is described in the figure 1.

Figure 1: Petri Nets Metamodel. This first thing to do is to create an XText project as shown in the figure 2. Be sure to tag the Create generator project option, as we will need this generator later. You should see that 3 projects have been generated in your workspace. The first project is the main XText project, we will define the actual DSL there. The second project is the Editor project, it will contain the editor that XText will automatically generate based on our DSL. Finally, the third project will allow us to translate models created using our DSL into something else. In this case, we will translate our model into Java classes.

2

Figure 2: XText Project creation.

3

DSL creation

In the first project, you should easily find a file with the extension xtxt, if you followed the above instructions it should be called PetriNetsdsl.xtxt. This is the file where we will create our DSL. Open it, you should only see a comment, quite an important one. We will use it later. We will now define our first entity, if you check the figure 1, the main entity is PetriNet. Copy the code in the listing 1 in the xtxt file in order to define the PetriNet entity: Listing 1: First rule of the DSL PetriNet : " Petri Net " name = ID 3

" Places " ( places += Place ) * " Transitions " ( transitions += Transition ) * " Arcs " ( arcs += Arc ) *

5

; We have just defined a rule Petri Net with a name, a list of Places, a list of Transitions and a list of Arcs. Each rule of the DSL will correspond to a class of our metamodel. Notice that name, places, transitions and arcs are variables, ID is a predefined xtext type and Place, Transition and Arc are types that we must define. The symbol “+=“ means that the variable contains a list of the corresponding type. The words between quotes are keywords of our language. Notice that we are defining at the same time the abstract and the concrete syntax of our system. All we have to do now is to define the rest of the types. Copy the rest of the code in the same file (see listing 2). Listing 2: Petri Nets DSL

5

10

PetriNet : " Petri Net " name = ID " Places " ( places += Place ) * " Transitions " ( transitions += Transition ) * " Arcs " ( arcs += Arc ) * ; Place : name = ID "(" init = INT ") " ; Transition : name = ID ;

15

Node : Place | Transition ; 20

Arc : " from " from = [ Node ] " to " to = [ Node ] ;

4

The brackets [Node] indicate a reference to existing objects (the editor will check that you already declared the objects you are using here!).

4

Editor creation

Once the DSL is finished, we can see the first XText feature: the editor generation. To create your editor, simply right-clic on your xtext file, and click on Generate XText Artifacts. ***IMPORTANT NOTICE*** After the FIRST code generation, open the file called generate.properties, look for the property overwrite.pluginresources and set it to false. Otherwise you may encounter unexpected errors if you generate your DSL again. If you forgot to set this property to false, generated the code a second time, and find weird errors, the best solution is to copy your xtext file (and every file you manually modified), delete the whole 3 projects, create them again and paste the saved files. Don’t forget this! You have been warned! The editor itself is an Eclipse plugin that was automatically created in the .editor project. In order to use it, we must create an Eclipse instance that takes this plugin into account. This is the easiest way to achieve this: • Clic on the dropdown menu next to the run button • Select Run configurations • Select Eclipse Application and then press the new button. • Select the Eclipse Application you created, select the Arguments tab. • In the box called VM arguments, type -Xmx256M -Xms256M (if your computer has low RAM, you can lower this numbers a bit). • In the Plug-ins tab, check that the projects you created are selected (they should be by default). • When you clic the Run button, a new workspace will be created (no, you can’t use the same worspace as the parent Eclipse application). You can change this worspace location in the Main tab. • Clic the Run button. 5

A new instance of Eclipse will be opened. This instance has a plugin to create Petri Nets using the DSL you previously defined. In order to create a Petri Net, you must create a Petri Net project. Once the project is created, you will see that it contains a src/model.pn file. You can edit this file to declare a Petri Net. You will quickly discover two nice features in this editor: syntax highlighting and code completion. Try to create the Petri Net in the listing 3. If you change your DSL, you must generate the artifacts again, and close and re-open the new Eclipse instance.

5

10

Listing 3: A DSL instance Petri Net myPetriNet Places p1 (1) p2 (2) p3 (1) Transitions t1 t2 Arcs from p1 to t1 from p1 to t2 from t1 to p2 from t2 to p3

5

Code generation

Well, now we have a parser for our DSL, with a neat editor. Now we probably want to actually USE the Petri Nets we build with our editor (i.e. give a semantic to our syntax). We will do this by metamodel transformation, using XPand. This is where the third project you created at the beggining (the generator project) enters the scene. In this project, you will find a file named Main.xpt. In this file we will define rules to translate every object of our DSL into Java code. As the rules to achieve this are a bit long, it will be easier for you to download directly the file Main.xpt available in the course website. Download this file and try to understand the syntax it uses to generate code.

6

Once you have replaced the file Main.xpt in the generator project, go back to the Eclipse instance where you created you Petri Net instance. Just beside the file model.pn, you should find a workflow file with the extension .oaw. Eclipse can execute it automatically (use the Run button). It will generate some java code in your project, and specially an executable file called myPetriNet.java. Execute this file and see the result. Congratulations, you just created your own Domain Specific Language!

7