Google Git
Sign in
eclipse / www.eclipse.org / Xtext / 63ddf9522fe521b2cbd1c117d9b37bb6c58d4bb4 / . / documentation / 301_grammarlanguage.html
blob: fe8c9ff31e2fc3213962e1ef3aa7432510e8017b [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Xtext - The Grammar Language</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description"
content="The website of Eclipse Xtext, an open-source framework for development of programming languages and domain-specific languages">
<meta name="author" content="Sven Efftinge">
<meta name="author" content="Miro Spoenemann">
<!-- styles -->
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- Le fav and touch icons -->
<link rel="shortcut icon" href="/Xtext/images/favicon.png">
<link href="/Xtext/css/bootstrap.css" rel="stylesheet" type='text/css'>
<link href="/Xtext/css/bootstrap-responsive.css" rel="stylesheet" type='text/css'>
<link href="/Xtext/css/shield-responsive.css" rel="stylesheet" type='text/css'>
<link href='/Xtext/css/fonts.css' rel='stylesheet' type='text/css'>
<link href="/Xtext/css/prettyPhoto.css" rel="stylesheet" media="screen" type='text/css'>
<link href="/Xtext/css/prettify.css" type="text/css" rel="stylesheet"/>
<link href="/Xtext/css/style.css" rel="stylesheet" type='text/css'>
<!-- cover flow -->
<link href="/Xtext/css/coverflow.css" rel="stylesheet" type='text/css'>
<!--[if lt IE 9]>
<link href="/css/iebugs.css" rel="stylesheet" type='text/css'>
<![endif]-->
<!-- BEGIN Cookie Consent
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.0.3/cookieconsent.min.css" />
<script src="//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.0.3/cookieconsent.min.js"></script>
<script>
window.addEventListener("load", function(){
window.cookieconsent.initialise({
"palette": {
"popup": {
"background": "#000"
},
"button": {
"background": "#f1d600"
}
},
"theme": "edgeless",
"type": "opt-in",
onInitialise: function (status) {
var type = this.options.type;
var didConsent = this.hasConsented();
if (type == 'opt-in' && didConsent) {
// TODO: enable cookies
}
if (type == 'opt-out' && !didConsent) {
// TODO: disable cookies
}
},
onStatusChange: function(status, chosenBefore) {
var type = this.options.type;
var didConsent = this.hasConsented();
if (type == 'opt-in' && didConsent) {
// TODO: enable cookies
}
if (type == 'opt-out' && !didConsent) {
// TODO: disable cookies
}
},
onRevokeChoice: function() {
var type = this.options.type;
if (type == 'opt-in') {
// TODO: disable cookies
}
if (type == 'opt-out') {
// TODO: enable cookies
}
},
"content": {
"href": "http://www.eclipse.org/legal/privacy.php"
}
})});
</script>
END Cookie Consent -->
</head>
<body>
<header class="site-header">
<!-- Navbar -->
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse"
data-target=".nav-collapse"> <span class="icon-bar"></span> <span
class="icon-bar"></span> <span class="icon-bar"></span>
</a> <a class="brand" href="/Xtext/index.html"></a>
<div class="nav-collapse collapse" style="height: 0px;">
<ul class="nav">
<!--li ><a href="/Xtext/news.html">News</a></li-->
<li ><a href="/Xtext/download.html">Download</a></li>
<li ><a href="/Xtext/documentation/index.html">Documentation</a></li>
<li ><a href="/Xtext/community.html">Community</a></li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Support &amp; Trainings<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="https://www.itemis.com/en/xtext/support-and-team/" target="_blank">itemis</a></li>
<li><a href="https://typefox.io/trainings-2" target="_blank">TypeFox</a></li>
</ul>
</li>
<li ><a href="http://xtend-lang.org">Xtend</a></li>
</ul>
<!--div class="nav pull-right">
<li ><a><iframe src="https://ghbtns.com/github-btn.html?user=eclipse&repo=xtext&type=star&count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe></a></li>
</div-->
</div>
<!--/.nav-collapse -->
</div>
</div>
</div>
<!-- Navbar End -->
</header>
<div class="page-content">
<script>
function startSearch(event) {
if (event.keyCode == 13) {
var q = 'site:eclipse.org/Xtext/documentation+' + event.target.value;
window.open('https://www.google.com/search?q=' + q, "_self");
}
}
</script>
<div class="wrapper">
<div id="page">
<div class="inner">
<div id="maincontainer" class="container">
<span class="edit-on-github pull-right">
<a href="https://github.com/eclipse/xtext/edit/website-published/xtext-website/documentation/301_grammarlanguage.md">Edit on Github</a>
</span>
<div class="span3" style="margin-left: 0px;">
<div class="search-bar">
<img src="/Xtext/images/search-gray.png"/>
<input type="search" id="google-search" onkeyup="startSearch(event);"/>
</div>
<ul id="nav-outline" style="margin-left: 0px;">
<li class="nav-part">Getting Started</li>
<li><a href="102_domainmodelwalkthrough.html">15 Minutes Tutorial</a></li>
<li><a href="103_domainmodelnextsteps.html">15 Minutes Tutorial - Extended</a></li>
<li><a href="104_jvmdomainmodel.html">Five simple steps to your JVM language</a></li>
<li class="nav-part">Reference Documentation</li>
<li><a href="301_grammarlanguage.html">The Grammar Language</a></li>
<li><a href="302_configuration.html">Configuration</a></li>
<li><a href="303_runtime_concepts.html">Language Implementation</a></li>
<li><a href="305_xbase.html">Integration with Java</a></li>
<li><a href="307_special_languages.html">Typical Language Configurations</a></li>
<li><a href="308_emf_integration.html">Integration with EMF</a></li>
<li><a href="310_eclipse_support.html">Eclipse Support</a></li>
<li><a href="330_web_support.html">Web Editor Support</a></li>
<li><a href="340_lsp_support.html">LSP Support</a></li>
<li><a href="350_continuous_integration.html">Continuous Integration</a></li>
</ul>
</div>
<div class="span8 doc-contents">
<h1 id="grammarLanguage">The Grammar Language</h1>
<p>The <a href="https://github.com/eclipse/xtext-core/blob/master/org.eclipse.xtext/src/org/eclipse/xtext/Xtext.xtext">grammar language</a> is the corner stone of Xtext. It is a domain-specific language, carefully designed for the description of textual languages. The main idea is to describe the concrete syntax and how it is mapped to an in-memory representation – the semantic model. This model will be created by the parser on-the-fly when it consumes an input file. Of course the Xtext grammar language itself is implemented with Xtext, so you will find parts of its syntax described with its own means in this documentation.</p>
<p>An example grammar is shown in the <a href="102_domainmodelwalkthrough.html#write-your-own-grammar">15 Minutes Tutorial</a>.</p>
<h2 id="syntax">The Syntax</h2>
<p>In the following the different concepts and syntactical constructs of the grammar language are explained.</p>
<h3 id="language-declaration">Language Declaration</h3>
<p>Each Xtext grammar starts with a header that defines some properties of the grammar.</p>
<pre><code class="language-xtext">grammar org.example.domainmodel.Domainmodel
with org.eclipse.xtext.common.Terminals
</code></pre>
<p>The first line declares the name of the language. Xtext leverages Java’s class path mechanism. This means that the name can be any valid Java qualifier. The grammar file name needs to correspond to the language name and have the file extension <code>.xtext</code>. This means that the name has to be e.g. <em>Domainmodel.xtext</em> and must be placed in a package <em>org.example.domainmodel</em> on your project’s class path. In other words, your <code>.xtext</code> file has to reside in a Java source folder to be valid.</p>
<p>The second aspect that can be deduced from the first line of the grammar is its relationship to other languages. An Xtext grammar can declare another existing grammar to be reused. The mechanism is called <a href="301_grammarlanguage.html#grammar-mixins">grammar mixin</a>.</p>
<h3 id="package-declarations">EPackage Declarations</h3>
<p>Xtext parsers create in-memory object graphs while consuming text. Such object-graphs are instances of <a href="https://www.eclipse.org/modeling/emf/">EMF</a> Ecore models. An Ecore model basically consists of an EPackage containing EClasses, EDataTypes and EEnums (see the <a href="308_emf_integration.html#model-metamodel">section on EMF</a> for more details) and describes the structure of the instantiated objects. Xtext can infer Ecore models from a grammar (see <a href="301_grammarlanguage.html#metamodel-inference">Ecore model inference</a>) but it is also possible to import existing Ecore models. You can even mix both approaches and use multiple existing Ecore models and infer some others from a single grammar. This allows for easy reuse of existing abstractions while still having the advantage of short turnarounds with derived Ecore models.</p>
<h4 id="epackage-generation">EPackage Generation</h4>
<p>The easiest way to get started is to let Xtext infer the Ecore model from your grammar. The <code>generate</code> declaration in the grammar advises the framework to do so:</p>
<pre><code class="language-xtext">generate domainmodel "http://www.example.org/domainmodel/Domainmodel"
</code></pre>
<p>That statement could actually be read as: generate an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EPackage.java">EPackage</a> with the <em>name</em> <code>domainmodel</code> and the <em>nsURI</em> <code>"http://www.example.org/domainmodel/Domainmodel"</code>. Xtext will then add <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClasses</a> with <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EAttribute.java">EAttributes</a> and <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EReference.java">EReferences</a> for the different parser rules in your grammar, as described in <a href="301_grammarlanguage.html#metamodel-inference">Ecore model inference</a>.</p>
<h4 id="epackage-import">EPackage Import</h4>
<p>If you already have an existing EPackage, you can import it using its namespace URI:</p>
<pre><code class="language-xtext">import "http://www.xtext.org/example/Domainmodel"
</code></pre>
<p>A <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.common/src/org/eclipse/emf/common/util/URI.java">URI</a> (Uniform Resource Identifier) provides a simple and extensible means for identifying an abstract or physical resource. It is also possible to import EPackages using resource URIs, but it is strongly recommended to use the namespace URI instead because it is independent from the concrete location in the file system, much more portable across different machines, easier to configure in the workflow, and works better with language mixins. The import via platform URIs or file URIs can be considered deprecated and is only supported for backwards compatibility.</p>
<p>Using package imports usually requires some <a href="302_configuration.html#importing-metamodels">adaptations in the generator workflow</a>.</p>
<h4 id="ecore-model-aliases-for-epackages">Ecore Model Aliases for EPackages</h4>
<p>If you want to use multiple EPackages you need to specify aliases in the following way:</p>
<pre><code class="language-xtext">import "http://www.xtext.org/example/Domainmodel" as dmodel
import 'http://www.eclipse.org/anotherPackage' as another
</code></pre>
<p>When referring to a type somewhere in the grammar you need to qualify the reference using that alias (e.g. <code>another::SomeType</code>). Cases where such type references occur are explained below.</p>
<p>It is also supported to put multiple EPackage imports into one alias. This is no problem as long as there are not any two <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClassifier.java">EClassifiers</a> with the same name. In that case none of them can be referenced. It is even possible to <code>import</code> multiple and <code>generate</code> one Ecore model and declare all of them with the same alias. If you do so, for a reference to an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClassifier.java">EClassifier</a> first the imported <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EPackage.java">EPackages</a> are scanned before it is assumed that a type needs to be generated into the inferred package.</p>
<p>Note that using the same alias for multiple EPackages is not recommended, because it might cause problems that are hard to track down. For instance, a reference to <code>classA</code> could mistakenly be linked to a newly created EClass instead of an existing EClass <code>ClassA</code> because the latter is written with a capital letter.</p>
<h3 id="terminal-rules">Terminal Rules</h3>
<p>Basically parsing can be separated in the following phases:</p>
<ol>
<li>Lexing</li>
<li>Parsing</li>
<li>Linking</li>
<li>Validation</li>
</ol>
<p>In the first stage called <em>lexing</em>, a sequence of characters (the text input) is transformed into a sequence of so-called <em>tokens</em>. In this context, a token is a sort of a strongly typed part or region of the input sequence. It consists of one or more characters and is matched by a particular terminal rule or keyword and therefore represents an atomic symbol. Terminal rules are also referred to as <em>token rules</em> or <em>lexer rules</em>. There is an informal naming convention that names of terminal rules are all upper-case.</p>
<p>In the <a href="102_domainmodelwalkthrough.html">domainmodel tutorial</a> there are no explicitly defined terminal rules, since it only uses the <em>ID</em> rule which is inherited from the grammar <code>org.eclipse.xtext.common.Terminals</code> (see <a href="#common-terminals">Common Terminals</a>). Therein the <em>ID</em> rule is defined as follows:</p>
<pre><code class="language-xtext">terminal ID:
('^')?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*;
</code></pre>
<p>It says that a token <em>ID</em> starts with an optional <code>'^'</code> character (caret), followed by a letter <code>('a'..'z'|'A'..'Z')</code> or underscore <code>'_'</code> followed by any number of letters, underscores and numbers <code>('0'..'9')</code>.</p>
<p>The caret is used to escape an identifier if there are conflicts with existing keywords. It is removed by the <em>ID</em> rule’s <a href="303_runtime_concepts.html#value-converter">ValueConverter</a>.</p>
<p>This is the simplified formal definition of terminal rules:</p>
<pre><code class="language-xtext">TerminalRule:
'terminal' name=ID ('returns' type=TypeRef)? ':'
alternatives=TerminalAlternatives ';';
</code></pre>
<p>Note that <em>the order of the terminal rules is crucial for your grammar</em>, as they may shadow each other. This is especially important for newly introduced rules in connection with imported rules from used grammars.</p>
<p>It’s almost in any case recommended to use <a href="#datatype-rules">data type rules</a> instead. Let’s assume you want to add a rule to allow fully qualified names in addition to simple IDs. Since a qualified name with only one segment looks like a plain ID, you should implement it as a data type rule instead of adding another terminal rule. The same rule of thumb applies to floating point literals, too.</p>
<h4 id="return-types">Return Types</h4>
<p>Each terminal rule returns an atomic value (an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EDataType.java">EDataType</a>). By default, it’s assumed that an instance of <code>ecore::EString</code> should be returned. However, if you want to provide a different type you can specify it. For instance, the rule <em>INT</em> is defined as:</p>
<pre><code class="language-xtext">import "http://www.eclipse.org/emf/2002/Ecore" as ecore
//...
terminal INT returns ecore::EInt:
('0'..'9')+;
</code></pre>
<p>This means that the terminal rule <em>INT</em> returns instances of <code>ecore::EInt</code>. It is possible to define any kind of data type here, which just needs to be an instance of <code>ecore::EDataType</code>. In order to tell the framework how to convert the parsed string to a value of the declared data type, you need to provide your own implementation of the <a href="https://github.com/eclipse/xtext-core/blob/master/org.eclipse.xtext/src/org/eclipse/xtext/conversion/IValueConverterService.java">IValueConverterService</a> (see <a href="303_runtime_concepts.html#value-converter">Value Converter</a>). The value converter is also the service that allows to remove escape sequences or semantically unnecessary characters such as quotes from string literals or the caret symbol <code>'^'</code> from the identifiers.</p>
<h4 id="extended-backus-naur-form-expressions">Extended Backus-Naur Form Expressions</h4>
<p>Terminal rules are described using <em>Extended Backus-Naur Form</em>-like (EBNF) expressions. The different expressions are described in the following. Each of these expressions allows to define a cardinality. There are four different possible cardinalities:</p>
<ol>
<li>exactly one (the default, no operator)</li>
<li>zero or one (operator <code>?</code>)</li>
<li>zero or more (operator <code>*</code>)</li>
<li>one or more (operator <code>+</code>)</li>
</ol>
<h5 id="keywords">Keywords / Characters</h5>
<p>Keywords are a kind of terminal rule literals. The <em>ID</em> rule in <code>org.eclipse.xtext.common.Terminals</code> for instance starts with a keyword:</p>
<pre><code class="language-xtext">terminal ID:
'^'? ... ;
</code></pre>
<p>The question mark sets the cardinality to <em>zero or one</em> (i.e. optional) as explained above.</p>
<p>A keyword can have any length, e.g. <code>'entity'</code>, and contain arbitrary characters. The following standard Java notations for special characters are allowed: <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\b</code>, <code>\f</code> and the quoted unicode character notation, such as <code>\u123</code>.</p>
<h5 id="character-ranges">Character Ranges</h5>
<p>A character range can be declared using the <code>..</code> operator. Example:</p>
<pre><code class="language-xtext">terminal INT returns ecore::EInt:
('0'..'9')+;
</code></pre>
<p>In this case an <em>INT</em> is comprised of one or more (note the <code>+</code> operator) characters between (and including) <code>'0'</code> and <code>'9'</code>.</p>
<h5 id="wildcard">Wildcard</h5>
<p>If you want to allow any character you can simply write the wildcard operator <code>.</code> (dot). Example:</p>
<pre><code class="language-xtext">terminal FOO:
'f' . 'o';
</code></pre>
<p>The rule above would allow expressions like <code>foo</code>, <code>f0o</code> or even <code>f°o</code>.</p>
<h5 id="until-token">Until Token</h5>
<p>With the <em>until token</em> it is possible to state that everything should be consumed until a certain token occurs. The multi-line comment is implemented this way:</p>
<pre><code class="language-xtext">terminal ML_COMMENT:
'/*' -&gt; '*/';
</code></pre>
<p>This is the rule for Java-style comments that begin with <code>/*</code> and end with <code>*/</code>.</p>
<h5 id="negated-tokens">Negated Token</h5>
<p>All the tokens explained above can be inverted using a preceding exclamation mark:</p>
<pre><code class="language-xtext">terminal BETWEEN_HASHES:
'#' (!'#')* '#';
</code></pre>
<h5 id="rule-calls">Rule Calls</h5>
<p>Rules can refer to other rules. This is simply done by using the name of the rule to be called. We refer to this as <em>rule calls</em>. Rule calls in terminal rules can only point to terminal rules. Example:</p>
<pre><code class="language-xtext">terminal DOUBLE:
INT '.' INT;
</code></pre>
<p>Note: It is generally not a good idea to implement floating point literals with terminal rules. You should use <a href="#datatype-rules">data type rules</a> instead due to possible shadowing problems explained above.</p>
<h5 id="alternatives">Alternatives</h5>
<p>Alternatives allow to define multiple valid options in the input file. For instance, the white space rule uses alternatives like this:</p>
<pre><code class="language-xtext">terminal WS:
(' '|'\t'|'\r'|'\n')+;
</code></pre>
<p>That is a WS can be made of one or more white space characters (including <code>' ', '\t', '\r', '\n'</code>).</p>
<h5 id="groups">Groups</h5>
<p>Finally, if you put tokens one after another, the whole sequence is referred to as a group. Example:</p>
<pre><code class="language-xtext">terminal ASCII:
'0x' ('0'..'7') ('0'..'9'|'A'..'F');
</code></pre>
<p>This group has three elements <code>'0x'</code>, <code>('0'..'7')</code>, and <code>('0'..'9'|'A'..'F')</code>, which have to appear in this order.</p>
<h4 id="terminal-fragment">Terminal Fragments</h4>
<p>Since terminal rules are used in a stateless context, it’s not easily possible to reuse parts of their definition. Fragments solve this problem. They allow the same EBNF elements as terminal rules do but may not be consumed by the lexer. Instead, they have to be used by other terminal rules. This allows to extract repeating parts of a definition:</p>
<pre><code class="language-xtext">terminal fragment ESCAPED_CHAR:
'\\' ('n'|'t'|'r'|'\\');
terminal STRING:
'"' ( ESCAPED_CHAR | !('\\'|'"') )* '"' |
"'" ( ESCAPED_CHAR | !('\\'|"'") )* "'";
</code></pre>
<h4 id="eof">EOF – End Of File</h4>
<p>The <code>EOF</code> (End Of File) token may be used to describe that the end of the input stream is a valid situation at a certain point in a terminal rule. This allows to consume the complete remaining input of a file starting with a special delimiter.</p>
<p><code>terminal UNCLOSED_STRING : '"' (!'"')* EOF;</code></p>
<p>The <code>EOF</code> token cannot be <a href="301_grammarlanguage.html#negated-tokens">negated</a>.</p>
<h3 id="parser-rules">Parser Rules</h3>
<p>The parser is fed with a sequence of terminals and walks through the so-called <em>parser rules</em>. Hence a parser rule – contrary to a terminal rule – does not produce a single atomic terminal token, but a tree of non-terminal and terminal tokens. They lead to a so-called <em>parse tree</em> (in Xtext it is also referred as <em>node model</em>). Furthermore, parser rules are handled as kind of a building plan for the creation of the <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EObject.java">EObjects</a> that form the semantic model (the linked <em>abstract syntax tree</em> or AST). Due to this fact, parser rules are also called production or EObject rules. Different constructs like actions and assignments are used to derive types and initialize the semantic objects accordingly.</p>
<h4 id="extended-backus-naur-form-expressions-1">Extended Backus-Naur Form Expressions</h4>
<p>Not all the expressions that are available in terminal rules can be used in parser rules. Character ranges, wildcards, the until token and the negation as well as the EOF token are only available for terminal rules.</p>
<p>The elements that are available in parser rules as well as in terminal rules are</p>
<ol>
<li><a href="301_grammarlanguage.html#groups">Groups</a></li>
<li><a href="301_grammarlanguage.html#alternatives">Alternatives</a></li>
<li><a href="301_grammarlanguage.html#keywords">Keywords</a></li>
<li><a href="301_grammarlanguage.html#rule-calls">Rule Calls</a></li>
</ol>
<p>In addition to these elements, there are some expressions used to direct how the AST is constructed. They are listed and explained in the following.</p>
<h5 id="assignments">Assignments</h5>
<p>Assignments are used to assign the consumed information to a feature of the currently produced object. The type of the current object, its <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClass</a>, is specified by the return type of the parser rule. If it is not explicitly stated it is implied that the type’s name equals the rule’s name. The type of the assigned feature is inferred from the right hand side of the assignment.</p>
<p>Example:</p>
<pre><code class="language-xtext">DataType:
'datatype' name = ID;
</code></pre>
<p>The syntactic declaration for datatypes starts with a keyword <code>datatype</code> followed by an assignment: <code>name = ID</code>. The left hand side refers to a feature <em>name</em> of the current object (which has the EClass <em>DataType</em> in this case). The right hand side can be a rule call, a keyword, a <a href="301_grammarlanguage.html#cross-references">cross-reference</a> or an alternative comprised by the former options. The type of the feature needs to be compatible with the type of the expression on the right. As <em>ID</em> returns an <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">EString</a> in this case, the feature <em>name</em> needs to be of type EString as well.</p>
<p>There are three different assignment operators, each with different semantics.</p>
<ol>
<li>The simple equal sign <code>=</code> is the straightforward assignment, and is used for features which take only one element.</li>
<li>The <code>+=</code> sign (the add operator) expects a multi-valued feature and adds the value on the right hand side to that feature, which is a list feature.</li>
<li>The <code>?=</code> sign (boolean assignment operator) expects a feature of type <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html">EBoolean</a> and sets it to true if the right hand side was consumed, independently from the concrete value of the right hand side.</li>
</ol>
<p>The used assignment operator does not influence the cardinality of the expected symbols on the right hand side.</p>
<h5 id="cross-references">Cross-References</h5>
<p>A unique feature of Xtext is the ability to declare cross-references in the grammar. In traditional compiler construction such cross-references are not established during parsing but in a later linking phase. This is the same in Xtext, but we allow to specify cross-reference information in the grammar. This information is used by the <a href="303_runtime_concepts.html#linking">linker</a>.</p>
<p>The syntax for cross-references is:</p>
<pre><code class="language-xtext">CrossReference:
'[' type=TypeRef ('|' ^terminal=CrossReferenceableTerminal )? ']';
</code></pre>
<p>For example, Features in the <a href="102_domainmodelwalkthrough.html">domainmodel tutorial</a> contain a cross-reference pointing to a Type:</p>
<pre><code class="language-xtext">Feature:
(many ?= 'many')? name = ID ':' type = [Type];
</code></pre>
<p>It is important to understand that the text between the square brackets does not refer to another rule, but to an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClass</a> – which is a type and not a parser rule. This can be sometimes confusing because one usually uses the same name for the rules and for the returned types.</p>
<p>Looking at the syntax definition for cross-references, there is an optional part starting with a vertical bar (pipe) followed by <em>CrossReferenceableTerminal</em>. This is the part describing the concrete text from which the cross-reference should be established. If the terminal is omitted, it is expected to be the rule with the name <em>ID</em> – if one can be found. The terminal is mandatory for languages that do not define a rule with the name <em>ID</em>.</p>
<h5 id="unordered-groups">Unordered Groups</h5>
<p>The elements of an unordered group can occur in any order, but each element must appear once. Members of unordered groups are separated by <code>&amp;</code>. The following rule <code>Modifier</code> allows to parse simplified modifiers of the Java language:</p>
<pre><code class="language-xtext">Modifier:
static?='static'? &amp; final?='final'? &amp; visibility=Visibility;
enum Visibility:
PUBLIC='public' | PRIVATE='private' | PROTECTED='protected';
</code></pre>
<p>With these definitions the following sequences of tokens are valid:</p>
<pre><code class="language-java">public static final
static protected
final private static
public
</code></pre>
<p>In contrast, the parser refuses to accept these input lines:</p>
<pre><code class="language-java">static final static // ERROR: static appears twice
public static final private // ERROR: visibility appears twice
final // ERROR: visibility is missing
</code></pre>
<p>Note that if you want an element of an unordered group to appear once or not at all, you have to choose a cardinality of <code>?</code>. In the example, the visibility is mandatory, while <code>static</code> or <code>final</code> are optional. Elements with a cardinality of <code>*</code> or <code>+</code> have to appear continuously without interruption, i.e.</p>
<pre><code class="language-xtext">ExampleRule:
values+=INT* &amp; name=ID;
</code></pre>
<p>can parse these lines</p>
<pre><code class="language-java">0 8 15 x
x 0 8 15
</code></pre>
<p>but does not consume the following sequence without raising an error</p>
<pre><code class="language-java">0 x 8 15 // wrong, as values must not be interrupted by a name (ID)
</code></pre>
<h5 id="simple-actions">Simple Actions</h5>
<p>The object to be returned by a parser rule is usually created lazily on the first assignment. Its type is determined from the specified return type of the rule, which may have been inferred from the rule’s name if no explicit return type is specified.</p>
<p>With Actions however, the creation of returned <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EObject.java">EObject</a> can be made explicit. Xtext supports two kinds of Actions:</p>
<ol>
<li><em>Simple</em> Actions</li>
<li><em>Assigned</em> Actions</li>
</ol>
<p>If you want to enforce the creation of an instance with specific type you can use simple actions. In the following example <em>TypeB</em> must be a subtype of <em>TypeA</em>. An expression <code>A ident</code> should create an instance of <em>TypeA</em>, whereas <code>B ident</code> should instantiate <em>TypeB</em>.</p>
<p>If you don’t use actions, you’ll have to define an alternative and delegate rules to guide the parser to the right types for the to-be-instantiated objects:</p>
<pre><code class="language-xtext">MyRule returns TypeA:
"A" name=ID |
MyOtherRule;
MyOtherRule returns TypeB:
"B" name = ID;
</code></pre>
<p>Actions however allow to make this explicit. Thereby they can improve the readability of grammars.</p>
<pre><code class="language-xtext">MyRule returns TypeA:
"A" name=ID |
"B" {TypeB} name=ID;
</code></pre>
<p>Generally speaking, the instance is created as soon as the parser hits the first assignment. However, actions allow to explicitly instantiate any <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EObject.java">EObject</a>. The notation <code>{TypeB}</code> will create an instance of <em>TypeB</em> and assign it to the result of the parser rule. This allows to define parser rules without any assignment and to create objects without the need to introduce unnecessary delegate rules.</p>
<p>Note: If a parser rule does not instantiate any object because it does not contain an Action and no mandatory Assignment, you’ll likely end up with unexpected situations for valid input files. Xtext detects this situation and will raise a warning (with a corresponding quickfix) for the parser rules in question.</p>
<h5 id="unassigned-rule-calls">Unassigned Rule Calls</h5>
<p>We previously explained that the <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EObject.java">EObject</a> to be returned is created lazily when the first assignment occurs or as soon as a simple action is evaluated. There is another concept to find the EObject to be returned, called <em>unassigned rule call</em>. Unassigned rule calls, as the name suggests it, are rule calls to other parser rules which are not used within an assignment. The return value of the called rule becomes the return value of the calling parser rule if it is not assigned to a feature.</p>
<p>With unassigned rule calls one can, for instance, create rules which just dispatch to other rules:</p>
<pre><code class="language-xtext">AbstractToken:
TokenA |
TokenB |
TokenC;
</code></pre>
<p>As <code>AbstractToken</code> could possibly return an instance of <em>TokenA</em>, <em>TokenB</em> or <em>TokenC</em>. Its type must be a super type for all these types. Since the return value of the called rule becomes the result of the current rule, it is possible to further change the state of the AST element by assigning additional features.</p>
<p>Example:</p>
<pre><code class="language-xtext">AbstractToken:
( TokenA |
TokenB |
TokenC ) cardinality=('?'|'+'|'*')?;
</code></pre>
<p>This way the <em>cardinality</em> is optional (last question mark) and can be represented by a question mark, a plus, or an asterisk. It will be assigned to either an instance of type <em>TokenA</em>, <em>TokenB</em>, or <em>TokenC</em>, which are all subtypes of <em>AbstractToken</em>. The rule in this example will never create an instance of <em>AbstractToken</em> directly, but always return the instance that has been created by the invoked <em>TokenX</em> rule.</p>
<h5 id="grammar-actions">Assigned Actions</h5>
<p>Xtext leverages the powerful ANTLR parser which implements an <code>LL(*)</code> algorithm. Even though LL parsers have many advantages with respect to readability, debuggability and error recovery, there are also some drawbacks. The most important one is that it does not allow left recursive grammars. For instance, the following rule is not allowed in LL-based grammars, because <code>Expression '+' Expression</code> is left-recursive:</p>
<pre><code class="language-xtext">Expression:
Expression '+' Expression |
'(' Expression ')' |
INT;
</code></pre>
<p>Instead one has to rewrite such left-recursive rules by “left-factoring” them:</p>
<pre><code class="language-xtext">Expression:
TerminalExpression ('+' TerminalExpression)*;
TerminalExpression:
'(' Expression ')' |
INT;
</code></pre>
<p>In practice this is always the same pattern and therefore not too difficult. However, by simply applying the Xtext AST construction features we’ve covered so far, a grammar such as</p>
<pre><code class="language-xtext">Expression:
{Operation} left=TerminalExpression (ops+='+' rights+=TerminalExpression)*
TerminalExpression returns Expression:
'(' Expression ')' |
{IntLiteral} value=INT;
</code></pre>
<p>would result in unwanted elements in the AST. For instance the expression <code>(42)</code> would result in a tree like this:</p>
<pre><code class="language-mwe2">Operation {
left=Operation {
left=IntLiteral {
value=42
}
}
}
</code></pre>
<p>Typically one would only want to have one instance of <em>IntLiteral</em> instead. This problem can be solved by using a combination of unassigned rule calls and assigned actions:</p>
<pre><code class="language-xtext">Expression:
TerminalExpression ({Operation.left=current}
op='+' right=TerminalExpression)*
TerminalExpression returns Expression:
'(' Expression ')' |
{IntLiteral} value=INT;
</code></pre>
<p>In the example above <code>{Operation.left=current}</code> is a so-called <em>tree rewrite action</em>, which creates a new instance of the stated <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClass</a> <em>Operation</em> and assigns the element currently to-be-returned (the <code>current</code> variable) to a feature of the newly created object. The example uses the feature <em>left</em> of the <em>Operation</em> instance to store the previously returned <em>Expression</em>. In Java these semantics could be expressed as:</p>
<pre><code class="language-java">Operation temp = new Operation();
temp.setLeft(current);
current = temp;
</code></pre>
<p>With these improved rules the expression <code>(42)</code> would lead to a single <em>IntLiteral</em> instance, while <code>40 + 2</code> creates an <em>Operation</em> with two <em>IntLiterals</em>.</p>
<h4 id="syntactic-predicates">Syntactic Predicates</h4>
<p>It is sometimes not easily possible to define an <code>LL(*)</code> grammar for a given language that parses all possible valid input files and still produces abstract syntax graphs that mimic the actual structure of the files. There are even cases that cannot be described with an unambiguous grammar. There are solutions that allow to deal with this problem:</p>
<ul>
<li>Enable backtracking: Xtext allows to enable backtracking for the ANTLR parser generator. This is usually not recommended since it influences error message strategies at runtime and shadows actually existing problems in the grammar.</li>
<li>Syntactic predicates: The grammar language allows to guide the parser in case of ambiguities. This mechanism is achieved by <em>syntactic predicates</em>. Since they affect only a very small part of the grammar, syntactic predicates are the recommended approach to handle ANTLR error messages during the parser generation.</li>
</ul>
<p>The classical example for ambiguous language parts is the <em>dangling else problem</em>. A conditional in a programming language usually looks like this:</p>
<pre><code class="language-java">if (isTrue())
doStuff();
else
dontDoStuff();
</code></pre>
<p>The problems becomes obvious as soon as nested conditions are used:</p>
<pre><code class="language-java">if (isTrue())
if (isTrueAsWell())
doStuff();
else
dontDoStuff();
</code></pre>
<p>Where does the <code>else</code> branch belong to? This question can be answered by a quick look into the language specification which tells that the <code>else</code> branch is part of the inner condition. However, the parser generator cannot be convinced that easily. We have to guide it to this decision point by means of syntactic predicates which are expressed by a leading <code>=&gt;</code> operator.</p>
<pre><code class="language-xtext">Condition:
'if' '(' condition=BooleanExpression ')'
then=Expression
(=&gt;'else' else=Expression)?
</code></pre>
<p>The parser understands the predicate basically like this: If you are at this particular decision point and you don’t know what to do, check whether the <code>else</code> keyword is present. If it is, take that branch directly without considering other options that would match the same token sequence.</p>
<p>Well chosen predicates allow to solve most ambiguities and backtracking can often be disabled. Be warned, though, that an ambiguity for the parser can also mean an ambiguity for the user, so before forcing the syntax into handling such cases you should consider avoiding them in the first place.</p>
<h5 id="first-token-set-predicates">First Token Set Predicates</h5>
<p>Sometimes you need to put a syntactic predicate on a more complex rule, e.g. an expression, which might be very long. For disambiguation it is often sufficient to look only at the first token set. In those cases one can use the <code>-&gt;</code> operator instead of <code>=&gt;</code>, instructing the parser to just look at the first token and make the decision based on that. This can heavily reduce the lookahead and as a consequence make the parser faster and more robust to syntactic errors. This also affects the behavior of the IDE, such as content assist, in a positive way.</p>
<h3 id="hidden-terminals">Hidden Terminal Symbols</h3>
<p>Because parser rules describe not a single token, but a sequence of patterns in the input, it is necessary to define the important parts of the input. Xtext introduces the concept of hidden tokens to handle semantically irrelevant things like white spaces, comments, etc. in the input sequence gracefully. It is possible to define a set of terminal symbols that are hidden from the parser rules and automatically skipped when they are recognized. Nevertheless, they are transparently woven into the node model, but not relevant for the semantic model.</p>
<p>Hidden terminals may optionally appear between any other terminals in any cardinality. They can be described per rule or for the whole grammar. When <a href="301_grammarlanguage.html#grammar-mixins">reusing a single grammar</a> its definition of hidden tokens is reused, too. The grammar <code>org.eclipse.xtext.common.Terminals</code> comes with a reasonable default and hides all comments and white spaces from the parser rules.</p>
<p>If a rule defines hidden symbols, you can think of a kind of scope that is automatically introduced. Any rule that is called transitively by the declaring rule uses the same hidden terminals as the calling rule, unless it defines hidden tokens itself.</p>
<pre><code class="language-xtext">Person hidden(WS, ML_COMMENT, SL_COMMENT):
name=Fullname age=INT ';';
Fullname:
(firstname=ID)? lastname=ID;
</code></pre>
<p>The sample rule <em>Person</em> defines multiline comments (<code>ML_COMMENT</code>), single-line comments (<code>SL_COMMENT</code>), and white space (<code>WS</code>) to be allowed between the <em>name</em> and the <em>age</em>. Because the rule <em>Fullname</em> does not introduce an own set of hidden terminals, it allows the same symbols to appear between <em>firstname</em> and <em>lastname</em> as the calling rule <em>Person</em>. Thus, the following input is perfectly valid for the given grammar snippet:</p>
<pre><code class="language-java">John /* comment */ Smith // line comment
/* comment */
42 ; // line comment
</code></pre>
<p>A list of all default terminals such as <code>WS</code> can be found in <a href="#common-terminals">Common Terminals</a>.</p>
<h3 id="datatype-rules">Data Type Rules</h3>
<p>Data type rules create instances of <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EDataType.java">EDataType</a> instead of <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClass</a>. They are quite similar to terminal rules, but they are actually parser rules and are therefore</p>
<ol>
<li>context sensitive and</li>
<li>allow to use of hidden tokens.</li>
</ol>
<p>Assuming you want to define a rule to consume Java-like qualified names (e.g. <code>foo.bar.Baz</code>) you could write:</p>
<pre><code class="language-xtext">QualifiedName:
ID ('.' ID)*;
</code></pre>
<p>In contrast to a terminal rule this is only valid in certain contexts, i.e. it won’t conflict with the rule <em>ID</em>. If you had defined it as a terminal rule, it would possibly hide the simple <em>ID</em> rule.</p>
<p>In addition, by defining the <em>QualifiedName</em> as a data type rule, it is allowed to use hidden tokens such as <code>/* comment */</code> between the segment IDs and dots (e.g. <code>foo/* comment */. bar . Baz</code>).</p>
<p>Return types can be specified in the same way as for terminal rules:</p>
<pre><code class="language-xtext">QualifiedName returns ecore::EString:
ID ('.' ID)*;
</code></pre>
<p>Note that rules that do not call other parser rules and do neither contain any actions nor <a href="301_grammarlanguage.html#assignments">assignments</a> are considered to be data type rules, and the data type <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">EString</a> is implied if none has been explicitly declared.</p>
<p><a href="303_runtime_concepts.html#value-converter">Value converters</a> are used to transform the parsed string to the actually returned data type value.</p>
<h3 id="enum-rules">Enum Rules</h3>
<p>Enum rules return enumeration literals from strings. They can be seen as a shortcut for data type rules with specific value converters. The main advantage of enum rules is their simplicity, type safety and therefore nice validation. Furthermore it is possible to infer enums and their respective literals during the Ecore model transformation.</p>
<p>If you want to define a <code>ChangeKind</code> from <a href="https://github.com/eclipse/emf/blob/master/plugins/org.eclipse.emf.ecore.change/model/Change.ecore">org.eclipse.emf.ecore.change/model/Change.ecore</a> with <em>ADD</em>, <em>MOVE</em> and <em>REMOVE</em> you could write:</p>
<pre><code class="language-xtext">enum ChangeKind:
ADD | MOVE | REMOVE;
</code></pre>
<p>It is even possible to use alternative literals for your enums or reference an enum value twice:</p>
<pre><code class="language-xtext">enum ChangeKind:
ADD = 'add' | ADD = '+' |
MOVE = 'move' | MOVE = '-&gt;' |
REMOVE = 'remove' | REMOVE = '-';
</code></pre>
<p>Please note that Ecore does not support unset values for enums. If you define a grammar like</p>
<pre><code class="language-xtext">Element:
'element' name=ID (value=SomeEnum)?;
</code></pre>
<p>with the input of <code>element Foo</code> the resulting instance <em>Foo</em> will hold the enum value with the internal representation of <code>0</code> (zero). When generating the EPackage from your grammar this will be the first literal you define. As a workaround you could introduce a dedicated none-value or order the enums accordingly. Note that it is not possible to define an enum literal with an empty textual representation. You can overcome this by importing a meta model where the enum is defined and omitting some of its literals in the grammar.</p>
<h3 id="grammar-annotations">Grammar Annotations</h3>
<p>Parser Rules can be annotated with several useful annotations. In the following sections there is an overview. Please keep in mind that those annotations will only work on Parser Rules. You’ll get an error if you try to use them on Terminal or Enum Rules.</p>
<h4 id="override">Override</h4>
<p>Sometimes you want to override an existing Parser Rule of a given super grammar to customize it. To do that, you have to create a rule with the same name. It’s clear for you that this is a customization, but for the reader of the grammar it’s not. To make that more explicit <code>@Override</code> marks a rule as being a customization of an already existing rule in a super grammar. You’ll get a warning if a rule is a customization and is not marked as Override and an error if it’s not an customization and therefore must not be marked as Override.</p>
<h4 id="final">Final</h4>
<p>Overriding Parser Rules is a common thing but if you want to make sure that nobody overrides a special rule the <code>@Final</code> annotation gives support for that.</p>
<h4 id="deprecated">Deprecated</h4>
<p>Language evolution is an important part of building serious DSLs. Adding something to a grammar is easy as long as the old instances of the grammar are still valid to the new grammar. It becomes hard if you want to remove something and you have to be very careful. Marking classes as deprecated is a good indicator for users to switch to the new API. With <code>@Deprecated</code> Xtext has support to mark Parser Rules to be deprecated. <br />
This will generate validations and the possibility to change the severity through preferences. As a default users will get a warning when using these rules. Of course it’s up to you to decide what the severity should be - this opens the possibility to safely remove parts of the grammar by informing in advance with a warning and raise the severity to error afterwards.</p>
<h4 id="exported">Exported</h4>
<p>As a default all elements that have a name that are exposed through the index to be referenced from outside. As a start this might fit your needs, but sooner or later you might run out of memory (big index) or you simply want to hide elements from the outside world. To do that you can write a custom version of the <a href="https://github.com/eclipse/xtext-core/blob/master/org.eclipse.xtext/src/org/eclipse/xtext/resource/IDefaultResourceDescriptionStrategy.java">IDefaultResourceDescriptionStrategy</a> or simply use the <code>@Exported</code> annotation. This will generate a custom strategy as soon as there is at least one <code>@Exported</code> annotation in your grammar.</p>
<hr />
<h2 id="metamodel-inference">Ecore Model Inference</h2>
<p>The Ecore model (or meta-model) of a textual language describes the structure of its abstract syntax trees (AST).</p>
<p>Xtext uses Ecore’s EPackages to define Ecore models. Ecore models are declared to be either inferred from the grammar or imported. By using the <code>generate</code> directive, one tells Xtext to infer an EPackage from the grammar.</p>
<h3 id="type-and-package-generation">Type and Package Generation</h3>
<p>Xtext creates</p>
<ul>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EPackage.java">EPackage</a>
<ul>
<li>for each <code>generate</code> declaration. The <em>name</em> of the EPackage is set to the first parameter of such a declaration, its <em>nsURI</em> to the second parameter. An optional alias as the third parameter allows to distinguish the generated EPackages later. Only one generated package declaration per alias is allowed.</li>
</ul>
</li>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EClass.java">EClass</a>
<ul>
<li>for each return type of a parser rule. If a parser rule does not define a return type, an implicit one with the same name as the rule itself is assumed. You can specify multiple rules that return the same type, but only one EClass is generated for each type name.</li>
<li>for each type defined in an action or a cross-reference.</li>
</ul>
</li>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EEnum.java">EEnum</a>
<ul>
<li>for each return type of an enum rule.</li>
</ul>
</li>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EDataType.java">EDataType</a>
<ul>
<li>for each return type of a terminal rule or a data type rule.</li>
</ul>
</li>
</ul>
<p>All EClasses, EEnums, and EDataTypes are added to the EPackage referred to by the alias provided in the type reference they were created from.</p>
<h3 id="feature-and-type-hierarchy-generation">Feature and Type Hierarchy Generation</h3>
<p>While walking through the grammar, the model inference algorithm keeps track of a set of the currently possible return types to add features to.</p>
<ul>
<li>Entering a parser rule the set contains only the return type of the rule.</li>
<li>Entering an element of an alternative the set is reset to the same state it was in when entering the first option of the alternative.</li>
<li>Leaving an alternative the set contains the union of all types at the end of each of its paths.</li>
<li>After an optional element, the set is reset to the same state it was before entering it.</li>
<li>After a non-optional unassigned rule call the set contains only the return type of the called rule. An optional rule call does not modify the set. A rule call is optional if its cardinality is <code>?</code> or <code>*</code>.</li>
<li>After an action the set contains only the type of the action.</li>
</ul>
<p>While traversing the parser rules Xtext creates</p>
<ul>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EAttribute.java">EAttribute</a> in each current return type
<ul>
<li>of type <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html">EBoolean</a> for each feature assignment using the <code>?=</code> operator. No further EReferences or EAttributes are generated from such an assignment.</li>
<li>for each assignment with the <code>=</code> or <code>+=</code> operator calling a terminal rule or data type rule. Its type is the return type of the called rule.</li>
</ul>
</li>
<li>an <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EReference.java">EReference</a> in each current return type
<ul>
<li>for each assignment with the <code>=</code> or <code>+=</code> operator in a parser rule calling a parser rule. The type of the EReference is the return type of the called parser rule.</li>
<li>for each assigned action. The type of the reference is the return type of the current rule containing the action.</li>
</ul>
</li>
</ul>
<p>Each <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EAttribute.java">EAttribute</a> or <a href="https://github.com/eclipse/emf/blob/R2_9_0/plugins/org.eclipse.emf.ecore/src/org/eclipse/emf/ecore/EReference.java">EReference</a> takes its name from the assignment or action that caused it. Multiplicities are <code>0..1</code> for assignments with the <code>=</code> operator and <code>0..*</code> for assignments with the <code>+=</code> operator.</p>
<p>Furthermore, each type that is added to the currently possible return types automatically extends the current return type of the parser rule. You can specify additional common super types by means of “artificial” parser rules that are never called, e.g.</p>
<pre><code class="language-xtext">CommonSuperType:
SubTypeA | SubTypeB | SubTypeC;
</code></pre>
<p>After the traversal of all grammar rules the model inference algorithm examines all generated EClasses and lifts up similar features to supertypes if there is more than one subtype and the feature is defined in all subtypes. This works even for multiple super types.</p>
<h3 id="enum-literal-generation">Enum Literal Generation</h3>
<p>For each alternative defined in an enum rule, the transformer creates an enum literal, as long as no other literal with the same name can be found. The <em>literal</em> property of the generated enum literal is set to the right hand side of the declaration. If it is omitted, an enum literal with equal <em>name</em> and <em>literal</em> attributes is inferred.</p>
<pre><code class="language-xtext">enum MyGeneratedEnum:
NAME = 'literal' | EQUAL_NAME_AND_LITERAL;
</code></pre>
<h3 id="error-conditions">Error Conditions</h3>
<p>The following conditions cause an error</p>
<ul>
<li>An EAttribute or EReference has two different types or different cardinalities.</li>
<li>There is an EAttribute and an EReference with the same name in the same EClass.</li>
<li>There is a cycle in the type hierarchy.</li>
<li>A new EAttribute, EReference or super type is added to an imported type.</li>
<li>An EClass is added to an imported EPackage.</li>
<li>An undeclared alias is used.</li>
<li>An imported Ecore model cannot be loaded.</li>
</ul>
<hr />
<h2 id="grammar-mixins">Grammar Mixins</h2>
<p>Xtext supports the reuse of existing grammars. Grammars that are created via the Xtext wizard use <code>org.eclipse.xtext.common.Terminals</code> by default, which introduces a common set of terminal rules and defines reasonable defaults for hidden terminals.</p>
<pre><code class="language-xtext">grammar org.example.domainmodel.Domainmodel
with org.eclipse.xtext.common.Terminals
generate domainmodel "http://www.example.org/domainmodel/Domainmodel"
Model:
greetings+=Greeting*;
Greeting:
'Hello' name=ID '!';
</code></pre>
<p>To reuse an existing grammar, make sure the grammar file is on the classpath of the inheriting language. If it is in a different plug-in, make sure to add a plug-in dependency in the <code>MANIFEST.MF</code>.</p>
<p>Mixing another grammar into a language makes the rules defined in that grammar referable. It is also possible to overwrite rules from the used grammar. Example:</p>
<pre><code class="language-xtext">grammar my.SuperGrammar
generate super "http://my.org/super"
RuleA: 'a' stuff=RuleB;
RuleB: '{' name=ID '}';
</code></pre>
<pre><code class="language-xtext">grammar my.SubGrammar with my.SuperGrammar
import "http://my.org/super"
Model: (ruleAs+=RuleA)*;
// overrides my.SuperGrammar.RuleB
@Override
RuleB: '[' name=ID ']';
</code></pre>
<p>Declared terminal rules always get a higher priority than imported terminal rules.</p>
<h3 id="common-terminals">Common Terminals</h3>
<p>Xtext ships with a default set of predefined, reasonable and often required terminal rules. The grammar for these common terminal rules is defined as follows:</p>
<pre><code class="language-xtext">grammar org.eclipse.xtext.common.Terminals
hidden(WS, ML_COMMENT, SL_COMMENT)
import "http://www.eclipse.org/emf/2002/Ecore" as ecore
terminal ID:
'^'?('a'..'z'|'A'..'Z'|'_')('a'..'z'|'A'..'Z'|'_'|'0'..'9')*;
terminal INT returns ecore::EInt:
('0'..'9')+;
terminal STRING:
'"' ( '\\'('b'|'t'|'n'|'f'|'r'|'u'|'"'|"'"|'\\') | !('\\'|'"') )* '"' |
"'" ( '\\'('b'|'t'|'n'|'f'|'r'|'u'|'"'|"'"|'\\') | !('\\'|"'") )* "'";
terminal ML_COMMENT:
'/*' -&gt; '*/';
terminal SL_COMMENT:
'//' !('\n'|'\r')* ('\r'? '\n')?;
terminal WS:
(' '|'\t'|'\r'|'\n')+;
terminal ANY_OTHER:
.;
</code></pre>
<hr />
<p><strong><a href="302_configuration.html">Next Chapter: Configuration</a></strong></p>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="site-footer">
<div id="extra">
<div class="inner">
<div class="container">
<div class="row">
<div class="span6">
<h3 class="footer-links-header">Quick Links</h3>
<ul class="footer-links clearfix">
<li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
<li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
<li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
<li><a href="http://www.eclipse.org/legal/">Legal</a></li>
</ul>
<ul class="footer-links clearfix">
<li><a href="http://www.eclipse.org">Eclipse Home</a></li>
<li><a href="http://marketplace.eclipse.org/">Market Place</a></li>
<li><a href="http://www.planeteclipse.org/">Eclipse Planet</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/27/">Xtext Forum</a></li>
</ul>
</div>
<div class="span6">
<!-- Social Media Links -->
<h3 class="footer-links-header"">Social Media</h3>
<ul class="footer-links clearfix">
<li>
<a href="https://twitter.com/xtext"><img src="/Xtext/images/Twitter-bird-darkgray.png" class="img-responsive" style="margin-right: 5px;height: 1em;" alt="Twitter icon">@xtext on Twitter</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<a href="#" class="scrollup fadeOutRight animated" style="display: none;">ScrollUp</a>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="/Xtext/js/jquery-1.11.3.min.js"></script>
<script src="/Xtext/js/bootstrap.min.js"></script>
<script src="/Xtext/js/jquery.easing.1.3.js" type="text/javascript"></script>
<script src="/Xtext/js/jquery.prettyPhoto.js" type="text/javascript"></script>
<script src="/Xtext/js/prettify.js" type="text/javascript"></script>
<script src="/Xtext/js/lang-xtend.js" type="text/javascript"></script>
<script src="/Xtext/js/lang-common.js" type="text/javascript"></script>
<script src="/Xtext/js/custom.js" type="text/javascript"></script>
<!--script src="https://apis.google.com/js/platform.js" async defer></script-->
<!--script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push([ '_setAccount', 'UA-2429174-3' ]);
_gaq.push([ '_trackPageview' ]);
(function() {
var ga = document.createElement('script');
ga.type = 'text/javascript';
ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl'
: 'http://www')
+ '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
})();
</script-->
<script src="/Xtext/js/coverflow.min.js" type="text/javascript"></script>
<script>
$(function() {
$('#coverflow').coverflow({
active : 1,
visibleAside: 2,
overlap : 0.5,
scale : 0.9,
angle : 20,
trigger : {
"itemfocus" : true,
"swipe" : true,
"mousewheel" : false
}
});
$('#coverflow :hidden').toggle();
$(window).resize(function() {
$('#coverflow').coverflow();
});
});
</script>
</footer>
</body>
</html>