Xtext User Guide Xtext User Guide Heiko Behrens, Michael Clay, Sven Efftinge, Moritz Eysholdt, Peter Friese, Jan Köhnlein, Knut Wannheden, Sebastian Zarnekow and contributors Copyright 2008 - 2010 Xtext 1.0 1 1. Overview .................................................................................................................... 1 1.1. What is Xtext? ................................................................................................... 1 1.2. How Does It Work? ............................................................................................ 1 1.3. Xtext is Highly Configurable ................................................................................ 1 1.4. Who Uses Xtext? ................................................................................................ 1 1.5. Who is Behind Xtext? ......................................................................................... 1 1.6. What is a Domain-Specific Language ..................................................................... 2 2. Getting Started ............................................................................................................ 3 2.1. Creating a DSL .................................................................................................. 3 2.1.1. Create an Xtext Project ............................................................................. 3 2.1.2. Project Layout ......................................................................................... 4 2.1.3. Build Your Own Grammar ......................................................................... 5 2.1.4. Generate Language Artifacts ...................................................................... 8 2.1.5. Run the Generated IDE Plug-in ................................................................... 8 2.1.6. Adding a Namespace Concept .................................................................... 9 2.2. Processing Xtext Models .................................................................................... 11 2.2.1. Loading a Resource ................................................................................ 12 2.2.2. Working with EMF Models ...................................................................... 12 2.2.3. Working with the Parse Tree (aka Node Model) ........................................... 13 2.2.4. Working with the Grammar ...................................................................... 13 2.2.5. Working with Live Models ....................................................................... 14 2.2.6. Summary ............................................................................................... 14 2.3. Writing a Code Generator ................................................................................... 15 2.3.1. Xpand and MWE2 .................................................................................. 15 2.3.2. The Empty Generator Project .................................................................... 15 2.3.3. Replacing the Example Model File (1) ........................................................ 15 2.3.4. The Modeling Workflow Engine File (2) ..................................................... 16 2.3.5. Using Xpand (3) and Xtend (4) for Code Generation ..................................... 18 3. The Grammar Language ............................................................................................ 21 3.1. A First Example ............................................................................................... 21 3.2. The Syntax ...................................................................................................... 22 3.2.1. Language Declaration .............................................................................. 22 3.2.2. EPackage Declarations ............................................................................. 22 3.2.3. Rules .................................................................................................... 24 3.2.4. Parser Rules ........................................................................................... 26 3.2.5. Hidden Terminal Symbols ........................................................................ 30 3.2.6. Data Type Rules ..................................................................................... 31 3.2.7. Enum Rules ........................................................................................... 31 3.3. Ecore Model Inference ....................................................................................... 32 3.3.1. Type and Package Generation ................................................................... 32 3.3.2. Feature and Type Hierarchy Generation ...................................................... 32 3.3.3. Enum Literal Generation .......................................................................... 33 3.3.4. Feature Normalization ............................................................................. 33 3.3.5. Customized Post Processing ...................................................................... 33 3.3.6. Error Conditions ..................................................................................... 34 3.4. Grammar Mixins ............................................................................................... 34 3.5. Common Terminals ........................................................................................... 34 4. Configuration ............................................................................................................ 36 4.1. The Generator .................................................................................................. 36 4.1.1. A Short Introduction to MWE2 ................................................................. 36 4.1.2. General Architecture ............................................................................... 37 4.1.3. Standard Generator Fragments .................................................................. 40 4.2. Dependency Injection in Xtext with Google Guice .................................................. 40 4.2.1. The Module API .................................................................................... 41 4.2.2. Obtaining an Injector .............................................................................. 42 5. Runtime Concepts ...................................................................................................... 43 5.1. Runtime Setup (ISetup) ...................................................................................... 43 5.2. Setup within Eclipse-Equinox (OSGi) ................................................................... 43 Xtext 1.0 ii Xtext User Guide 5.3. Logging ........................................................................................................... 43 5.4. Validation ........................................................................................................ 43 5.4.1. Automatic Validation .............................................................................. 43 5.4.2. Custom Validation .................................................................................. 45 5.4.3. Validation with the Check Language .......................................................... 45 5.4.4. Validating Manually ................................................................................ 46 5.4.5. Test Validators ....................................................................................... 46 5.5. Linking ........................................................................................................... 48 5.5.1. Declaration of Crosslinks ......................................................................... 48 5.5.2. Default Runtime Behavior (Lazy Linking) ................................................... 48 5.6. Scoping ........................................................................................................... 48 5.6.1. Global Scopes and IResourceDescriptions ................................................... 49 5.6.2. Local Scoping ........................................................................................ 54 5.6.3. Imported Namespace-Aware Scoping ......................................................... 56 5.7. Value Converter ................................................................................................ 57 5.7.1. Annotation-Based Value Converters ........................................................... 57 5.8. Serialization ..................................................................................................... 57 5.8.1. The Contract .......................................................................................... 58 5.8.2. Roles of the Semantic Model and the Node Model During Serialization ............. 58 5.8.3. Parse Tree Constructor ............................................................................ 58 5.8.4. Options ................................................................................................. 59 5.8.5. Preserving Comments from the Node Model ................................................ 59 5.8.6. Transient Values ..................................................................................... 59 5.8.7. Unassigned Text ..................................................................................... 60 5.8.8. Cross-Reference Serializer ........................................................................ 60 5.8.9. Merge Whitespaces ................................................................................