Xtext 2.1 Documentation
Total Page:16
File Type:pdf, Size:1020Kb
Xtext 2.1 Documentation October 31, 2011 Contents I. Getting Started 8 1. Installation 9 1.1. Install Pre-Configured Eclipse With Xtext . .9 1.2. Install Xtext From Update Site . .9 2. 5 Minutes Tutorial 10 2.1. Creating A New Xtext Project . 10 2.2. Generating The Language Infrastructure . 10 2.3. Try The Editor . 11 2.4. Conclusion . 11 3. 15 Minutes Tutorial 14 3.1. Create A New Xtext Project . 14 3.2. Write Your Own Grammar . 15 3.3. Generate Language Artifacts . 18 3.4. Run the Generated IDE Plug-in . 18 3.5. Second Iteration : Adding Packages and Imports . 19 4. 15 Minutes Tutorial - Extended 25 4.1. Writing a Code Generator With Xtend . 27 4.2. Unit Testing the Language . 32 4.3. Creating Custom Validation Rules . 32 5. Five simple steps to your JVM language 34 5.1. Step One: Create A New Xtext Project . 35 5.2. Step Two: Write the Grammar . 36 5.3. Step Three: Generate Language Artifacts . 39 5.4. Step Four: Define the Mapping to JVM Concepts . 40 5.5. Step Five : Try the Editor! . 43 II. Reference Documentation 45 6. Overview 46 6.1. What is Xtext? . 46 2 6.2. How Does It Work? . 46 6.3. Xtext is Highly Configurable . 46 6.4. Who Uses Xtext? . 47 6.5. Who is Behind Xtext? . 47 6.6. What is a Domain-Specific Language . 47 7. The Grammar Language 49 7.1. A First Example . 49 7.2. The Syntax . 51 7.2.1. Language Declaration . 51 7.2.2. EPackage Declarations . 51 7.2.3. Rules . 54 7.2.4. Parser Rules . 58 7.2.5. Hidden Terminal Symbols . 64 7.2.6. Data Type Rules . 64 7.2.7. Enum Rules . 65 7.2.8. Syntactic Predicates . 66 7.3. Ecore Model Inference . 67 7.3.1. Type and Package Generation . 67 7.3.2. Feature and Type Hierarchy Generation . 68 7.3.3. Enum Literal Generation . 69 7.3.4. Feature Normalization . 69 7.3.5. Customized Post Processing . 69 7.3.6. Error Conditions . 70 7.4. Grammar Mixins . 70 7.5. Common Terminals . 71 8. Configuration 72 8.1. The Language Generator . 72 8.1.1. A Short Introduction to MWE2 . 72 8.1.2. General Architecture . 74 8.1.3. Standard Generator Fragments . 76 8.2. Dependency Injection in Xtext with Google Guice . 77 8.2.1. The Module API . 78 8.2.2. Obtaining an Injector . 79 9. Runtime Concepts 81 9.1. Runtime Setup (ISetup) . 81 9.2. Setup within Eclipse-Equinox (OSGi) . 81 9.3. Logging . 82 9.4. Validation . 82 9.4.1. Automatic Validation . 82 9.4.2. Custom Validation . 84 9.4.3. Validating Manually . 85 3 9.4.4. Test Validators . 85 9.5. Linking . 87 9.5.1. Declaration of Crosslinks . 87 9.5.2. Default Runtime Behavior (Lazy Linking) . 88 9.6. Scoping . 88 9.6.1. Global Scopes and Resource Descriptions . 90 9.6.2. Local Scoping . 97 9.6.3. Imported Namespace-Aware Scoping . 98 9.7. Value Converter . 100 9.8. Serialization . 101 9.8.1. The Contract . 101 9.8.2. Roles of the Semantic Model and the Node Model During Serial- ization.................................. 102 9.8.3. Parse Tree Constructor . 102 9.8.4. Options . 104 9.8.5. Preserving Comments from the Node Model . 104 9.8.6. Transient Values . 104 9.8.7. Unassigned Text . 104 9.8.8. Cross-Reference Serializer . 105 9.8.9. Merge White Space . 105 9.8.10. Token Stream . 105 9.9. Formatting (Pretty Printing) . 105 9.9.1. General FormattingConfig Settings . 107 9.9.2. FormattingConfig Instructions . 107 9.9.3. Grammar Element Finders . 108 9.10. Fragment Provider (Referencing Xtext Models From Other EMF Artifacts)109 9.11. Encoding in Xtext . 110 9.11.1. Encoding at Language Design Time . 110 9.11.2. Encoding at Language Runtime . 111 9.11.3. Encoding of an XtextResource . 112 9.11.4. Encoding in New Model Projects . 112 9.11.5. Encoding of Xtext Source Code . 112 10.IDE Concepts 113 10.1. Label Provider . 113 10.1.1. Label Providers For EObjects . 113 10.1.2. Label Providers For Index Entries . 115 10.2. Content Assist . 115 10.3. Quick Fixes . 116 10.3.1. Quickfixes for Linking Errors and Syntax Errors . 118 10.4. Template Proposals . 118 10.4.1. Cross Reference Template Variable Resolver . 119 10.4.2. Enumeration Template Variable Resolver . 120 4 10.5. Outline View . 121 10.5.1. Influencing the outline structure . 121 10.5.2. Styling the outline . 123 10.5.3. Filtering actions . 123 10.5.4. Sorting actions . 124 10.5.5. Quick Outline . 125 10.6. Hyperlinking . 125 10.6.1. Location Provider . 125 10.6.2. Customizing Available Hyperlinks . 126 10.7. Syntax Coloring . 126 10.7.1. Lexical Highlighting . 127 10.7.2. Semantic Highlighting . 128 11.Xtext and Java 131 11.1. Plug-in Setup . 131 11.2. Referring to Java Elements using JVM Types . 132 11.2.1. Customization Points . 133 11.3. Referring to Java Types Using Xbase . 133 11.4. Inferring a JVM Model . 136 11.4.1. Linking and Indexing . 137 11.5. Using Xbase Expressions . ..