Last modified by Richard Kreissig on 2023/09/14 10:07
Show last authors
1 {{info title="Xtext tutorials"}}
2 The two Xtext tutorials are stand-alone tutorials. You do not need to do the Xtext I tutorial in order to perform the Xtext II tutorial. Ask your supervisor which tutorial suits you best.
3 {{/info}}
4
5
6 This tutorial presents the [[Xtext>>url:http://www.eclipse.org/Xtext/||rel="nofollow" shape="rect" class="external-link"]] framework, a toolsuite for the generation of plain text based model editors. Such textual editors provide syntax highlighting, content assist (ctrl-space), an outline, and much more out-of-the-box. You will start by creating a grammar for [[Brainfuck>>url:http://en.wikipedia.org/wiki/Brainfuck||shape="rect"]].
7
8
9
10
11 {{toc/}}
12
13
14 = Preliminaries =
15
16 There's a few things to do before we dive into the tutorial itself.
17
18 == Required Software ==
19
20 For this tutorial, we need you to have Eclipse installed:
21
22 1. Install Eclipse. For what we do, we recommend installing the Eclipse Modeling Tools, with a few extras. Our [[Wiki page on getting Eclipse>>url:http://rtsys.informatik.uni-kiel.de/confluence/display/KIELER/Getting+Eclipse||shape="rect"]] has the details: simply follow the instructions for downloading and installing Eclipse and you should be set.
23 1. Open your eclipse instance and install the complete Xtext SDK 2.7.3 from the itemis updatesite: [[http:~~/~~/download.itemis.de/updates/>>url:http://download.itemis.de/updates/||rel="nofollow" shape="rect"]]
24 [[image:attach:TUT.Xtext 1 - Creating a Grammar for an Existing Metamodel.WebHome@installXtext.png]]
25
26 == Recommended Tutorials ==
27
28 We recommend that you have completed the following tutorials before diving into this one.
29
30 1. [[doc:KIELER.Development.Tutorials.Eclipse.Eclipse Plug-ins and Extension Points.WebHome]]
31 1. [[doc:KIELER.Development.Tutorials.Eclipse.Eclipse Modeling Framework (EMF).WebHome]]
32
33 == Brainfuck ==
34
35 Basically, you are going to write an Xtext grammar for [[Brainfuck>>url:http://en.wikipedia.org/wiki/Brainfuck||shape="rect"]] (BF) in this tutorial. Conceptionally BF programs are working on an endless tape. The program can navigate from cell to cell on the tape and modify the value stored in a particular cell. Your BF language should know the following commands:
36
37 |(((
38 <
39 )))|(((
40 Move one cell to the left on the tape.
41 )))
42 |(% colspan="1" %)(% colspan="1" %)
43 (((
44 ~>
45 )))|(% colspan="1" %)(% colspan="1" %)
46 (((
47 Move one cell to the right on the tape.
48 )))
49 |(% colspan="1" %)(% colspan="1" %)
50 (((
51 +
52 )))|(% colspan="1" %)(% colspan="1" %)
53 (((
54 Increment the value in the actual cell.
55 )))
56 |(% colspan="1" %)(% colspan="1" %)
57 (((
58 -
59 )))|(% colspan="1" %)(% colspan="1" %)
60 (((
61 Decrement the value in the actual cell.
62 )))
63 |(% colspan="1" %)(% colspan="1" %)
64 (((
65 .
66 )))|(% colspan="1" %)(% colspan="1" %)
67 (((
68 Print the actual cell to the console.
69 )))
70 |(% colspan="1" %)(% colspan="1" %)
71 (((
72 [
73 )))|(% colspan="1" %)(% colspan="1" %)
74 (((
75 If the value in the actual cell is 0, jump to the instruction after the corresponding ]
76 )))
77 |(% colspan="1" %)(% colspan="1" %)
78 (((
79 ]
80 )))|(% colspan="1" %)(% colspan="1" %)
81 (((
82 If the value of the actual cell is not 0, jump to the instruction after the corresponding [
83 )))
84
85
86 = Creating a Grammar =
87
88 An Xtext grammar is always related to a specific EMF meta model. The grammar defines a concrete syntax in which instances of the meta model (the abstract syntax) can be serialized and stored. Xtext supports two ways of linking a grammar with a meta model: either creating a grammar for an existing meta model, or creating a grammar first and generating a meta model out of it. In this tutorial you will create a new grammar from scratch!
89
90 1. Select //File// → //New// → //Project...// → //Xtext// → //Xtext Project //→ //Next//
91 1. Enter the following values:
92 1*. //Project name~:// de.cau.cs.rtprak.<login>.brainfuck (like in previous tutorials, replace "login" by your login name)
93 1*. //Location~:// your repository path
94 1*. //Name~:// de.cau.cs.rtprak.<login>.turing.brainfuck.Brainfuck
95 1*. //Extensions~:// brainfuck (the file extension under which your text files will be stored)
96 1*. Uncheck //Create SDK feature project// (not required)
97 [[image:attach:createXtextProject.png]]
98 1. //Finish //→ an editor is opened with a predefined grammar (Brainfuck.xtext). (((
99
100
101 {{code language="text"}}
102 grammar de.cau.cs.rtprak.ssm.brainfuck.Brainfuck with org.eclipse.xtext.common.Terminals
103
104 generate brainfuck "http://www.cau.de/cs/rtprak/ssm/brainfuck/Brainfuck"
105
106 Model:
107 greetings+=Greeting*;
108
109 Greeting:
110 'Hello' name=ID '!';
111
112
113 {{/code}}
114
115
116
117
118 )))
119 1. As you can see in the pre-defined grammar, two grammar rules already exist, Model and Greeting.
120 11. In the Model rule a field greetings (actually a list indicated by the +=) is generated. greetings may contain tokens from the Greeting rule. The list may contain arbitrary many items (indicated by the *)
121 11. The Greeting rule expects the keyword Hello and then a name (defined by ID which is a subset of an arbitrary STRING defined in the Terminals definition imported at the top of the grammar). The rule expects a closing exclamation mark!
122 11. Actually, let's try out the pre-defined grammar.
123 1. (((
124 Open the manifest of the newly created project and add org.eclipse.equinox.common to the required plugins. This is required to start the use the modeling workflow engine to create your DSL automatically.
125 )))
126 1. The Brainfuck.xtext file is located in the package de.cau.cs.rtprak.<login>.turing.text together with a //Modeling Workflow Engine// file, which can be used to configure code generation. Right-click GenerateTuring.mwe2 and select //Run As// → //MWE2 Workflow//. If you get an error message like "//*ATTENTION* It is recommended to use the ANTLR 3 parser generator//" in the console, type //n// and install Antlr from the update site.
127 1. Now a great amount of Java code should have been generated. Add the new plugins to your Eclipse run configuration and start it.
128 1. In the new Eclipse instance, create an empty project and add a file: //File// → //New// → //File// and name it test.brainfuck (when asked to add the Xtext nature, hit //Yes//).
129 1. Use the content assist to generate a valid syntax. Watch the outline while you edit the file. The model objects are created as you type.
130 [[image:attach:outlineXtextPredefined.png]]
131 1. Now, close your eclipse instance and modify your Brainfuck grammar so that Brainfuck programs become valid. There is more than one way to do that... be creative and/or discuss possible grammars with your fellow students. If you need help with the Xtext syntax, contact the Xtext manual: [[http:~~/~~/www.eclipse.org/Xtext/>>url:http://www.eclipse.org/Xtext/||rel="nofollow" shape="rect"]]
132 **IMPORTANT: Make sure your rule for {{code language="none"}}[{{/code}} and {{code language="none"}}]{{/code}} is proper!!**
133 1. (((
134 Re-generate your Brainfuck code and re-run your eclipse instance.
135
136 {{info title="Class Creation"}}
137 Make sure Xtext generates classes for your grammar rules. It is a common mistake to only consume the program tokens and use a list of strings. Your Brainfuck class should contain something like this:
138
139 {{code language="java"}}
140 EList<Command> getCommands();
141 {{/code}}
142 {{/info}}
143 )))
144 1. Use ctrl + space for getting content assist to validate your program syntax. All Brainfuck commands should be visible.
145
146 =
147 To go further =
148
149 Congratulations, you've completed the your first Xtext tutorial. However, as this is a beginners tutorial, you barely touched Xtext. If you want to know more, you could...
150
151 1. Dive deeper into the rich Xtext documentation: [[http:~~/~~/www.eclipse.org/Xtext/>>url:http://www.eclipse.org/Xtext/||rel="nofollow" shape="rect"]]
152 1. Perform our second Xtext tutorial: [[doc:KIELER.Development.Tutorials.Xtext and Xtend.Xtext 1 - Creating a Grammar for an Existing Metamodel.WebHome]]
153 1. Go on with our Xtend tutorial:

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage