NEW - bug 225214: Tutorial: Build your own DSL with Tools from the Eclipse Modeling Project
https://bugs.eclipse.org/bugs/show_bug.cgi?id=225214
diff --git a/Article-BuildYourOwnDSL/article.xml b/Article-BuildYourOwnDSL/article.xml
index bbcc84b..3f7835d 100644
--- a/Article-BuildYourOwnDSL/article.xml
+++ b/Article-BuildYourOwnDSL/article.xml
@@ -1,237 +1,237 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="article">
- <articleinfo>
- <title>Build your own textual DSL with Tools from the Eclipse Modeling Project</title>
- <releaseinfo role="SVN">
- $Id: article.xml,v 1.3 2008/07/23 16:49:44 wbeaton Exp $
- </releaseinfo>
- <date>April 18, 2008</date>
- <authorgroup>
- <author>
- <firstname>Peter</firstname>
- <surname>Friese</surname>
- <affiliation>
- <orgname>itemis AG</orgname>
- <address>
+ <articleinfo>
+ <title>Build your own textual DSL with Tools from the Eclipse Modeling
+ Project</title>
+
+ <releaseinfo role="SVN">$Id: article.xml,v 1.3 2008/07/23 16:49:44 wbeaton
+ Exp $</releaseinfo>
+
+ <date>April 18, 2008</date>
+
+ <authorgroup>
+ <author>
+ <firstname>Peter</firstname>
+
+ <surname>Friese</surname>
+
+ <affiliation>
+ <orgname>itemis AG</orgname>
+
+ <address>
<email>peter.friese@itemis.de</email>
</address>
- </affiliation>
- </author>
- <author>
- <firstname>Sven</firstname>
- <surname>Efftinge</surname>
- <affiliation>
- <orgname>itemis AG</orgname>
- <address>
+ </affiliation>
+ </author>
+
+ <author>
+ <firstname>Sven</firstname>
+
+ <surname>Efftinge</surname>
+
+ <affiliation>
+ <orgname>itemis AG</orgname>
+
+ <address>
<email>sven.efftinge@itemis.de</email>
</address>
- </affiliation>
- </author>
- <author>
- <firstname>Jan</firstname>
- <surname>Köhnlein</surname>
- <affiliation>
- <orgname>itemis AG</orgname>
- <address>
+ </affiliation>
+ </author>
+
+ <author>
+ <firstname>Jan</firstname>
+
+ <surname>Köhnlein</surname>
+
+ <affiliation>
+ <orgname>itemis AG</orgname>
+
+ <address>
<email>jan.koehnlein@itemis.de</email>
</address>
- </affiliation>
- </author>
- </authorgroup>
- <copyright>
- <year>2008</year>
- <holder>itemis AG. All rights reserved.</holder>
- </copyright>
- <abstract>
- <para>
- Domain Specific Languages (DSLs) are a hot topic nowadays. While creating internal DSLs
- is no big deal, external DSLs have been said to be hard to create. In this
- tutorial we will show you how easy it is to create your own DSL with tools from the
- Eclipse Modeling Project (EMP) in less than one hour.
- </para>
- </abstract>
- <legalnotice>
- <para>
- Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United
- States, other countries, or both.
- </para>
- <para>
- Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
- </para>
- <para>
- Microsoft is a trademark of Microsoft Corporation in the United States, other countries, or both.
- </para>
- <para>
- UNIX is a registered trademark of The Open Group in the United States and other countries.
- </para>
- <para>
- Other company, product, or service names may be trademarks or service marks of others.
- </para>
- </legalnotice>
- </articleinfo>
- <section id="introduction">
- <title>Introduction</title>
- <para>
- The purpose of this tutorial is to illustrate the definition of external
- DSLs using tools from the Eclipse Modeling Project (EMP). The main focus is on the
- <emphasis>Xtext</emphasis> framework. We will start by defining our own DSL in an
- <emphasis>Xtext</emphasis> grammar. Then we will use the
- <emphasis>Xtext</emphasis> framework to generate a parser, an
- <emphasis>Ecore-based</emphasis>
- metamodel and a textual editor for Eclipse. Afterwards we will see how to refine
- the DSL and its editor by means of <emphasis>Xtend</emphasis> extensions.
- Finally, we will learn how one can generate code out of textual models using the template
- language <emphasis>Xpand</emphasis>.</para>
+ </affiliation>
+ </author>
+ </authorgroup>
- <para>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.
- </para>
- </section>
- <section id="environment">
- <title>Setting up the Environment</title>
- <para>
- To follow this tutorial, you will need to install the following components
- <itemizedlist>
- <listitem>
- <simpara>
- A Java 5 or 6 SDK. Download it at
- <xref linkend="java_download"/>
- or use another SDK that suits your environment.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Eclipse SDK 3.3 (From the "Europa" release). You can download it from
- <xref linkend="eclipse_europa"/>.
- Install by simply unpacking the archive.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- openArchitectureWare 4.3. Download the ZIP file from
- <xref linkend="oaw_download"/>
- or point your eclipse update manager to
- <xref linkend="oaw_update_site"/>.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The source code for the samples developed in this article can be downloaded from <xref linkend="solution"/>.
- </para>
- </section>
- <section id="defininig_the_dsl">
- <title>Defining the DSL</title>
- <section id="creating_an_xtext_project">
- <title>Creating an Xtext Project</title>
- <para>
- 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.
- </para>
- <para>
- To create a new Xtext project,
- <itemizedlist>
- <listitem>
- <simpara>
- Start up Eclipse 3.3 with oAW 4.3 installed
- (see <xref linkend="environment" />) in a fresh workspace and close the
- welcome screen
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select <emphasis role="bold">File > New... > Project... Xtext Project</emphasis>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Specify the project settings in the wizard dialog. Since you started in a
- fresh workspace, the wizard should provide sensible defaults. See the
- Xtext reference documentation for a detailed overview of what all those
- settings mean.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Click <emphasis role="bold">Finish</emphasis>
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The wizard creates three projects, <filename>my.dsl</filename>,
- <filename>my.dsl.editor</filename>, and <filename>my.dsl.generator</filename>:
-
- <itemizedlist>
- <listitem>
- <simpara>
- <emphasis role="bold">my.dsl</emphasis> is the language project, in which
- we will define the grammar for our DSL. After running the Xtext generator,
- this model also contains a parser for the DSL and a metamodel backing the
- language.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <emphasis role="bold">my.dsl.editor</emphasis> will contain the DSL
- editor. Since we have not yet defined a grammar, this project is still
- empty. It will be filled by the Xtext generator later.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <emphasis role="bold">my.dsl.generator</emphasis> contains an
- openArchitectureWare code generator skeleton. Later in this tutorial, you
- will write a couple of templates that process models created with your
- DSL editor.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="defining_the_grammar">
- <title>Defining the Grammar</title>
- <para>
- Now that you have created a new Xtext project, you can define the grammar for
- your DSL. The grammar specifies the metamodel <emphasis>and</emphasis> 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- In this tutorial, we will develop a DSL for entities (since entities are something
- most developers know quite well).
- <itemizedlist>
- <listitem>
- <simpara>
- Open the Xtext grammar definition <filename>my.dsl/src/mydsl.xtxt</filename>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- And type in the following grammar definition:
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <programlisting>
+ <copyright>
+ <year>2008</year>
+
+ <holder>itemis AG. All rights reserved.</holder>
+ </copyright>
+
+ <abstract>
+ <para>Domain Specific Languages (DSLs) are a hot topic nowadays. While
+ creating internal DSLs is no big deal, external DSLs have been said to
+ be hard to create. In this tutorial we will show you how easy it is to
+ create your own DSL with tools from the Eclipse Modeling Project (EMP)
+ in less than one hour.</para>
+ </abstract>
+
+ <legalnotice>
+ <para>Java and all Java-based trademarks are trademarks of Sun
+ Microsystems, Inc. in the United States, other countries, or
+ both.</para>
+
+ <para>Linux is a trademark of Linus Torvalds in the United States, other
+ countries, or both.</para>
+
+ <para>Microsoft is a trademark of Microsoft Corporation in the United
+ States, other countries, or both.</para>
+
+ <para>UNIX is a registered trademark of The Open Group in the United
+ States and other countries.</para>
+
+ <para>Other company, product, or service names may be trademarks or
+ service marks of others.</para>
+ </legalnotice>
+ </articleinfo>
+
+ <section id="introduction">
+ <title>Introduction</title>
+
+ <para>The purpose of this tutorial is to illustrate the definition of
+ external DSLs using tools from the Eclipse Modeling Project (EMP). The
+ main focus is on the <emphasis>Xtext</emphasis> framework. We will start
+ by defining our own DSL in an <emphasis>Xtext</emphasis> grammar. Then we
+ will use the <emphasis>Xtext</emphasis> framework to generate a parser, an
+ <emphasis>Ecore-based</emphasis> metamodel and a textual editor for
+ Eclipse. Afterwards we will see how to refine the DSL and its editor by
+ means of <emphasis>Xtend</emphasis> extensions. Finally, we will learn how
+ one can generate code out of textual models using the template language
+ <emphasis>Xpand</emphasis>.</para>
+
+ <para>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.</para>
+ </section>
+
+ <section id="environment">
+ <title>Setting up the Environment</title>
+
+ <para>To follow this tutorial, you will need to install the following
+ components <itemizedlist>
+ <listitem>
+ <simpara>A Java 5 or 6 SDK. Download it at <xref
+ linkend="java_download" /> or use another SDK that suits your
+ environment.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Eclipse SDK 3.4 (From the "Ganymede" release). You can
+ download it from <xref linkend="eclipse_ganymede" />. Install by
+ simply unpacking the archive.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>openArchitectureWare 4.3. Download the ZIP file from <xref
+ linkend="oaw_download" /> or point your eclipse update manager to
+ <xref linkend="oaw_update_site" />.</simpara>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The source code for the samples developed in this article can be
+ downloaded from <xref linkend="solution" />.</para>
+ </section>
+
+ <section id="defininig_the_dsl">
+ <title>Defining the DSL</title>
+
+ <section id="creating_an_xtext_project">
+ <title>Creating an Xtext Project</title>
+
+ <para>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.</para>
+
+ <para>To create a new Xtext project, <itemizedlist>
+ <listitem>
+ <simpara>Start up Eclipse 3.4 with oAW 4.3 installed (see <xref
+ linkend="environment" />) in a fresh workspace and close the
+ welcome screen</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Select <emphasis role="bold">File > New... >
+ Project... Xtext Project</emphasis></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Specify the project settings in the wizard dialog. Since
+ you started in a fresh workspace, the wizard should provide
+ sensible defaults. See the Xtext reference documentation for a
+ detailed overview of what all those settings mean.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Click <emphasis role="bold">Finish</emphasis></simpara>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The wizard creates three projects, <filename>my.dsl</filename>,
+ <filename>my.dsl.editor</filename>, and
+ <filename>my.dsl.generator</filename>: <itemizedlist>
+ <listitem>
+ <simpara><emphasis role="bold">my.dsl</emphasis> is the language
+ project, in which we will define the grammar for our DSL. After
+ running the Xtext generator, this model also contains a parser for
+ the DSL and a metamodel backing the language.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><emphasis role="bold">my.dsl.editor</emphasis> will
+ contain the DSL editor. Since we have not yet defined a grammar,
+ this project is still empty. It will be filled by the Xtext
+ generator later.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><emphasis role="bold">my.dsl.generator</emphasis>
+ contains an openArchitectureWare code generator skeleton. Later in
+ this tutorial, you will write a couple of templates that process
+ models created with your DSL editor.</simpara>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section id="defining_the_grammar">
+ <title>Defining the Grammar</title>
+
+ <para>Now that you have created a new Xtext project, you can define the
+ grammar for your DSL. The grammar specifies the metamodel
+ <emphasis>and</emphasis> 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.</para>
+
+ <para>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.</para>
+
+ <para>In this tutorial, we will develop a DSL for entities (since
+ entities are something most developers know quite well). <itemizedlist>
+ <listitem>
+ <simpara>Open the Xtext grammar definition
+ <filename>my.dsl/src/mydsl.xtxt</filename></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>And type in the following grammar definition:</simpara>
+ </listitem>
+ </itemizedlist></para>
+
+ <programlisting>
Model:
- (types+=Type)*; <co id="rule.model"/>
+ (types+=Type)*; <co id="rule.model" />
Type:
- DataType | Entity; <co id="rule.type"/>
+ DataType | Entity; <co id="rule.type" />
DataType:
"datatype" name=ID; <co id="rule.datatype" />
@@ -244,180 +244,214 @@
Feature:
type=[Type|ID] name=ID; <co id="rule.feature" />
</programlisting>
- <calloutlist>
- <callout arearefs="rule.model">
- <para>
- The <emphasis role="bold">Model</emphasis> rule specifies that a model contains
- zero or more <emphasis role="bold">Types</emphasis>.
- </para>
- </callout>
- <callout arearefs="rule.type">
- <para>
- The <emphasis role="bold">Type</emphasis> rule is an abstract rule. It specifies
- that a <emphasis role="bold">Type</emphasis> may either be a <emphasis role="bold">DataType</emphasis>
- or an <emphasis role="bold">Entity</emphasis>
- </para>
- </callout>
- <callout arearefs="rule.datatype">
- <para>
- The <emphasis role="bold">DataType</emphasis> rule specifies that a <emphasis role="bold">DataType</emphasis>
- starts with the literal <emphasis role="bold">datatype</emphasis>, 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).
- </para>
- </callout>
- <callout arearefs="rule.entity">
- <para>
- The <emphasis role="bold">Entity</emphasis> rule specifies that an <emphasis role="bold">Entity</emphasis>
- starts with the literal <emphasis role="bold">entity</emphasis>, 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 <emphasis role="bold">Feature</emphasis>s.
- </para>
- </callout>
- <callout arearefs="rule.feature">
- <para>
- A <emphasis role="bold">Feature</emphasis> has a reference to a <emphasis role="bold">Type</emphasis>
- and a name. The reference to <emphasis role="bold">Type</emphasis> is particularly interesting,
- because by appending the <emphasis>|ID</emphasis> modifier, we point out that
- the reference to <emphasis role="bold">Type</emphasis> will be determined by an ID.
- </para>
- </callout>
- </calloutlist>
- <para>
- Your grammar should now look like in <xref linkend="xtext_dsl_grammar"/>.
- </para>
- <figure id="xtext_dsl_grammar">
- <title>DSL grammar</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/3_grammar.png"
- scale="60" />
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/3_grammar.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="generating_the_dsl_editor">
- <title>Generating the DSL Editor</title>
- <para>
- Having specified the grammar, we can now generate the DSL editor.
- <itemizedlist>
- <listitem>
- <simpara>
- Right-click inside the Xtext grammar editor to open the context menu.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select <emphasis role="bold">Generate Xtext Artifacts</emphasis> to
- generate the DSL parser, the corresonding metamodel and, last but not
- least, the DSL editor.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <figure id="generate_xtext_artifacts">
- <title>Generate Xtext artifacts</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/4_generate_xtext_artifacts.png"
- scale="60" />
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/4_generate_xtext_artifacts.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="running_the_editor">
- <title>Deploying and Running the Editor</title>
- <para>
- To run the generated editor, you have to deploy the DSL plug-ins to an Eclipse
- installation. For simplicity, we take the one we are already running.
- <itemizedlist>
- <listitem>
- <simpara>
- Choose <emphasis role="bold">Export... > Deployable plug-ins and
- fragments...</emphasis>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- The <emphasis>Export</emphasis> dialog appears.
- Select the three DSL plug-ins.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Enter the path to your Eclipse installation. Make sure the selected
- directory contains the Eclipse executable and a folder named
- <emphasis>plugins</emphasis>. Usually, the directory is called
- <emphasis>eclipse</emphasis>.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Choose <emphasis role="bold">Finish</emphasis>.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Restart Eclipse.
- </simpara>
- </listitem>
- </itemizedlist>
- <figure id="deploy_plugins">
- <title>Deployment of the DSL plug-ins</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/5_deploy_plugins.png"
- scale="60" />
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/5_deploy_plugins.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </para>
- </section>
- <section id="exploring_the_editor">
- <title>Taking it for a spin</title>
- <para>
- You should now see the same workspace as before. To check out the DSL editor, create
- a new <emphasis>mydsl</emphasis> project and model in the runtime instance:
- </para>
- <itemizedlist>
- <listitem>
- <simpara>
- Select <emphasis role="bold">File > New... > Other... > mydsl
- Project</emphasis> to create a new <emphasis>mydsl</emphasis> project.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Click <emphasis role="bold">Next</emphasis> to proceed to the next wizard page.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Leave the project name as is (it should read <emphasis>mydslproject</emphasis>)
- and click <emphasis role="bold">Finish</emphasis> to create the project.
- </simpara>
- </listitem>
- </itemizedlist>
- <para>
- The wizard will now create a new project for you, including an empty sample model.
- </para>
- <para>
- 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 <keycombo><keycap>CTRL</keycap><keycap>Space</keycap></keycombo>.
- </para>
- <programlisting>
+ <calloutlist>
+ <callout arearefs="rule.model">
+ <para>The <emphasis role="bold">Model</emphasis> rule specifies that
+ a model contains zero or more <emphasis
+ role="bold">Types</emphasis>.</para>
+ </callout>
+
+ <callout arearefs="rule.type">
+ <para>The <emphasis role="bold">Type</emphasis> rule is an abstract
+ rule. It specifies that a <emphasis role="bold">Type</emphasis> may
+ either be a <emphasis role="bold">DataType</emphasis> or an
+ <emphasis role="bold">Entity</emphasis></para>
+ </callout>
+
+ <callout arearefs="rule.datatype">
+ <para>The <emphasis role="bold">DataType</emphasis> rule specifies
+ that a <emphasis role="bold">DataType</emphasis> starts with the
+ literal <emphasis role="bold">datatype</emphasis>, 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).</para>
+ </callout>
+
+ <callout arearefs="rule.entity">
+ <para>The <emphasis role="bold">Entity</emphasis> rule specifies
+ that an <emphasis role="bold">Entity</emphasis> starts with the
+ literal <emphasis role="bold">entity</emphasis>, 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 <emphasis
+ role="bold">Feature</emphasis>s.</para>
+ </callout>
+
+ <callout arearefs="rule.feature">
+ <para>A <emphasis role="bold">Feature</emphasis> has a reference to
+ a <emphasis role="bold">Type</emphasis> and a name. The reference to
+ <emphasis role="bold">Type</emphasis> is particularly interesting,
+ because by appending the <emphasis>|ID</emphasis> modifier, we point
+ out that the reference to <emphasis role="bold">Type</emphasis> will
+ be determined by an ID.</para>
+ </callout>
+ </calloutlist>
+
+ <para>Your grammar should now look like in <xref
+ linkend="xtext_dsl_grammar" />.</para>
+
+ <figure id="xtext_dsl_grammar">
+ <title>DSL grammar</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/3_grammar.png" scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/3_grammar.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section id="generating_the_dsl_editor">
+ <title>Generating the DSL Editor</title>
+
+ <para>Having specified the grammar, we can now generate the DSL editor.
+ <itemizedlist>
+ <listitem>
+ <simpara>Right-click inside the Xtext grammar editor to open the
+ context menu.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Select <emphasis role="bold">Generate Xtext
+ Artifacts</emphasis> to generate the DSL parser, the corresonding
+ metamodel and, last but not least, the DSL editor.</simpara>
+ </listitem>
+ </itemizedlist></para>
+
+ <figure id="generate_xtext_artifacts">
+ <title>Generate Xtext artifacts</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/4_generate_xtext_artifacts.png"
+ scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/4_generate_xtext_artifacts.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section id="running_the_editor">
+ <title>Running the Editor</title>
+
+ <para>To run the generated editor, you have to start a new Eclipse
+ workbench with the DSL plug-ins enabled. <itemizedlist>
+ <listitem>
+ <simpara>Choose <emphasis role="bold">Run -> Run
+ Configurations...</emphasis></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>The <emphasis>Run Configuraton</emphasis> dialog appears.
+ Choose <emphasis role="bold">New</emphasis> from the context menu
+ of <emphasis role="bold">Eclipse Application</emphasis></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Choose <emphasis role="bold">New</emphasis> from the
+ context menu of <emphasis role="bold">Eclipse
+ Application</emphasis>.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Go to the <emphasis>Arguments</emphasis> tab and enter
+ <emphasis role="bold">-Xmx256m</emphasis> in the <emphasis>VM
+ arguments</emphasis> field to increase the maximum heap size of
+ the new Eclipse workbench.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Start the new Eclipse workbench by clicking the <emphasis
+ role="bold">Run</emphasis> button.</simpara>
+ </listitem>
+ </itemizedlist> <figure id="new_config">
+ <title>Setting up a new Eclipse workbench to test the DSL
+ plug-ins</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/4a_new_run_config.png" scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/4a_new_run_config.png" />
+ </imageobject>
+ </mediaobject>
+ </figure> <figure id="new_eclipse_app">
+ <title>Creating a new Eclipse run configuration</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/4b_new_eclipse_application.png"
+ scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/4b_new_eclipse_application.png" />
+ </imageobject>
+ </mediaobject>
+ </figure> <figure id="increase_heapsize">
+ <title>Increasing maximum heap size</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/4c_increase_heap_memory.png"
+ scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/4c_increase_heap_memory.png" />
+ </imageobject>
+ </mediaobject>
+ </figure></para>
+ </section>
+
+ <section id="exploring_the_editor">
+ <title>Taking it for a spin</title>
+
+ <para>You should now see the same workspace as before. To check out the
+ DSL editor, create a new <emphasis>mydsl</emphasis> project and model in
+ the runtime instance:</para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>Select <emphasis role="bold">File > New... > Other...
+ > mydsl Project</emphasis> to create a new
+ <emphasis>mydsl</emphasis> project.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Click <emphasis role="bold">Next</emphasis> to proceed to
+ the next wizard page.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Leave the project name as is (it should read
+ <emphasis>mydslproject</emphasis>) and click <emphasis
+ role="bold">Finish</emphasis> to create the project.</simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>The wizard will now create a new project for you, including an
+ empty sample model.</para>
+
+ <para>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 <keycombo>
+ <keycap>CTRL</keycap>
+
+ <keycap>Space</keycap>
+ </keycombo>.</para>
+
+ <programlisting>
datatype String
datatype String
@@ -434,84 +468,91 @@
String city
}
</programlisting>
- <para>
- Xtext-based editors support a number of features right out of the box:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Syntax coloring
- </para>
- </listitem>
- <listitem>
- <para>
- Code completion (press
- <keycombo><keycap>CTRL</keycap><keycap>Space</keycap></keycombo> to
- invoke)
- </para>
- </listitem>
- <listitem>
- <para>
- Navigation (either by holding the <keycap>CTRL</keycap> key and
- left-clicking an identifier or by pressing the <keycap>F3</keycap> key
- when the cursor is on an identifier)
- </para>
- </listitem>
- <listitem>
- <para>
- Find References (place the cursor on an identifier and press
- <keycombo><keycap>CTRL</keycap><keycap>SHIFT</keycap><keycap>G</keycap></keycombo>)
- </para>
- </listitem>
- <listitem>
- <para>
- Folding
- </para>
- </listitem>
- <listitem>
- <para>
- Outline
- </para>
- </listitem>
- <listitem>
- <para>
- Quick Outline (press <keycombo><keycap>CTRL</keycap><keycap>O</keycap></keycombo>)
- </para>
- </listitem>
- <listitem>
- <para>
- Syntax checking / Error markers
- </para>
- </listitem>
- </itemizedlist>
- <para>
- 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.
- </para>
- </section>
- </section>
- <section id="refining_the_dsl">
- <title>Refining the DSL</title>
- <para>
- 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.
- </para>
- <section id="adjusting_code_completion">
- <title>Adjusting code completion</title>
- <para>
- 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 <varname>datatype</varname> grammar rule?
- </para>
- <para>
- To do so, open <filename>my.dsl.editor/src/org.example.dsl/ContentAssist.ext</filename>
- and insert the following lines at the end of the file:
- </para>
- <programlisting>
+
+ <para>Xtext-based editors support a number of features right out of the
+ box:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Syntax coloring</para>
+ </listitem>
+
+ <listitem>
+ <para>Code completion (press <keycombo>
+ <keycap>CTRL</keycap>
+
+ <keycap>Space</keycap>
+ </keycombo> to invoke)</para>
+ </listitem>
+
+ <listitem>
+ <para>Navigation (either by holding the <keycap>CTRL</keycap> key
+ and left-clicking an identifier or by pressing the
+ <keycap>F3</keycap> key when the cursor is on an identifier)</para>
+ </listitem>
+
+ <listitem>
+ <para>Find References (place the cursor on an identifier and press
+ <keycombo>
+ <keycap>CTRL</keycap>
+
+ <keycap>SHIFT</keycap>
+
+ <keycap>G</keycap>
+ </keycombo>)</para>
+ </listitem>
+
+ <listitem>
+ <para>Folding</para>
+ </listitem>
+
+ <listitem>
+ <para>Outline</para>
+ </listitem>
+
+ <listitem>
+ <para>Quick Outline (press <keycombo>
+ <keycap>CTRL</keycap>
+
+ <keycap>O</keycap>
+ </keycombo>)</para>
+ </listitem>
+
+ <listitem>
+ <para>Syntax checking / Error markers</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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.</para>
+ </section>
+ </section>
+
+ <section id="refining_the_dsl">
+ <title>Refining the DSL</title>
+
+ <para>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.</para>
+
+ <section id="adjusting_code_completion">
+ <title>Adjusting code completion</title>
+
+ <para>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
+ <varname>datatype</varname> grammar rule?</para>
+
+ <para>To do so, open
+ <filename>my.dsl.editor/src/org.example.dsl/ContentAssist.ext</filename>
+ and insert the following lines at the end of the file:</para>
+
+ <programlisting>
/* proposals for Feature DataType::name */
List[Proposal] completeDataType_name<co id="extension.name" />(emf::EObject ctx, String prefix) :
{
@@ -522,100 +563,104 @@
newProposal("int")
};
</programlisting>
- <calloutlist>
- <callout arearefs="extension.name">
- <para>
- The name of he extension function must match the following rule:
- <emphasis role="bold">complete<name of the metatype>_<name of the attribute to be completed></emphasis>.
- In this sample, the extension function will be invoked as soon as the user
- requests content assist for the name of a <emphasis role="bold">DataType</emphasis>.
- </para>
- </callout>
- </calloutlist>
- <para>
- After saving the extension file, the DSL editor display the new proposals:
- </para>
- <figure id="enhanced_CA">
- <title>Enhanced content assist in action</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/7_enhanced_CA.png"
- scale="60" />
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/7_enhanced_CA.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section id="refining_checks">
- <title>Defining constraints for your model</title>
- <para>
- 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.
- </para>
- <para>
- The <emphasis>Check</emphasis> language from the openArchitectuerWare stack can be
- used to define constraints that ensure the validity of your models.
- </para>
- <para>
- 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 <filename>my.dsl/src/org.example.dsl/Checks.chk</filename>
- and add the following contraint to the end of the file:
- </para>
- <programlisting>
+
+ <calloutlist>
+ <callout arearefs="extension.name">
+ <para>The name of he extension function must match the following
+ rule: <emphasis role="bold">complete<name of the
+ metatype>_<name of the attribute to be
+ completed></emphasis>. In this sample, the extension function
+ will be invoked as soon as the user requests content assist for the
+ name of a <emphasis role="bold">DataType</emphasis>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>After saving the extension file, the DSL editor display the new
+ proposals:</para>
+
+ <figure id="enhanced_CA">
+ <title>Enhanced content assist in action</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/7_enhanced_CA.png" scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/7_enhanced_CA.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section id="refining_checks">
+ <title>Defining constraints for your model</title>
+
+ <para>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.</para>
+
+ <para>The <emphasis>Check</emphasis> language from the
+ openArchitectuerWare stack can be used to define constraints that ensure
+ the validity of your models.</para>
+
+ <para>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
+ <filename>my.dsl/src/org.example.dsl/Checks.chk</filename> and add the
+ following contraint to the end of the file:</para>
+
+ <programlisting>
context Type ERROR "Duplicate type detected: " + this.name :
- allElements()<co id="allElements" />.typeSelect(Type)<co id="typeSelect"/>.select(e|e.name == this.name).size ==1;
+ allElements()<co id="allElements" />.typeSelect(Type)<co id="typeSelect" />.select(e|e.name == this.name).size ==1;
</programlisting>
- <para>
- This constraint basically means the following:
- <itemizedlist>
- <listitem>
- <para>
- From the collection of <emphasis>all model elements</emphasis>,
- </para>
- </listitem>
- <listitem>
- <para>
- select all elements that are of type <emphasis role="bold">Type</emphasis> (i.e, all
- <emphasis role="bold">DataTypes</emphasis> and all <emphasis role="bold">Entities</emphasis>).
- </para>
- </listitem>
- <listitem>
- <para>
- Of the resulting collection, select all elements whose name equals the
- name of the current <emphasis role="bold">Type</emphasis>.
- </para>
- </listitem>
- <listitem>
- <para>
- Finally, check whether the size of the resulting collection is exactly one (1).
- </para>
- </listitem>
- </itemizedlist>
- In other words: each model may only have exactly one <emphasis role="bold">Type</emphasis> with the same name.
- </para>
- <para>
- After saving the check file, the DSL editor now issues an error if you enter two
- types with the same name:
- </para>
- <figure id="constraint_validation">
- <title>Constraint fails on duplicate data types</title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/8_constraint_validation.png"
- scale="60" />
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/8_constraint_validation.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- </section>
-
- <section>
+
+ <para>This constraint basically means the following: <itemizedlist>
+ <listitem>
+ <para>From the collection of <emphasis>all model
+ elements</emphasis>,</para>
+ </listitem>
+
+ <listitem>
+ <para>select all elements that are of type <emphasis
+ role="bold">Type</emphasis> (i.e, all <emphasis
+ role="bold">DataTypes</emphasis> and all <emphasis
+ role="bold">Entities</emphasis>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Of the resulting collection, select all elements whose name
+ equals the name of the current <emphasis
+ role="bold">Type</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Finally, check whether the size of the resulting collection
+ is exactly one (1).</para>
+ </listitem>
+ </itemizedlist> In other words: each model may only have exactly one
+ <emphasis role="bold">Type</emphasis> with the same name.</para>
+
+ <para>After saving the check file, the DSL editor now issues an error if
+ you enter two types with the same name:</para>
+
+ <figure id="constraint_validation">
+ <title>Constraint fails on duplicate data types</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/8_constraint_validation.png" scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/8_constraint_validation.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+
+ <section>
<title>Generating code</title>
<para>Now, that we have a DSL, we may want to do something useful with it.
@@ -630,31 +675,30 @@
Translating a language at runtime is called interpretation (ignoring
special cases like just-in-time compilation here).</para>
- <para>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.</para>
+ <para>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.</para>
<section>
<title>Code generation with Xpand</title>
- <para>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. <emphasis role="bold">String</emphasis>). So, we do not
- need to care about mapping data types.</para>
+ <para>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. <emphasis
+ role="bold">String</emphasis>). So, we do not need to care about mapping
+ data types.</para>
- <para>So just open the Xpand template (<emphasis role="bold">Main.xpt</emphasis>)
- and modify it like this:</para>
+ <para>So just open the Xpand template (<emphasis
+ role="bold">Main.xpt</emphasis>) and modify it like this:</para>
<figure id="xtext_tutorial_xpand_tenplate">
<title>Xpand template</title>
<mediaobject>
<imageobject role="fo">
- <imagedata fileref="images/9_xpand_template.png"
- scale="60" />
+ <imagedata fileref="images/9_xpand_template.png" scale="60" />
</imageobject>
<imageobject role="html">
@@ -663,144 +707,178 @@
</mediaobject>
</figure>
- <para>The definition <emphasis role="bold">main</emphasis> is invoked from the
- workflow file. It is declared for elements of type
- <emphasis role="bold">mydsl::Model</emphasis>, which corresponds to the root node
- of our DSL models. Within this definition, another definition
- (<emphasis role="bold">javaBean</emphasis>) is called (<emphasis role="bold">«EXPAND
- javaBean...»</emphasis>) for each model element
- (<emphasis role="bold">...FOREACH...</emphasis>) contained in the reference
- '<emphasis role="bold">types</emphasis>' of <emphasis role="bold">Model</emphasis>
- which is of type <emphasis role="bold">Entity</emphasis>.
- (<emphasis role="bold">typeSelect(Entity)</emphasis>).</para>
+ <para>The definition <emphasis role="bold">main</emphasis> is invoked
+ from the workflow file. It is declared for elements of type <emphasis
+ role="bold">mydsl::Model</emphasis>, which corresponds to the root node
+ of our DSL models. Within this definition, another definition (<emphasis
+ role="bold">javaBean</emphasis>) is called (<emphasis
+ role="bold">«EXPAND javaBean...»</emphasis>) for each model element
+ (<emphasis role="bold">...FOREACH...</emphasis>) contained in the
+ reference '<emphasis role="bold">types</emphasis>' of <emphasis
+ role="bold">Model</emphasis> which is of type <emphasis
+ role="bold">Entity</emphasis>. (<emphasis
+ role="bold">typeSelect(Entity)</emphasis>).</para>
- <para>The definition <emphasis role="bold">javaBean</emphasis> is declared for
- elements of type <emphasis role="bold">Entity</emphasis>. 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 '<filename>.java</filename>'. It is going to be generated
- into the <filename>src-gen</filename> directory directly.</para>
+ <para>The definition <emphasis role="bold">javaBean</emphasis> is
+ declared for elements of type <emphasis role="bold">Entity</emphasis>.
+ 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 '<filename>.java</filename>'. It is
+ going to be generated into the <filename>src-gen</filename> directory
+ directly.</para>
- <para>All text contained between <emphasis role="bold">«FILE ...»</emphasis> and
- <emphasis role="bold">«ENDFILE»</emphasis> will go to the new file.
- <emphasis>Xpand</emphasis> provides control statements
- (<emphasis role="bold">FOR</emphasis>, <emphasis role="bold">IF</emphasis>,
- <emphasis role="bold">ELSEIF</emphasis>, ...), as well as evaluation of expression, in
- order to create the desired code. See the openArchitectureWare reference
- documentation for details.</para>
-
+ <para>All text contained between <emphasis role="bold">«FILE
+ ...»</emphasis> and <emphasis role="bold">«ENDFILE»</emphasis> will go
+ to the new file. <emphasis>Xpand</emphasis> provides control statements
+ (<emphasis role="bold">FOR</emphasis>, <emphasis
+ role="bold">IF</emphasis>, <emphasis role="bold">ELSEIF</emphasis>,
+ ...), as well as evaluation of expression, in order to create the
+ desired code. See the openArchitectureWare reference documentation for
+ details.</para>
+
<para>To see our template in action, we have to run the code generator:
- <itemizedlist>
- <listitem>
- <para>
- Locate the oAW workflow file <emphasis>mydslproject.oaw</emphasis> in
- your <emphasis>mydslproject</emphasis> plug-in.
- </para>
- </listitem>
- <listitem>
- <para>
- Right-click on it and choose
- <emphasis role="bold">Run as > oAW Workflow</emphasis> from the context
- menu.
- </para>
- </listitem>
- <listitem>
- <para>
- You can see the generator running and logging into the
- <emphasis>Console</emphasis> view.
- </para>
- </listitem>
- <listitem>
- <para>
- The result will be stored in a new source folder
- <emphasis>src-gen</emphasis> in the <emphasis>mydslproject</emphasis>
- project.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
+ <itemizedlist>
+ <listitem>
+ <para>Locate the oAW workflow file
+ <emphasis>mydslproject.oaw</emphasis> in your
+ <emphasis>mydslproject</emphasis> plug-in.</para>
+ </listitem>
+
+ <listitem>
+ <para>Right-click on it and choose <emphasis role="bold">Run as
+ > oAW Workflow</emphasis> from the context menu.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can see the generator running and logging into the
+ <emphasis>Console</emphasis> view.</para>
+ </listitem>
+
+ <listitem>
+ <para>The result will be stored in a new source folder
+ <emphasis>src-gen</emphasis> in the
+ <emphasis>mydslproject</emphasis> project.</para>
+ </listitem>
+ </itemizedlist></para>
</section>
</section>
-
+
+ <section id="deploying_the_editor">
+ <title>Deploying the Editor</title>
+
+ <para>If you have finished customizing the generator and the editor, you
+ can deploy the DSL plug-ins to an Eclipse installation. For simplicity, we
+ take the one we are already running. <itemizedlist>
+ <listitem>
+ <simpara>Choose <emphasis role="bold">Export... > Deployable
+ plug-ins and fragments...</emphasis></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>The <emphasis>Export</emphasis> dialog appears. Select the
+ three DSL plug-ins.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Enter the path to your Eclipse installation. Make sure the
+ selected directory contains the Eclipse executable and a folder
+ named <emphasis>plugins</emphasis>. Usually, the directory is called
+ <emphasis>eclipse</emphasis>.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Choose <emphasis role="bold">Finish</emphasis>.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Restart Eclipse.</simpara>
+ </listitem>
+ </itemizedlist> <figure id="deploy_plugins">
+ <title>Deployment of the DSL plug-ins</title>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/5_deploy_plugins.png" scale="60" />
+ </imageobject>
+
+ <imageobject role="html">
+ <imagedata fileref="images/5_deploy_plugins.png" />
+ </imageobject>
+ </mediaobject>
+ </figure></para>
+ </section>
+
<section>
- <title>Where to go from here...</title>
- <para>
- This tutorial ends here, but there is a lot more to know about Xtext, Xpand, DSLs and EMP, e.g.
- <itemizedlist>
- <listitem>
- <simpara>
- Advanced model customization: References to elements outside the model,
- configurable linking of cross-references, etc.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Further customizing of the editor: Choosing font styles, defining multiple
- outline views etc.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Integration with the Eclipse Modeling Framework (EMF), and thereby opening
- to the whole world of eclipse modeling.
- </simpara>
- </listitem>
- </itemizedlist>
- Please consult the openArchitectureWare reference documentation
- <xref linkend="oaw_reference_documentation"/> for further information.
- </para>
+ <title>Where to go from here...</title>
+
+ <para>This tutorial ends here, but there is a lot more to know about
+ Xtext, Xpand, DSLs and EMP, e.g. <itemizedlist>
+ <listitem>
+ <simpara>Advanced model customization: References to elements
+ outside the model, configurable linking of cross-references,
+ etc.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Further customizing of the editor: Choosing font styles,
+ defining multiple outline views etc.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Integration with the Eclipse Modeling Framework (EMF), and
+ thereby opening to the whole world of eclipse modeling.</simpara>
+ </listitem>
+ </itemizedlist> Please consult the openArchitectureWare reference
+ documentation <xref linkend="oaw_reference_documentation" /> for further
+ information.</para>
</section>
<bibliography>
- <title>Resources</title>
- <biblioentry id="java_download">
- <title>Sun's Java SDK</title>
- <bibliosource>
- <ulink url="http://java.sun.com/javase/downloads/index.jsp">
- http://java.sun.com/javase/downloads/index.jsp
- </ulink>
- </bibliosource>
- </biblioentry>
- <biblioentry id="eclipse_europa">
- <title>Eclipse 3.3</title>
- <bibliosource>
- <ulink url="http://www.eclipse.org/europa/">
- http://www.eclipse.org/europa/
- </ulink>
- </bibliosource>
- </biblioentry>
- <biblioentry id="oaw_download">
- <title>openArchitectureWare download page</title>
- <bibliosource>
- <ulink url="http://www.eclipse.org/gmt/oaw/download/">
- http://www.eclipse.org/gmt/oaw/download/
- </ulink>
- </bibliosource>
- </biblioentry>
- <biblioentry id="oaw_update_site">
- <title>openArchitectureWare update site</title>
- <bibliosource>
- <ulink url="http://www.openarchitectureware.org/updatesite/milestone/site.xml">
- http://www.openarchitectureware.org/updatesite/milestone/site.xml
- </ulink>
- </bibliosource>
- </biblioentry>
- <biblioentry id="oaw_reference_documentation">
- <title>openArchitectureWare reference documentation</title>
- <bibliosource>
- <ulink url="http://www.eclipse.org/gmt/doc/">
- http://www.eclipse.org/gmt/doc/
- </ulink>
- </bibliosource>
- </biblioentry>
- <biblioentry id="solution">
- <title>Source code for the sample developed in this article</title>
- <bibliosource>
- <ulink url="solution/mydsl.zip">
- mydsl.zip
- </ulink>
- </bibliosource>
- </biblioentry>
- </bibliography>
+ <title>Resources</title>
+
+ <biblioentry id="java_download">
+ <title>Sun's Java SDK</title>
+
+ <bibliosource><ulink
+ url="http://java.sun.com/javase/downloads/index.jsp">
+ http://java.sun.com/javase/downloads/index.jsp </ulink></bibliosource>
+ </biblioentry>
+
+ <biblioentry id="eclipse_ganymede">
+ <title>Eclipse 3.4</title>
+
+ <bibliosource><ulink url="http://www.eclipse.org/ganymede/">
+ http://www.eclipse.org/ganymede/</ulink></bibliosource>
+ </biblioentry>
+
+ <biblioentry id="oaw_download">
+ <title>openArchitectureWare download page</title>
+
+ <bibliosource><ulink url="http://www.eclipse.org/gmt/oaw/download/">
+ http://www.eclipse.org/gmt/oaw/download/ </ulink></bibliosource>
+ </biblioentry>
+
+ <biblioentry id="oaw_update_site">
+ <title>openArchitectureWare update site</title>
+
+ <bibliosource><ulink
+ url="http://www.openarchitectureware.org/updatesite/milestone/site.xml">
+ http://www.openarchitectureware.org/updatesite/milestone/site.xml
+ </ulink></bibliosource>
+ </biblioentry>
+
+ <biblioentry id="oaw_reference_documentation">
+ <title>openArchitectureWare reference documentation</title>
+
+ <bibliosource><ulink url="http://www.eclipse.org/gmt/doc/">
+ http://www.eclipse.org/gmt/doc/ </ulink></bibliosource>
+ </biblioentry>
+
+ <biblioentry id="solution">
+ <title>Source code for the sample developed in this article</title>
+
+ <bibliosource><ulink url="solution/mydsl.zip"> mydsl.zip
+ </ulink></bibliosource>
+ </biblioentry>
+ </bibliography>
</article>
\ No newline at end of file
diff --git a/Article-BuildYourOwnDSL/images/4a_new_run_config.png b/Article-BuildYourOwnDSL/images/4a_new_run_config.png
new file mode 100644
index 0000000..bd1066b
--- /dev/null
+++ b/Article-BuildYourOwnDSL/images/4a_new_run_config.png
Binary files differ
diff --git a/Article-BuildYourOwnDSL/images/4b_new_eclipse_application.png b/Article-BuildYourOwnDSL/images/4b_new_eclipse_application.png
new file mode 100644
index 0000000..7b3d1b7
--- /dev/null
+++ b/Article-BuildYourOwnDSL/images/4b_new_eclipse_application.png
Binary files differ
diff --git a/Article-BuildYourOwnDSL/images/4c_increase_heap_memory.png b/Article-BuildYourOwnDSL/images/4c_increase_heap_memory.png
new file mode 100644
index 0000000..31712c5
--- /dev/null
+++ b/Article-BuildYourOwnDSL/images/4c_increase_heap_memory.png
Binary files differ
diff --git a/Article-BuildYourOwnDSL/index.html b/Article-BuildYourOwnDSL/index.html
index ff62fd0..8c94084 100644
--- a/Article-BuildYourOwnDSL/index.html
+++ b/Article-BuildYourOwnDSL/index.html
@@ -1,108 +1,66 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Build your own textual DSL with Tools from the Eclipse Modeling Project</title><link href="../article.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.71.1" name="generator"><meta name="description" content="Domain Specific Languages (DSLs) are a hot topic nowadays. While creating internal DSLs is no big deal, external DSLs have been said to be hard to create. In this tutorial we will show you how easy it is to create your own DSL with tools from the Eclipse Modeling Project (EMP) in less than one hour."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><h1>Build your own textual DSL with Tools from the Eclipse Modeling Project</h1><div class="summary"><h2>Summary</h2><p>
- Domain Specific Languages (DSLs) are a hot topic nowadays. While creating internal DSLs
- is no big deal, external DSLs have been said to be hard to create. In this
- tutorial we will show you how easy it is to create your own DSL with tools from the
- Eclipse Modeling Project (EMP) in less than one hour.
- </p><div class="author">
+<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Build your own textual DSL with Tools from the Eclipse Modeling Project</title><link href="../article.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.71.1" name="generator"><meta name="description" content="Domain Specific Languages (DSLs) are a hot topic nowadays. While creating internal DSLs is no big deal, external DSLs have been said to be hard to create. In this tutorial we will show you how easy it is to create your own DSL with tools from the Eclipse Modeling Project (EMP) in less than one hour."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><h1>Build your own textual DSL with Tools from the Eclipse Modeling
+ Project</h1><div class="summary"><h2>Summary</h2><p>Domain Specific Languages (DSLs) are a hot topic nowadays. While
+ creating internal DSLs is no big deal, external DSLs have been said to
+ be hard to create. In this tutorial we will show you how easy it is to
+ create your own DSL with tools from the Eclipse Modeling Project (EMP)
+ in less than one hour.</p><div class="author">
By
Peter Friese,
itemis AG<br>Sven Efftinge,
itemis AG<br>Jan Köhnlein,
itemis AG<br></div><div class="copyright">
Copyright ©
- 2008 itemis AG. All rights reserved.</div><div class="date"><span class="date">April 18, 2008<br></span></div></div><div class="content"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>
- The purpose of this tutorial is to illustrate the definition of external
- DSLs using tools from the Eclipse Modeling Project (EMP). The main focus is on the
- <span class="emphasis"><em>Xtext</em></span> framework. We will start by defining our own DSL in an
- <span class="emphasis"><em>Xtext</em></span> grammar. Then we will use the
- <span class="emphasis"><em>Xtext</em></span> framework to generate a parser, an
- <span class="emphasis"><em>Ecore-based</em></span>
- metamodel and a textual editor for Eclipse. Afterwards we will see how to refine
- the DSL and its editor by means of <span class="emphasis"><em>Xtend</em></span> extensions.
- Finally, we will learn how one can generate code out of textual models using the template
- language <span class="emphasis"><em>Xpand</em></span>.</p><p>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.
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="environment"></a>Setting up the Environment</h2></div></div></div><p>
- To follow this tutorial, you will need to install the following components
- <div class="itemizedlist"><ul type="disc"><li>
- A Java 5 or 6 SDK. Download it at
- [<a href="#java_download" title="[java_download]">1</a>]
- or use another SDK that suits your environment.
- </li><li>
- Eclipse SDK 3.3 (From the "Europa" release). You can download it from
- [<a href="#eclipse_europa" title="[eclipse_europa]">2</a>].
- Install by simply unpacking the archive.
- </li><li>
- openArchitectureWare 4.3. Download the ZIP file from
- [<a href="#oaw_download" title="[oaw_download]">3</a>]
- or point your eclipse update manager to
- [<a href="#oaw_update_site" title="[oaw_update_site]">4</a>].
- </li></ul></div>
- </p><p>
- The source code for the samples developed in this article can be downloaded from [<a href="#solution" title="[solution]">6</a>].
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="defininig_the_dsl"></a>Defining the DSL</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="creating_an_xtext_project"></a>Creating an Xtext Project</h3></div></div></div><p>
- 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.
- </p><p>
- To create a new Xtext project,
- <div class="itemizedlist"><ul type="disc"><li>
- Start up Eclipse 3.3 with oAW 4.3 installed
- (see <a href="#environment" title="Setting up the Environment">the section called “Setting up the Environment”</a>) in a fresh workspace and close the
- welcome screen
- </li><li>
- Select <span class="bold"><strong>File > New... > Project... Xtext Project</strong></span>
- </li><li>
- Specify the project settings in the wizard dialog. Since you started in a
- fresh workspace, the wizard should provide sensible defaults. See the
- Xtext reference documentation for a detailed overview of what all those
- settings mean.
- </li><li>
- Click <span class="bold"><strong>Finish</strong></span>
- </li></ul></div>
- </p><p>
- The wizard creates three projects, <code class="filename">my.dsl</code>,
- <code class="filename">my.dsl.editor</code>, and <code class="filename">my.dsl.generator</code>:
-
- <div class="itemizedlist"><ul type="disc"><li>
- <span class="bold"><strong>my.dsl</strong></span> is the language project, in which
- we will define the grammar for our DSL. After running the Xtext generator,
- this model also contains a parser for the DSL and a metamodel backing the
- language.
- </li><li>
- <span class="bold"><strong>my.dsl.editor</strong></span> will contain the DSL
- editor. Since we have not yet defined a grammar, this project is still
- empty. It will be filled by the Xtext generator later.
- </li><li>
- <span class="bold"><strong>my.dsl.generator</strong></span> contains an
- openArchitectureWare code generator skeleton. Later in this tutorial, you
- will write a couple of templates that process models created with your
- DSL editor.
- </li></ul></div>
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="defining_the_grammar"></a>Defining the Grammar</h3></div></div></div><p>
- Now that you have created a new Xtext project, you can define the grammar for
- your DSL. The grammar specifies the metamodel <span class="emphasis"><em>and</em></span> 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.
- </p><p>
- 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.
- </p><p>
- In this tutorial, we will develop a DSL for entities (since entities are something
- most developers know quite well).
- <div class="itemizedlist"><ul type="disc"><li>
- Open the Xtext grammar definition <code class="filename">my.dsl/src/mydsl.xtxt</code>
- </li><li>
- And type in the following grammar definition:
- </li></ul></div>
- </p><pre class="programlisting">
+ 2008 itemis AG. All rights reserved.</div><div class="date"><span class="date">April 18, 2008<br></span></div></div><div class="content"><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>The purpose of this tutorial is to illustrate the definition of
+ external DSLs using tools from the Eclipse Modeling Project (EMP). The
+ main focus is on the <span class="emphasis"><em>Xtext</em></span> framework. We will start
+ by defining our own DSL in an <span class="emphasis"><em>Xtext</em></span> grammar. Then we
+ will use the <span class="emphasis"><em>Xtext</em></span> framework to generate a parser, an
+ <span class="emphasis"><em>Ecore-based</em></span> metamodel and a textual editor for
+ Eclipse. Afterwards we will see how to refine the DSL and its editor by
+ means of <span class="emphasis"><em>Xtend</em></span> extensions. Finally, we will learn how
+ one can generate code out of textual models using the template language
+ <span class="emphasis"><em>Xpand</em></span>.</p><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="environment"></a>Setting up the Environment</h2></div></div></div><p>To follow this tutorial, you will need to install the following
+ components <div class="itemizedlist"><ul type="disc"><li>A Java 5 or 6 SDK. Download it at [<a href="#java_download" title="[java_download]">1</a>] or use another SDK that suits your
+ environment.</li><li>Eclipse SDK 3.4 (From the "Ganymede" release). You can
+ download it from [<a href="#eclipse_ganymede" title="[eclipse_ganymede]">2</a>]. Install by
+ simply unpacking the archive.</li><li>openArchitectureWare 4.3. Download the ZIP file from [<a href="#oaw_download" title="[oaw_download]">3</a>] or point your eclipse update manager to
+ [<a href="#oaw_update_site" title="[oaw_update_site]">4</a>].</li></ul></div></p><p>The source code for the samples developed in this article can be
+ downloaded from [<a href="#solution" title="[solution]">6</a>].</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="defininig_the_dsl"></a>Defining the DSL</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="creating_an_xtext_project"></a>Creating an Xtext Project</h3></div></div></div><p>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.</p><p>To create a new Xtext project, <div class="itemizedlist"><ul type="disc"><li>Start up Eclipse 3.4 with oAW 4.3 installed (see <a href="#environment" title="Setting up the Environment">the section called “Setting up the Environment”</a>) in a fresh workspace and close the
+ welcome screen</li><li>Select <span class="bold"><strong>File > New... >
+ Project... Xtext Project</strong></span></li><li>Specify the project settings in the wizard dialog. Since
+ you started in a fresh workspace, the wizard should provide
+ sensible defaults. See the Xtext reference documentation for a
+ detailed overview of what all those settings mean.</li><li>Click <span class="bold"><strong>Finish</strong></span></li></ul></div></p><p>The wizard creates three projects, <code class="filename">my.dsl</code>,
+ <code class="filename">my.dsl.editor</code>, and
+ <code class="filename">my.dsl.generator</code>: <div class="itemizedlist"><ul type="disc"><li><span class="bold"><strong>my.dsl</strong></span> is the language
+ project, in which we will define the grammar for our DSL. After
+ running the Xtext generator, this model also contains a parser for
+ the DSL and a metamodel backing the language.</li><li><span class="bold"><strong>my.dsl.editor</strong></span> will
+ contain the DSL editor. Since we have not yet defined a grammar,
+ this project is still empty. It will be filled by the Xtext
+ generator later.</li><li><span class="bold"><strong>my.dsl.generator</strong></span>
+ contains an openArchitectureWare code generator skeleton. Later in
+ this tutorial, you will write a couple of templates that process
+ models created with your DSL editor.</li></ul></div></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="defining_the_grammar"></a>Defining the Grammar</h3></div></div></div><p>Now that you have created a new Xtext project, you can define the
+ grammar for your DSL. The grammar specifies the metamodel
+ <span class="emphasis"><em>and</em></span> 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.</p><p>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.</p><p>In this tutorial, we will develop a DSL for entities (since
+ entities are something most developers know quite well). <div class="itemizedlist"><ul type="disc"><li>Open the Xtext grammar definition
+ <code class="filename">my.dsl/src/mydsl.xtxt</code></li><li>And type in the following grammar definition:</li></ul></div></p><pre class="programlisting">
Model:
(types+=Type)*; <a name="rule.model"></a><img border="0" alt="1" src="images/callouts/1.png">
@@ -119,78 +77,49 @@
Feature:
type=[Type|ID] name=ID; <a name="rule.feature"></a><img border="0" alt="5" src="images/callouts/5.png">
- </pre><div class="calloutlist"><table summary="Callout list" border="0"><tr><td align="left" valign="top" width="5%"><a href="#rule.model"><img border="0" alt="1" src="images/callouts/1.png"></a> </td><td align="left" valign="top"><p>
- The <span class="bold"><strong>Model</strong></span> rule specifies that a model contains
- zero or more <span class="bold"><strong>Types</strong></span>.
- </p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.type"><img border="0" alt="2" src="images/callouts/2.png"></a> </td><td align="left" valign="top"><p>
- The <span class="bold"><strong>Type</strong></span> rule is an abstract rule. It specifies
- that a <span class="bold"><strong>Type</strong></span> may either be a <span class="bold"><strong>DataType</strong></span>
- or an <span class="bold"><strong>Entity</strong></span>
- </p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.datatype"><img border="0" alt="3" src="images/callouts/3.png"></a> </td><td align="left" valign="top"><p>
- The <span class="bold"><strong>DataType</strong></span> rule specifies that a <span class="bold"><strong>DataType</strong></span>
- starts with the literal <span class="bold"><strong>datatype</strong></span>, 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).
- </p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.entity"><img border="0" alt="4" src="images/callouts/4.png"></a> </td><td align="left" valign="top"><p>
- The <span class="bold"><strong>Entity</strong></span> rule specifies that an <span class="bold"><strong>Entity</strong></span>
- starts with the literal <span class="bold"><strong>entity</strong></span>, 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 <span class="bold"><strong>Feature</strong></span>s.
- </p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.feature"><img border="0" alt="5" src="images/callouts/5.png"></a> </td><td align="left" valign="top"><p>
- A <span class="bold"><strong>Feature</strong></span> has a reference to a <span class="bold"><strong>Type</strong></span>
- and a name. The reference to <span class="bold"><strong>Type</strong></span> is particularly interesting,
- because by appending the <span class="emphasis"><em>|ID</em></span> modifier, we point out that
- the reference to <span class="bold"><strong>Type</strong></span> will be determined by an ID.
- </p></td></tr></table></div><p>
- Your grammar should now look like in <a href="#xtext_dsl_grammar" title="Figure 1. DSL grammar">Figure 1, “DSL grammar”</a>.
- </p><div class="figure"><a name="xtext_dsl_grammar"></a><p class="title"><b>Figure 1. DSL grammar</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/3_grammar.png" alt="DSL grammar"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="generating_the_dsl_editor"></a>Generating the DSL Editor</h3></div></div></div><p>
- Having specified the grammar, we can now generate the DSL editor.
- <div class="itemizedlist"><ul type="disc"><li>
- Right-click inside the Xtext grammar editor to open the context menu.
- </li><li>
- Select <span class="bold"><strong>Generate Xtext Artifacts</strong></span> to
- generate the DSL parser, the corresonding metamodel and, last but not
- least, the DSL editor.
- </li></ul></div>
- </p><div class="figure"><a name="generate_xtext_artifacts"></a><p class="title"><b>Figure 2. Generate Xtext artifacts</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/4_generate_xtext_artifacts.png" alt="Generate Xtext artifacts"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="running_the_editor"></a>Deploying and Running the Editor</h3></div></div></div><p>
- To run the generated editor, you have to deploy the DSL plug-ins to an Eclipse
- installation. For simplicity, we take the one we are already running.
- <div class="itemizedlist"><ul type="disc"><li>
- Choose <span class="bold"><strong>Export... > Deployable plug-ins and
- fragments...</strong></span>
- </li><li>
- The <span class="emphasis"><em>Export</em></span> dialog appears.
- Select the three DSL plug-ins.
- </li><li>
- Enter the path to your Eclipse installation. Make sure the selected
- directory contains the Eclipse executable and a folder named
- <span class="emphasis"><em>plugins</em></span>. Usually, the directory is called
- <span class="emphasis"><em>eclipse</em></span>.
- </li><li>
- Choose <span class="bold"><strong>Finish</strong></span>.
- </li><li>
- Restart Eclipse.
- </li></ul></div>
- <div class="figure"><a name="deploy_plugins"></a><p class="title"><b>Figure 3. Deployment of the DSL plug-ins</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/5_deploy_plugins.png" alt="Deployment of the DSL plug-ins"></div></div></div><br class="figure-break">
- </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="exploring_the_editor"></a>Taking it for a spin</h3></div></div></div><p>
- You should now see the same workspace as before. To check out the DSL editor, create
- a new <span class="emphasis"><em>mydsl</em></span> project and model in the runtime instance:
- </p><div class="itemizedlist"><ul type="disc"><li>
- Select <span class="bold"><strong>File > New... > Other... > mydsl
- Project</strong></span> to create a new <span class="emphasis"><em>mydsl</em></span> project.
- </li><li>
- Click <span class="bold"><strong>Next</strong></span> to proceed to the next wizard page.
- </li><li>
- Leave the project name as is (it should read <span class="emphasis"><em>mydslproject</em></span>)
- and click <span class="bold"><strong>Finish</strong></span> to create the project.
- </li></ul></div><p>
- The wizard will now create a new project for you, including an empty sample model.
- </p><p>
- 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 <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">Space</strong></span>.
- </p><pre class="programlisting">
+ </pre><div class="calloutlist"><table summary="Callout list" border="0"><tr><td align="left" valign="top" width="5%"><a href="#rule.model"><img border="0" alt="1" src="images/callouts/1.png"></a> </td><td align="left" valign="top"><p>The <span class="bold"><strong>Model</strong></span> rule specifies that
+ a model contains zero or more <span class="bold"><strong>Types</strong></span>.</p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.type"><img border="0" alt="2" src="images/callouts/2.png"></a> </td><td align="left" valign="top"><p>The <span class="bold"><strong>Type</strong></span> rule is an abstract
+ rule. It specifies that a <span class="bold"><strong>Type</strong></span> may
+ either be a <span class="bold"><strong>DataType</strong></span> or an
+ <span class="bold"><strong>Entity</strong></span></p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.datatype"><img border="0" alt="3" src="images/callouts/3.png"></a> </td><td align="left" valign="top"><p>The <span class="bold"><strong>DataType</strong></span> rule specifies
+ that a <span class="bold"><strong>DataType</strong></span> starts with the
+ literal <span class="bold"><strong>datatype</strong></span>, 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).</p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.entity"><img border="0" alt="4" src="images/callouts/4.png"></a> </td><td align="left" valign="top"><p>The <span class="bold"><strong>Entity</strong></span> rule specifies
+ that an <span class="bold"><strong>Entity</strong></span> starts with the
+ literal <span class="bold"><strong>entity</strong></span>, 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 <span class="bold"><strong>Feature</strong></span>s.</p></td></tr><tr><td align="left" valign="top" width="5%"><a href="#rule.feature"><img border="0" alt="5" src="images/callouts/5.png"></a> </td><td align="left" valign="top"><p>A <span class="bold"><strong>Feature</strong></span> has a reference to
+ a <span class="bold"><strong>Type</strong></span> and a name. The reference to
+ <span class="bold"><strong>Type</strong></span> is particularly interesting,
+ because by appending the <span class="emphasis"><em>|ID</em></span> modifier, we point
+ out that the reference to <span class="bold"><strong>Type</strong></span> will
+ be determined by an ID.</p></td></tr></table></div><p>Your grammar should now look like in <a href="#xtext_dsl_grammar" title="Figure 1. DSL grammar">Figure 1, “DSL grammar”</a>.</p><div class="figure"><a name="xtext_dsl_grammar"></a><p class="title"><b>Figure 1. DSL grammar</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/3_grammar.png" alt="DSL grammar"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="generating_the_dsl_editor"></a>Generating the DSL Editor</h3></div></div></div><p>Having specified the grammar, we can now generate the DSL editor.
+ <div class="itemizedlist"><ul type="disc"><li>Right-click inside the Xtext grammar editor to open the
+ context menu.</li><li>Select <span class="bold"><strong>Generate Xtext
+ Artifacts</strong></span> to generate the DSL parser, the corresonding
+ metamodel and, last but not least, the DSL editor.</li></ul></div></p><div class="figure"><a name="generate_xtext_artifacts"></a><p class="title"><b>Figure 2. Generate Xtext artifacts</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/4_generate_xtext_artifacts.png" alt="Generate Xtext artifacts"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="running_the_editor"></a>Running the Editor</h3></div></div></div><p>To run the generated editor, you have to start a new Eclipse
+ workbench with the DSL plug-ins enabled. <div class="itemizedlist"><ul type="disc"><li>Choose <span class="bold"><strong>Run -> Run
+ Configurations...</strong></span></li><li>The <span class="emphasis"><em>Run Configuraton</em></span> dialog appears.
+ Choose <span class="bold"><strong>New</strong></span> from the context menu
+ of <span class="bold"><strong>Eclipse Application</strong></span></li><li>Choose <span class="bold"><strong>New</strong></span> from the
+ context menu of <span class="bold"><strong>Eclipse
+ Application</strong></span>.</li><li>Go to the <span class="emphasis"><em>Arguments</em></span> tab and enter
+ <span class="bold"><strong>-Xmx256m</strong></span> in the <span class="emphasis"><em>VM
+ arguments</em></span> field to increase the maximum heap size of
+ the new Eclipse workbench.</li><li>Start the new Eclipse workbench by clicking the <span class="bold"><strong>Run</strong></span> button.</li></ul></div> <div class="figure"><a name="new_config"></a><p class="title"><b>Figure 3. Setting up a new Eclipse workbench to test the DSL
+ plug-ins</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/4a_new_run_config.png" alt="Setting up a new Eclipse workbench to test the DSL plug-ins"></div></div></div><br class="figure-break"> <div class="figure"><a name="new_eclipse_app"></a><p class="title"><b>Figure 4. Creating a new Eclipse run configuration</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/4b_new_eclipse_application.png" alt="Creating a new Eclipse run configuration"></div></div></div><br class="figure-break"> <div class="figure"><a name="increase_heapsize"></a><p class="title"><b>Figure 5. Increasing maximum heap size</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/4c_increase_heap_memory.png" alt="Increasing maximum heap size"></div></div></div><br class="figure-break"></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="exploring_the_editor"></a>Taking it for a spin</h3></div></div></div><p>You should now see the same workspace as before. To check out the
+ DSL editor, create a new <span class="emphasis"><em>mydsl</em></span> project and model in
+ the runtime instance:</p><div class="itemizedlist"><ul type="disc"><li>Select <span class="bold"><strong>File > New... > Other...
+ > mydsl Project</strong></span> to create a new
+ <span class="emphasis"><em>mydsl</em></span> project.</li><li>Click <span class="bold"><strong>Next</strong></span> to proceed to
+ the next wizard page.</li><li>Leave the project name as is (it should read
+ <span class="emphasis"><em>mydslproject</em></span>) and click <span class="bold"><strong>Finish</strong></span> to create the project.</li></ul></div><p>The wizard will now create a new project for you, including an
+ empty sample model.</p><p>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 <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">Space</strong></span>.</p><pre class="programlisting">
datatype String
datatype String
@@ -206,47 +135,24 @@
String zip
String city
}
- </pre><p>
- Xtext-based editors support a number of features right out of the box:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- Syntax coloring
- </p></li><li><p>
- Code completion (press
- <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">Space</strong></span> to
- invoke)
- </p></li><li><p>
- Navigation (either by holding the <span><strong class="keycap">CTRL</strong></span> key and
- left-clicking an identifier or by pressing the <span><strong class="keycap">F3</strong></span> key
- when the cursor is on an identifier)
- </p></li><li><p>
- Find References (place the cursor on an identifier and press
- <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">SHIFT</strong></span>-<span><strong class="keycap">G</strong></span>)
- </p></li><li><p>
- Folding
- </p></li><li><p>
- Outline
- </p></li><li><p>
- Quick Outline (press <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">O</strong></span>)
- </p></li><li><p>
- Syntax checking / Error markers
- </p></li></ul></div><p>
- 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.
- </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="refining_the_dsl"></a>Refining the DSL</h2></div></div></div><p>
- 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.
- </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="adjusting_code_completion"></a>Adjusting code completion</h3></div></div></div><p>
- 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 <code class="varname">datatype</code> grammar rule?
- </p><p>
- To do so, open <code class="filename">my.dsl.editor/src/org.example.dsl/ContentAssist.ext</code>
- and insert the following lines at the end of the file:
- </p><pre class="programlisting">
+ </pre><p>Xtext-based editors support a number of features right out of the
+ box:</p><div class="itemizedlist"><ul type="disc"><li><p>Syntax coloring</p></li><li><p>Code completion (press <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">Space</strong></span> to invoke)</p></li><li><p>Navigation (either by holding the <span><strong class="keycap">CTRL</strong></span> key
+ and left-clicking an identifier or by pressing the
+ <span><strong class="keycap">F3</strong></span> key when the cursor is on an identifier)</p></li><li><p>Find References (place the cursor on an identifier and press
+ <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">SHIFT</strong></span>-<span><strong class="keycap">G</strong></span>)</p></li><li><p>Folding</p></li><li><p>Outline</p></li><li><p>Quick Outline (press <span><strong class="keycap">CTRL</strong></span>-<span><strong class="keycap">O</strong></span>)</p></li><li><p>Syntax checking / Error markers</p></li></ul></div><p>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.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="refining_the_dsl"></a>Refining the DSL</h2></div></div></div><p>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.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="adjusting_code_completion"></a>Adjusting code completion</h3></div></div></div><p>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
+ <code class="varname">datatype</code> grammar rule?</p><p>To do so, open
+ <code class="filename">my.dsl.editor/src/org.example.dsl/ContentAssist.ext</code>
+ and insert the following lines at the end of the file:</p><pre class="programlisting">
/* proposals for Feature DataType::name */
List[Proposal] completeDataType_name<a name="extension.name"></a><img border="0" alt="1" src="images/callouts/1.png">(emf::EObject ctx, String prefix) :
{
@@ -256,45 +162,29 @@
newProposal("Long"),
newProposal("int")
};
- </pre><div class="calloutlist"><table summary="Callout list" border="0"><tr><td align="left" valign="top" width="5%"><a href="#extension.name"><img border="0" alt="1" src="images/callouts/1.png"></a> </td><td align="left" valign="top"><p>
- The name of he extension function must match the following rule:
- <span class="bold"><strong>complete<name of the metatype>_<name of the attribute to be completed></strong></span>.
- In this sample, the extension function will be invoked as soon as the user
- requests content assist for the name of a <span class="bold"><strong>DataType</strong></span>.
- </p></td></tr></table></div><p>
- After saving the extension file, the DSL editor display the new proposals:
- </p><div class="figure"><a name="enhanced_CA"></a><p class="title"><b>Figure 4. Enhanced content assist in action</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/7_enhanced_CA.png" alt="Enhanced content assist in action"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="refining_checks"></a>Defining constraints for your model</h3></div></div></div><p>
- 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.
- </p><p>
- The <span class="emphasis"><em>Check</em></span> language from the openArchitectuerWare stack can be
- used to define constraints that ensure the validity of your models.
- </p><p>
- 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 <code class="filename">my.dsl/src/org.example.dsl/Checks.chk</code>
- and add the following contraint to the end of the file:
- </p><pre class="programlisting">
+ </pre><div class="calloutlist"><table summary="Callout list" border="0"><tr><td align="left" valign="top" width="5%"><a href="#extension.name"><img border="0" alt="1" src="images/callouts/1.png"></a> </td><td align="left" valign="top"><p>The name of he extension function must match the following
+ rule: <span class="bold"><strong>complete<name of the
+ metatype>_<name of the attribute to be
+ completed></strong></span>. In this sample, the extension function
+ will be invoked as soon as the user requests content assist for the
+ name of a <span class="bold"><strong>DataType</strong></span>.</p></td></tr></table></div><p>After saving the extension file, the DSL editor display the new
+ proposals:</p><div class="figure"><a name="enhanced_CA"></a><p class="title"><b>Figure 6. Enhanced content assist in action</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/7_enhanced_CA.png" alt="Enhanced content assist in action"></div></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="refining_checks"></a>Defining constraints for your model</h3></div></div></div><p>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.</p><p>The <span class="emphasis"><em>Check</em></span> language from the
+ openArchitectuerWare stack can be used to define constraints that ensure
+ the validity of your models.</p><p>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
+ <code class="filename">my.dsl/src/org.example.dsl/Checks.chk</code> and add the
+ following contraint to the end of the file:</p><pre class="programlisting">
context Type ERROR "Duplicate type detected: " + this.name :
allElements()<a name="allElements"></a><img border="0" alt="1" src="images/callouts/1.png">.typeSelect(Type)<a name="typeSelect"></a><img border="0" alt="2" src="images/callouts/2.png">.select(e|e.name == this.name).size ==1;
- </pre><p>
- This constraint basically means the following:
- <div class="itemizedlist"><ul type="disc"><li><p>
- From the collection of <span class="emphasis"><em>all model elements</em></span>,
- </p></li><li><p>
- select all elements that are of type <span class="bold"><strong>Type</strong></span> (i.e, all
- <span class="bold"><strong>DataTypes</strong></span> and all <span class="bold"><strong>Entities</strong></span>).
- </p></li><li><p>
- Of the resulting collection, select all elements whose name equals the
- name of the current <span class="bold"><strong>Type</strong></span>.
- </p></li><li><p>
- Finally, check whether the size of the resulting collection is exactly one (1).
- </p></li></ul></div>
- In other words: each model may only have exactly one <span class="bold"><strong>Type</strong></span> with the same name.
- </p><p>
- After saving the check file, the DSL editor now issues an error if you enter two
- types with the same name:
- </p><div class="figure"><a name="constraint_validation"></a><p class="title"><b>Figure 5. Constraint fails on duplicate data types</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/8_constraint_validation.png" alt="Constraint fails on duplicate data types"></div></div></div><br class="figure-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N102CF"></a>Generating code</h2></div></div></div><p>Now, that we have a DSL, we may want to do something useful with it.
+ </pre><p>This constraint basically means the following: <div class="itemizedlist"><ul type="disc"><li><p>From the collection of <span class="emphasis"><em>all model
+ elements</em></span>,</p></li><li><p>select all elements that are of type <span class="bold"><strong>Type</strong></span> (i.e, all <span class="bold"><strong>DataTypes</strong></span> and all <span class="bold"><strong>Entities</strong></span>).</p></li><li><p>Of the resulting collection, select all elements whose name
+ equals the name of the current <span class="bold"><strong>Type</strong></span>.</p></li><li><p>Finally, check whether the size of the resulting collection
+ is exactly one (1).</p></li></ul></div> In other words: each model may only have exactly one
+ <span class="bold"><strong>Type</strong></span> with the same name.</p><p>After saving the check file, the DSL editor now issues an error if
+ you enter two types with the same name:</p><div class="figure"><a name="constraint_validation"></a><p class="title"><b>Figure 7. Constraint fails on duplicate data types</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/8_constraint_validation.png" alt="Constraint fails on duplicate data types"></div></div></div><br class="figure-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N102F4"></a>Generating code</h2></div></div></div><p>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
@@ -304,98 +194,61 @@
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).</p><p>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.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102D6"></a>Code generation with Xpand</h3></div></div></div><p>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. <span class="bold"><strong>String</strong></span>). So, we do not
- need to care about mapping data types.</p><p>So just open the Xpand template (<span class="bold"><strong>Main.xpt</strong></span>)
- and modify it like this:</p><div class="figure"><a name="xtext_tutorial_xpand_tenplate"></a><p class="title"><b>Figure 6. Xpand template</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/9_xpand_template.png" alt="Xpand template"></div></div></div><br class="figure-break"><p>The definition <span class="bold"><strong>main</strong></span> is invoked from the
- workflow file. It is declared for elements of type
- <span class="bold"><strong>mydsl::Model</strong></span>, which corresponds to the root node
- of our DSL models. Within this definition, another definition
- (<span class="bold"><strong>javaBean</strong></span>) is called (<span class="bold"><strong>«EXPAND
- javaBean...»</strong></span>) for each model element
- (<span class="bold"><strong>...FOREACH...</strong></span>) contained in the reference
- '<span class="bold"><strong>types</strong></span>' of <span class="bold"><strong>Model</strong></span>
- which is of type <span class="bold"><strong>Entity</strong></span>.
- (<span class="bold"><strong>typeSelect(Entity)</strong></span>).</p><p>The definition <span class="bold"><strong>javaBean</strong></span> is declared for
- elements of type <span class="bold"><strong>Entity</strong></span>. 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 '<code class="filename">.java</code>'. It is going to be generated
- into the <code class="filename">src-gen</code> directory directly.</p><p>All text contained between <span class="bold"><strong>«FILE ...»</strong></span> and
- <span class="bold"><strong>«ENDFILE»</strong></span> will go to the new file.
- <span class="emphasis"><em>Xpand</em></span> provides control statements
- (<span class="bold"><strong>FOR</strong></span>, <span class="bold"><strong>IF</strong></span>,
- <span class="bold"><strong>ELSEIF</strong></span>, ...), as well as evaluation of expression, in
- order to create the desired code. See the openArchitectureWare reference
- documentation for details.</p><p>To see our template in action, we have to run the code generator:
- <div class="itemizedlist"><ul type="disc"><li><p>
- Locate the oAW workflow file <span class="emphasis"><em>mydslproject.oaw</em></span> in
- your <span class="emphasis"><em>mydslproject</em></span> plug-in.
- </p></li><li><p>
- Right-click on it and choose
- <span class="bold"><strong>Run as > oAW Workflow</strong></span> from the context
- menu.
- </p></li><li><p>
- You can see the generator running and logging into the
- <span class="emphasis"><em>Console</em></span> view.
- </p></li><li><p>
- The result will be stored in a new source folder
- <span class="emphasis"><em>src-gen</em></span> in the <span class="emphasis"><em>mydslproject</em></span>
- project.
- </p></li></ul></div>
- </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10368"></a>Where to go from here...</h2></div></div></div><p>
- This tutorial ends here, but there is a lot more to know about Xtext, Xpand, DSLs and EMP, e.g.
- <div class="itemizedlist"><ul type="disc"><li>
- Advanced model customization: References to elements outside the model,
- configurable linking of cross-references, etc.
- </li><li>
- Further customizing of the editor: Choosing font styles, defining multiple
- outline views etc.
- </li><li>
- Integration with the Eclipse Modeling Framework (EMF), and thereby opening
- to the whole world of eclipse modeling.
- </li></ul></div>
- Please consult the openArchitectureWare reference documentation
- [<a href="#oaw_reference_documentation" title="[oaw_reference_documentation]">5</a>] for further information.
- </p></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="N1037B"></a>Resources</h2></div></div></div><div class="biblioentry"><a name="java_download"></a><p>[1] <span class="title"><i>Sun's Java SDK</i>. </span><span class="bibliosource">
- <a href="http://java.sun.com/javase/downloads/index.jsp" target="_new">
- http://java.sun.com/javase/downloads/index.jsp
- </a>
- . </span></p></div><div class="biblioentry"><a name="eclipse_europa"></a><p>[2] <span class="title"><i>Eclipse 3.3</i>. </span><span class="bibliosource">
- <a href="http://www.eclipse.org/europa/" target="_new">
- http://www.eclipse.org/europa/
- </a>
- . </span></p></div><div class="biblioentry"><a name="oaw_download"></a><p>[3] <span class="title"><i>openArchitectureWare download page</i>. </span><span class="bibliosource">
- <a href="http://www.eclipse.org/gmt/oaw/download/" target="_new">
- http://www.eclipse.org/gmt/oaw/download/
- </a>
- . </span></p></div><div class="biblioentry"><a name="oaw_update_site"></a><p>[4] <span class="title"><i>openArchitectureWare update site</i>. </span><span class="bibliosource">
- <a href="http://www.openarchitectureware.org/updatesite/milestone/site.xml" target="_new">
- http://www.openarchitectureware.org/updatesite/milestone/site.xml
- </a>
- . </span></p></div><div class="biblioentry"><a name="oaw_reference_documentation"></a><p>[5] <span class="title"><i>openArchitectureWare reference documentation</i>. </span><span class="bibliosource">
- <a href="http://www.eclipse.org/gmt/doc/" target="_new">
- http://www.eclipse.org/gmt/doc/
- </a>
- . </span></p></div><div class="biblioentry"><a name="solution"></a><p>[6] <span class="title"><i>Source code for the sample developed in this article</i>. </span><span class="bibliosource">
- <a href="solution/mydsl.zip" target="_new">
- mydsl.zip
- </a>
- . </span></p></div></div><div class="notices"><h3>Legal Notices</h3><p>
- Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United
- States, other countries, or both.
- </p><p>
- Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
- </p><p>
- Microsoft is a trademark of Microsoft Corporation in the United States, other countries, or both.
- </p><p>
- UNIX is a registered trademark of The Open Group in the United States and other countries.
- </p><p>
- Other company, product, or service names may be trademarks or service marks of others.
- </p></div></div><div class="content"></div></body></html>
\ No newline at end of file
+ special cases like just-in-time compilation here).</p><p>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.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102FB"></a>Code generation with Xpand</h3></div></div></div><p>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. <span class="bold"><strong>String</strong></span>). So, we do not need to care about mapping
+ data types.</p><p>So just open the Xpand template (<span class="bold"><strong>Main.xpt</strong></span>) and modify it like this:</p><div class="figure"><a name="xtext_tutorial_xpand_tenplate"></a><p class="title"><b>Figure 8. Xpand template</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/9_xpand_template.png" alt="Xpand template"></div></div></div><br class="figure-break"><p>The definition <span class="bold"><strong>main</strong></span> is invoked
+ from the workflow file. It is declared for elements of type <span class="bold"><strong>mydsl::Model</strong></span>, which corresponds to the root node
+ of our DSL models. Within this definition, another definition (<span class="bold"><strong>javaBean</strong></span>) is called (<span class="bold"><strong>«EXPAND javaBean...»</strong></span>) for each model element
+ (<span class="bold"><strong>...FOREACH...</strong></span>) contained in the
+ reference '<span class="bold"><strong>types</strong></span>' of <span class="bold"><strong>Model</strong></span> which is of type <span class="bold"><strong>Entity</strong></span>. (<span class="bold"><strong>typeSelect(Entity)</strong></span>).</p><p>The definition <span class="bold"><strong>javaBean</strong></span> is
+ declared for elements of type <span class="bold"><strong>Entity</strong></span>.
+ 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 '<code class="filename">.java</code>'. It is
+ going to be generated into the <code class="filename">src-gen</code> directory
+ directly.</p><p>All text contained between <span class="bold"><strong>«FILE
+ ...»</strong></span> and <span class="bold"><strong>«ENDFILE»</strong></span> will go
+ to the new file. <span class="emphasis"><em>Xpand</em></span> provides control statements
+ (<span class="bold"><strong>FOR</strong></span>, <span class="bold"><strong>IF</strong></span>, <span class="bold"><strong>ELSEIF</strong></span>,
+ ...), as well as evaluation of expression, in order to create the
+ desired code. See the openArchitectureWare reference documentation for
+ details.</p><p>To see our template in action, we have to run the code generator:
+ <div class="itemizedlist"><ul type="disc"><li><p>Locate the oAW workflow file
+ <span class="emphasis"><em>mydslproject.oaw</em></span> in your
+ <span class="emphasis"><em>mydslproject</em></span> plug-in.</p></li><li><p>Right-click on it and choose <span class="bold"><strong>Run as
+ > oAW Workflow</strong></span> from the context menu.</p></li><li><p>You can see the generator running and logging into the
+ <span class="emphasis"><em>Console</em></span> view.</p></li><li><p>The result will be stored in a new source folder
+ <span class="emphasis"><em>src-gen</em></span> in the
+ <span class="emphasis"><em>mydslproject</em></span> project.</p></li></ul></div></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="deploying_the_editor"></a>Deploying the Editor</h2></div></div></div><p>If you have finished customizing the generator and the editor, you
+ can deploy the DSL plug-ins to an Eclipse installation. For simplicity, we
+ take the one we are already running. <div class="itemizedlist"><ul type="disc"><li>Choose <span class="bold"><strong>Export... > Deployable
+ plug-ins and fragments...</strong></span></li><li>The <span class="emphasis"><em>Export</em></span> dialog appears. Select the
+ three DSL plug-ins.</li><li>Enter the path to your Eclipse installation. Make sure the
+ selected directory contains the Eclipse executable and a folder
+ named <span class="emphasis"><em>plugins</em></span>. Usually, the directory is called
+ <span class="emphasis"><em>eclipse</em></span>.</li><li>Choose <span class="bold"><strong>Finish</strong></span>.</li><li>Restart Eclipse.</li></ul></div> <div class="figure"><a name="deploy_plugins"></a><p class="title"><b>Figure 9. Deployment of the DSL plug-ins</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/5_deploy_plugins.png" alt="Deployment of the DSL plug-ins"></div></div></div><br class="figure-break"></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N103C2"></a>Where to go from here...</h2></div></div></div><p>This tutorial ends here, but there is a lot more to know about
+ Xtext, Xpand, DSLs and EMP, e.g. <div class="itemizedlist"><ul type="disc"><li>Advanced model customization: References to elements
+ outside the model, configurable linking of cross-references,
+ etc.</li><li>Further customizing of the editor: Choosing font styles,
+ defining multiple outline views etc.</li><li>Integration with the Eclipse Modeling Framework (EMF), and
+ thereby opening to the whole world of eclipse modeling.</li></ul></div> Please consult the openArchitectureWare reference
+ documentation [<a href="#oaw_reference_documentation" title="[oaw_reference_documentation]">5</a>] for further
+ information.</p></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="N103D5"></a>Resources</h2></div></div></div><div class="biblioentry"><a name="java_download"></a><p>[1] <span class="title"><i>Sun's Java SDK</i>. </span><span class="bibliosource"><a href="http://java.sun.com/javase/downloads/index.jsp" target="_new">
+ http://java.sun.com/javase/downloads/index.jsp </a>. </span></p></div><div class="biblioentry"><a name="eclipse_ganymede"></a><p>[2] <span class="title"><i>Eclipse 3.4</i>. </span><span class="bibliosource"><a href="http://www.eclipse.org/ganymede/" target="_new">
+ http://www.eclipse.org/ganymede/</a>. </span></p></div><div class="biblioentry"><a name="oaw_download"></a><p>[3] <span class="title"><i>openArchitectureWare download page</i>. </span><span class="bibliosource"><a href="http://www.eclipse.org/gmt/oaw/download/" target="_new">
+ http://www.eclipse.org/gmt/oaw/download/ </a>. </span></p></div><div class="biblioentry"><a name="oaw_update_site"></a><p>[4] <span class="title"><i>openArchitectureWare update site</i>. </span><span class="bibliosource"><a href="http://www.openarchitectureware.org/updatesite/milestone/site.xml" target="_new">
+ http://www.openarchitectureware.org/updatesite/milestone/site.xml
+ </a>. </span></p></div><div class="biblioentry"><a name="oaw_reference_documentation"></a><p>[5] <span class="title"><i>openArchitectureWare reference documentation</i>. </span><span class="bibliosource"><a href="http://www.eclipse.org/gmt/doc/" target="_new">
+ http://www.eclipse.org/gmt/doc/ </a>. </span></p></div><div class="biblioentry"><a name="solution"></a><p>[6] <span class="title"><i>Source code for the sample developed in this article</i>. </span><span class="bibliosource"><a href="solution/mydsl.zip" target="_new"> mydsl.zip
+ </a>. </span></p></div></div><div class="notices"><h3>Legal Notices</h3><p>Java and all Java-based trademarks are trademarks of Sun
+ Microsystems, Inc. in the United States, other countries, or
+ both.</p><p>Linux is a trademark of Linus Torvalds in the United States, other
+ countries, or both.</p><p>Microsoft is a trademark of Microsoft Corporation in the United
+ States, other countries, or both.</p><p>UNIX is a registered trademark of The Open Group in the United
+ States and other countries.</p><p>Other company, product, or service names may be trademarks or
+ service marks of others.</p></div></div><div class="content"></div></body></html>
\ No newline at end of file
