Xtext 2.4 Documentation
Total Page:16
File Type:pdf, Size:1020Kb
Xtext 2.4 Documentation April 16, 2013 Contents I. Getting Started 7 1. 5 Minutes Tutorial 8 1.1. Creating A New Xtext Project . .8 1.2. Generating The Language Infrastructure . .8 1.3. Try The Editor . .9 1.4. Conclusion . 10 2. 15 Minutes Tutorial 12 2.1. Create A New Xtext Project . 12 2.2. Write Your Own Grammar . 13 2.3. Generate Language Artifacts . 17 2.4. Run the Generated IDE Plug-in . 18 2.5. Second Iteration: Adding Packages and Imports . 18 3. 15 Minutes Tutorial - Extended 24 3.1. Writing a Code Generator With Xtend . 26 3.2. Unit Testing the Language . 31 3.3. Creating Custom Validation Rules . 32 4. Five simple steps to your JVM language 34 4.1. Step One: Create A New Xtext Project . 35 4.2. Step Two: Write the Grammar . 36 4.3. Step Three: Generate Language Artifacts . 40 4.4. Step Four: Define the Mapping to JVM Concepts . 40 4.5. Step Five : Try the Editor! . 45 II. Reference Documentation 47 5. Overview 48 5.1. What is Xtext? . 48 5.2. How Does It Work? . 48 5.3. Xtext is Highly Configurable . 48 5.4. Who Uses Xtext? . 49 5.5. Who is Behind Xtext? . 49 2 5.6. What is a Domain-Specific Language . 49 6. The Grammar Language 51 6.1. A First Example . 51 6.2. The Syntax . 53 6.2.1. Language Declaration . 53 6.2.2. EPackage Declarations . 53 6.2.3. Rules . 58 6.2.4. Parser Rules . 62 6.2.5. Hidden Terminal Symbols . 69 6.2.6. Data Type Rules . 70 6.2.7. Enum Rules . 71 6.2.8. Syntactic Predicates . 72 6.3. Ecore Model Inference . 73 6.3.1. Type and Package Generation . 73 6.3.2. Feature and Type Hierarchy Generation . 74 6.3.3. Enum Literal Generation . 75 6.3.4. Feature Normalization . 75 6.3.5. Error Conditions . 75 6.4. Grammar Mixins . 76 6.5. Common Terminals . 77 7. Configuration 78 7.1. The Language Generator . 78 7.1.1. A Short Introduction to MWE2 . 78 7.1.2. General Architecture . 80 7.1.3. Standard Generator Fragments . 83 7.2. Dependency Injection in Xtext with Google Guice . 83 7.2.1. The Module API . 84 7.2.2. Obtaining an Injector . 86 8. Runtime Concepts 88 8.1. Runtime Setup (ISetup) . 88 8.2. Setup within Eclipse-Equinox (OSGi) . 88 8.3. Logging . 89 8.4. Validation . 89 8.4.1. Automatic Validation . 89 8.4.2. Custom Validation . 91 8.4.3. Validating Manually . 92 8.4.4. Test Validators . 92 8.5. Linking . 95 8.5.1. Declaration of Cross-links . 95 8.5.2. Default Runtime Behavior (Lazy Linking) . 95 3 8.6. Scoping . 96 8.6.1. Global Scopes and Resource Descriptions . 97 8.6.2. Local Scoping . 105 8.6.3. Imported Namespace-Aware Scoping . 107 8.7. Value Converter . 109 8.8. Serialization . 110 8.8.1. The Contract . 110 8.8.2. Roles of the Semantic Model and the Node Model During Serial- ization.................................. 111 8.8.3. Parse Tree Constructor . 111 8.8.4. Options . 113 8.8.5. Preserving Comments from the Node Model . 113 8.8.6. Transient Values . 113 8.8.7. Unassigned Text . 114 8.8.8. Cross-Reference Serializer . 114 8.8.9. Merge White Space . 114 8.8.10. Token Stream . 114 8.9. Formatting (Pretty Printing) . 115 8.9.1. General FormattingConfig Settings . 116 8.9.2. FormattingConfig Instructions . 116 8.9.3. Grammar Element Finders . 118 8.10. Fragment Provider (Referencing Xtext Models From Other EMF Artifacts)118 8.11. Encoding in Xtext . 119 8.11.1. Encoding at Language Design Time . 120 8.11.2. Encoding at Language Runtime . 120 8.11.3. Encoding of an XtextResource . 121 8.11.4. Encoding in New Model Projects . 122 8.11.5. Encoding of Xtext Source Code . 122 9. IDE Concepts 123 9.1. Label Provider . 123 9.1.1. Label Providers For EObjects . 123 9.1.2. Label Providers For Index Entries . 125 9.2. Content Assist . 125 9.3. Quick Fixes . 127 9.3.1. Quick Fixes for Linking Errors and Syntax Errors . 129 9.4. Template Proposals . 129 9.4.1. Cross Reference Template Variable Resolver . 130 9.4.2. Enumeration Template Variable Resolver . 130 9.5. Outline View . 131 9.5.1. Influencing the outline structure . 132 9.5.2. Styling the outline . 134 9.5.3. Filtering actions . 134 9.5.4. Sorting actions . 136 4 9.5.5. Quick Outline . 136 9.6. Hyperlinking . 137 9.6.1. Location Provider . 137 9.6.2. Customizing Available Hyperlinks . 138 9.7. Syntax Coloring . 138 9.7.1. Lexical Highlighting . 138 9.7.2. Semantic Highlighting . 140 9.8. Rename Refactoring . 141 9.8.1. Customizing . 142 9.8.2. Rename Participants . 142 10.Xtext and Java 143 10.1. Plug-in Setup . 143 10.2. Referring to Java Elements using JVM Types . 144 10.2.1. Customization Points . 145 10.3. Referring to Java Types Using Xbase . 145 10.4. Inferring a JVM Model . 148 10.4.1. Linking and Indexing . 150 10.5. Using Xbase Expressions . ..