Xtext 2.5 Documentation
Total Page:16
File Type:pdf, Size:1020Kb
Xtext 2.5 Documentation December 16, 2013 Contents I. Getting Started 8 1. 5 Minutes Tutorial 9 1.1. Creating A New Xtext Project . .9 1.2. Generating The Language Infrastructure . .9 1.3. Try The Editor . 10 1.4. Conclusion . 11 2. 15 Minutes Tutorial 13 2.1. Create A New Xtext Project . 13 2.2. Write Your Own Grammar . 15 2.3. Generate Language Artifacts . 18 2.4. Run the Generated IDE Plug-in . 19 2.5. Second Iteration: Adding Packages and Imports . 19 3. 15 Minutes Tutorial - Extended 26 3.1. Writing a Code Generator With Xtend . 28 3.2. Unit Testing the Language . 33 3.3. Creating Custom Validation Rules . 34 4. Five simple steps to your JVM language 36 4.1. Step One: Create A New Xtext Project . 37 4.2. Step Two: Write the Grammar . 37 4.3. Step Three: Generate Language Artifacts . 42 4.4. Step Four: Define the Mapping to JVM Concepts . 42 4.5. Step Five : Try the Editor! . 47 II. Reference Documentation 49 5. Overview 50 5.1. What is Xtext? . 50 5.2. How Does It Work? . 50 5.3. Xtext is Highly Configurable . 50 5.4. Who Uses Xtext? . 51 5.5. Who is Behind Xtext? . 51 2 5.6. What is a Domain-Specific Language . 51 6. The Grammar Language 53 6.1. A First Example . 53 6.2. The Syntax . 55 6.2.1. Language Declaration . 55 6.2.2. EPackage Declarations . 55 6.2.3. Rules . 60 6.2.4. Parser Rules . 64 6.2.5. Hidden Terminal Symbols . 71 6.2.6. Data Type Rules . 72 6.2.7. Enum Rules . 73 6.2.8. Syntactic Predicates . 74 6.3. Ecore Model Inference . 75 6.3.1. Type and Package Generation . 75 6.3.2. Feature and Type Hierarchy Generation . 76 6.3.3. Enum Literal Generation . 77 6.3.4. Feature Normalization . 77 6.3.5. Error Conditions . 77 6.4. Grammar Mixins . 78 6.5. Common Terminals . 79 7. Configuration 80 7.1. The Language Generator . 80 7.1.1. A Short Introduction to MWE2 . 80 7.1.2. General Architecture . 82 7.1.3. Standard Generator Fragments . 85 7.2. Dependency Injection in Xtext with Google Guice . 85 7.2.1. The Module API . 86 7.2.2. Obtaining an Injector . 88 7.3. Continuous Integration (with Maven) . 89 7.3.1. An overview of the example projects . 89 7.3.2. Building an Xtext language with Maven and Tycho . 89 7.3.3. Integration in Standard Maven Builds . 93 8. Runtime Concepts 95 8.1. Runtime Setup (ISetup) . 95 8.2. Setup within Eclipse-Equinox (OSGi) . 95 8.3. Logging . 96 8.4. Code Generation / Compilation . 96 8.4.1. IGenerator . 96 8.4.2. Output Configurations . 97 8.5. Validation . 97 8.5.1. Automatic Validation . 97 3 8.5.2. Custom Validation . 99 8.5.3. Validating Manually . 100 8.5.4. Test Validators . 101 8.6. Linking . 103 8.6.1. Declaration of Cross-links . 103 8.6.2. Default Runtime Behavior (Lazy Linking) . 104 8.7. Scoping . 104 8.7.1. Global Scopes and Resource Descriptions . 106 8.7.2. Local Scoping . 113 8.7.3. Imported Namespace-Aware Scoping . 116 8.8. Value Converter . 117 8.9. Serialization . 118 8.9.1. The Contract . 119 8.9.2. Roles of the Semantic Model and the Node Model During Serial- ization.................................. 119 8.9.3. Parse Tree Constructor . 120 8.9.4. Options . 121 8.9.5. Preserving Comments from the Node Model . 121 8.9.6. Transient Values . 122 8.9.7. Unassigned Text . 122 8.9.8. Cross-Reference Serializer . 122 8.9.9. Merge White Space . 122 8.9.10. Token Stream . 123 8.10. Formatting (Pretty Printing) . 123 8.10.1. General FormattingConfig Settings . 124 8.10.2. FormattingConfig Instructions . 125 8.10.3. Grammar Element Finders . 126 8.11. Fragment Provider (Referencing Xtext Models From Other EMF Artifacts)126 8.12. Encoding in Xtext . 128 8.12.1. Encoding at Language Design Time . 128 8.12.2. Encoding at Language Runtime . 129 8.12.3. Encoding of an XtextResource . 130 8.12.4. Encoding in New Model Projects . 130 8.12.5. Encoding of Xtext Source Code . 130 9. IDE Concepts 131 9.1. Label Provider . 131 9.1.1. Label Providers For EObjects . 131 9.1.2. Label Providers For Index Entries . 133 9.2. Content Assist . 133 9.3. Quick Fixes . 135 9.3.1. Quick Fixes for Linking Errors and Syntax Errors . 137 9.4. Template Proposals . 137 9.4.1. Cross Reference Template Variable Resolver . 138 4 9.4.2. Enumeration Template Variable Resolver . 138 9.5. Outline View . 139 9.5.1. Influencing the outline structure . 140 9.5.2. Styling the outline . 142 9.5.3. Filtering actions . 142 9.5.4. Sorting actions . 144 9.5.5. Quick Outline . 144 9.6. Hyperlinking . 145 9.6.1. Location Provider . 145 9.6.2. Customizing Available Hyperlinks . 146 9.7. Syntax Coloring . 146 9.7.1. Lexical Highlighting . 146 9.7.2. Semantic Highlighting . 148 9.8. Rename Refactoring . 149 9.8.1. Customizing . 150 9.8.2. Rename Participants . 150 10.Xtext and Java 151 10.1. Plug-in Setup . ..