Resources
-
+
@@ -37,7 +37,7 @@
-
Forum
+GitHub Discussions
-
The Xtext™ forum is the first source for getting answers in case you got stuck. +
Xtext™ GitHub Discussions is the first source for getting answers in case you got stuck. The community is very friendly.
Forum
Found a Bug?
-
Bug reports and enhancement request are tracked at GitHub.org. Please +
Bug reports and enhancement request are tracked at GitHub.com. Please explain the problem and provide a reduced but reproducible example.
Found a Bug?
-
Github
+GitHub
The Xtext™ source code is available on GitHub. You'll find more information on how to contribute to the project in the README.md contained there.
@@ -80,6 +80,24 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Forum (archived)
+
+
+ The Xtext™ forum, now read-only, is still a useful resource, as it contains several years' worth of discussion about Xtext.
+
diff --git a/xtext-website/documentation/301_grammarlanguage.md b/xtext-website/documentation/301_grammarlanguage.md
index 117b1f4..f304451 100644
--- a/xtext-website/documentation/301_grammarlanguage.md
+++ b/xtext-website/documentation/301_grammarlanguage.md
@@ -29,7 +29,7 @@ The second aspect that can be deduced from the first line of the grammar is its
### EPackage Declarations {#package-declarations}
-Xtext parsers create in-memory object graphs while consuming text. Such object-graphs are instances of [EMF](https://www.eclipse.org/modeling/emf/) Ecore models. An Ecore model basically consists of an EPackage containing EClasses, EDataTypes and EEnums (see the [section on EMF](308_emf_integration.html#model-metamodel) for more details) and describes the structure of the instantiated objects. Xtext can infer Ecore models from a grammar (see [Ecore model inference](301_grammarlanguage.html#metamodel-inference)) 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.
+Xtext parsers create in-memory object graphs while consuming text. Such object-graphs are instances of [EMF](https://projects.eclipse.org/projects/modeling.emf.emf) Ecore models. An Ecore model basically consists of an EPackage containing EClasses, EDataTypes and EEnums (see the [section on EMF](308_emf_integration.html#model-metamodel) for more details) and describes the structure of the instantiated objects. Xtext can infer Ecore models from a grammar (see [Ecore model inference](301_grammarlanguage.html#metamodel-inference)) 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.
#### EPackage Generation
@@ -766,4 +766,4 @@ terminal ANY_OTHER:
---
-**[Next Chapter: Configuration](302_configuration.html)**
\ No newline at end of file
+**[Next Chapter: Configuration](302_configuration.html)**
diff --git a/xtext-website/documentation/303_runtime_concepts.md b/xtext-website/documentation/303_runtime_concepts.md
index f078e94..a4e1fb5 100644
--- a/xtext-website/documentation/303_runtime_concepts.md
+++ b/xtext-website/documentation/303_runtime_concepts.md
@@ -531,7 +531,7 @@ Serialization is invoked when calling [XtextResource.save(..)]({{site.src.xtext}
### The Contract {#serialization-contract}
-The contract of serialization says that a model which is saved (serialized) to its textual representation and then loaded (parsed) again yields a new model that is equal to the original model. Please be aware that this does *not* imply that loading a textual representation and serializing it back produces identical textual representations. However, the serialization algorithm tries to restore as much information as possible. That is, if the parsed model was not modified in-memory, the serialized output will usually be equal to the previous input. Unfortunately, this cannot be ensured for each and every case. A use case where is is hardly possible, is shown in the following example:
+The contract of serialization says that a model which is saved (serialized) to its textual representation and then loaded (parsed) again yields a new model that is equal to the original model. Please be aware that this does *not* imply that loading a textual representation and serializing it back produces identical textual representations. However, the serialization algorithm tries to restore as much information as possible. That is, if the parsed model was not modified in-memory, the serialized output will usually be equal to the previous input. Unfortunately, this cannot be ensured for each and every case. A use case where it is hardly possible, is shown in the following example:
```xtext
MyRule:
@@ -601,13 +601,13 @@ Example:
```xtext
PluralRule:
- 'contents:' count=INT Plural;
+ 'contents:' count=INT PLURAL;
-terminal Plural:
+terminal PLURAL:
'item' | 'items';
```
-Valid models for this example are `contents 1 item` or `contents 5 items`. However, it is not stored in the semantic model whether the keyword *item* or *items* has been parsed. This is due to the fact that the rule call *Plural* is unassigned. However, the [parse tree constructor](#parse-tree-constructor) needs to decide which value to write during serialization. This decision can be be made by customizing the [IValueSerializer.serializeUnassignedValue(EObject, RuleCall, INode)]({{site.src.xtext}}/org.eclipse.xtext/src/org/eclipse/xtext/parsetree/reconstr/ITokenSerializer.java).
+Valid models for this example are `contents 1 item` or `contents 5 items`. However, it is not stored in the semantic model whether the keyword *item* or *items* has been parsed. This is due to the fact that the rule call *PLURAL* is unassigned. However, the [parse tree constructor](#parse-tree-constructor) needs to decide which value to write during serialization. This decision can be be made by customizing the [IValueSerializer.serializeUnassignedValue(EObject, RuleCall, INode)]({{site.src.xtext}}/org.eclipse.xtext/src/org/eclipse/xtext/parsetree/reconstr/ITokenSerializer.java).
### Cross-Reference Serializer {#cross-reference-serializer}
@@ -632,6 +632,91 @@ public interface ITokenStream {
}
```
+## Tree Manipulation {#tree-manipulation}
+An implementation of [IDerivedStateComputer](https://github.com/eclipse/xtext/blob/main/org.eclipse.xtext/src/org/eclipse/xtext/resource/IDerivedStateComputer.java) can be used to modify the objects in the abstract syntax tree after parsing. Commonly, implementations of this interface are used to modify the objects' features programmatically.
+
+As an example, let's take a simple Entity DSL defined by the following grammar:
+
+```xtext
+grammar org.xtext.example.mydsl.MyDsl with org.eclipse.xtext.common.Terminals
+
+generate myDsl "http://www.xtext.org/example/mydsl/MyDsl"
+
+Model:
+ entities+=Entity*;
+
+Entity:
+ 'Entity' name=QUOTED_NAME shortName=ID?;
+
+terminal QUOTED_NAME:
+ '\'' ID (ID | ' ')* '\'';
+```
+
+This grammar allows declaring that an Entity has got a name and a short name. The former is mandatory, and composed by one or more tokens matched by the ID terminal rule, each followed by an arbitrary number of whitespaces. The resulting name must then be wrapped in single quotation marks. The latter is optional, and consists of a simple ID token. Suppose we want all Entities in our AST to have a short name: we can use a custom IDerivedStateComputer to achieve this.
+
+Let's see a sample implementation of this interface that takes care of setting the `shortName` feature of Entities which lack a short name. We want to set it to the name of the Entity, deprived of the quotation marks, without any whitespace, and suffixed with "_computed". For this purpose, we write the following implementation and place it, for instance, inside the `org.xtext.example.mydsl.services` package of our DSL project:
+
+```java
+package org.xtext.example.mydsl.services;
+
+import org.eclipse.xtext.resource.DerivedStateAwareResource;
+import org.eclipse.xtext.resource.IDerivedStateComputer;
+import org.xtext.example.mydsl.myDsl.Entity;
+
+public class MyDslDerivedStateComputer implements IDerivedStateComputer {
+ private static final String SUFFIX = "_computed";
+
+ @Override
+ public void installDerivedState(DerivedStateAwareResource resource, boolean preLinkingPhase) {
+ resource.getAllContents().forEachRemaining(eObject -> {
+ if (eObject instanceof final Entity entity) {
+ if (entity.getShortName() == null) {
+ final String name = entity.getName();
+ final String shortName = name
+ .substring(1, name.length() - 1)
+ .replaceAll("\\s", "")
+ .trim()
+ .concat(SUFFIX);
+ entity.setShortName(shortName);
+ }
+ }
+ });
+ }
+
+ @Override
+ public void discardDerivedState(DerivedStateAwareResource resource) {
+ resource.getAllContents().forEachRemaining(eObject -> {
+ if (eObject instanceof final Entity entity) {
+ if (entity.getShortName().endsWith(SUFFIX)) {
+ entity.setShortName(null);
+ }
+ }
+ });
+ }
+}
+```
+
+The `installDerivedState()` method is responsible for applying the desired changes. For serialization purposes, we also need to implement `discardDerivedState()` to tell the framework how to revert the changes applied programmatically. Note that this implementation sets to `null` the `shortName` feature of any Entity whose short name ends with the suffix, regardless of the origin of such name (input by the user or set by `installDerivedState()`).
+
+In order for Xtext to actually use our custom IDerivedStateComputer, as a last step we need to bind it in our runtime module:
+
+```java
+public class MyDslRuntimeModule extends AbstractMyDslRuntimeModule {
+ public Class bindIDerivedStateComputer() {
+ return MyDslDerivedStateComputer.class;
+ }
+
+ @Override
+ public Class bindXtextResource() {
+ return DerivedStateAwareResource.class;
+ }
+
+ public Class bindIResourceDescriptionManager() {
+ return DerivedStateAwareResourceDescriptionManager.class;
+ }
+}
+```
+
## Formatting {#formatting}
Formatting (aka. pretty printing) is the process of rearranging the text in a document to improve the readability without changing the semantic value of the document. Therefore a formatter is responsible for arranging line-wraps, indentation, whitespace, etc. in a text to emphasize its structure, but it is not supposed to alter a document in a way that impacts the semantic model.
diff --git a/xtext-website/documentation/308_emf_integration.md b/xtext-website/documentation/308_emf_integration.md
index f9ce751..7d00f44 100644
--- a/xtext-website/documentation/308_emf_integration.md
+++ b/xtext-website/documentation/308_emf_integration.md
@@ -6,7 +6,7 @@ part: Reference Documentation
# {{page.title}} {#emf-integration}
-Xtext relies heavily on EMF internally, but it can also be used as the serialization back-end of other EMF-based tools. In this section we introduce the basic concepts of the [Eclipse Modeling Framework (EMF)](https://www.eclipse.org/modeling/emf/) in the context of Xtext. If you want to learn more about EMF, we recommend reading the [EMF book](https://www.eclipse.org/modeling/emf/).
+Xtext relies heavily on EMF internally, but it can also be used as the serialization back-end of other EMF-based tools. In this section we introduce the basic concepts of the [Eclipse Modeling Framework (EMF)](https://projects.eclipse.org/projects/modeling.emf.emf) in the context of Xtext. If you want to learn more about EMF, we recommend reading the [EMF book](https://wiki.eclipse.org/Eclipse_Modeling_Framework#Documentation_.26_Assistance).
## Model, Ecore Model, and Ecore {#model-metamodel}
diff --git a/xtext-website/documentation/310_eclipse_support.md b/xtext-website/documentation/310_eclipse_support.md
index 3d20497..ef69860 100644
--- a/xtext-website/documentation/310_eclipse_support.md
+++ b/xtext-website/documentation/310_eclipse_support.md
@@ -388,12 +388,13 @@ Note that the method `_text(modelElement)` can return a [String]({{site.javadoc.
private StylerFactory stylerFactory;
public Object _text(Entity entity) {
- if(entity.isAbstract()) {
+ if (entity.isAbstract()) {
return new StyledString(entity.getName(),
stylerFactory
- .createXtextStyleAdapterStyler(getTypeTextStyle())));
- else
+ .createXtextStyleAdapterStyler(getTypeTextStyle()));
+ } else {
return entity.getName();
+ }
}
protected TextStyle getTypeTextStyle() {
diff --git a/xtext-website/documentation/350_continuous_integration.md b/xtext-website/documentation/350_continuous_integration.md
index c253812..b9c91b9 100644
--- a/xtext-website/documentation/350_continuous_integration.md
+++ b/xtext-website/documentation/350_continuous_integration.md
@@ -307,8 +307,9 @@ To further speed up the p2 dependency resolution step, use the concrete build re
| Xtext | EMF | MWE2/MWE | Xpand | Eclipse | All included in |
| ------------- | ------------- | ----------- | ----------- | ----------- | ----------- |
-| [2.37.0]({{page.upsite.xtext}}releases/2.37.0/) | [2.39.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.39.0) (2.29.0) | [2.20.0]({{page.upsite.mwe}}releases/2.20.0/) (2.9.1) | no longer supported | [4.34.0]({{page.upsite.eclipse}}releases/2024-12) (4.24) | [2024-12]({{page.upsite.eclipse}}releases/2024-12)|
-| [2.36.0]({{page.upsite.xtext}}releases/2.36.0/) | [2.38.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.38.0) (2.29.0) | [2.19.0]({{page.upsite.mwe}}releases/2.19.0/) (2.9.1) | no longer supported | [4.33.0]({{page.upsite.eclipse}}releases/2024-09) (4.23) | [2024-09]({{page.upsite.eclipse}}releases/2024-09)|
+| [2.38.0]({{page.upsite.xtext}}releases/2.38.0/) | [2.41.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.41.0) (2.36.0) | [2.21.0]({{page.upsite.mwe}}releases/2.21.0/) (2.9.1) | no longer supported | [4.35.0]({{page.upsite.eclipse}}releases/2025-03) (4.30) | [2025-03]({{page.upsite.eclipse}}releases/2025-03)|
+| [2.37.0]({{page.upsite.xtext}}releases/2.37.0/) | [2.40.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.40.0) (2.29.0) | [2.20.0]({{page.upsite.mwe}}releases/2.20.0/) (2.9.1) | no longer supported | [4.34.0]({{page.upsite.eclipse}}releases/2024-12) (4.24) | [2024-12]({{page.upsite.eclipse}}releases/2024-12)|
+| [2.36.0]({{page.upsite.xtext}}releases/2.36.0/) | [2.39.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.39.0) (2.29.0) | [2.19.0]({{page.upsite.mwe}}releases/2.19.0/) (2.9.1) | no longer supported | [4.33.0]({{page.upsite.eclipse}}releases/2024-09) (4.23) | [2024-09]({{page.upsite.eclipse}}releases/2024-09)|
| [2.35.0]({{page.upsite.xtext}}releases/2.35.0/) | [2.38.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.38.0) (2.29.0) | [2.18.0]({{page.upsite.mwe}}releases/2.18.0/) (2.9.1) | no longer supported | [4.32.0]({{page.upsite.eclipse}}releases/2024-06) (4.23) | [2024-06]({{page.upsite.eclipse}}releases/2024-06)|
| [2.34.0]({{page.upsite.xtext}}releases/2.34.0/) | [2.37.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.37.0) (2.29.0) | [2.17.0]({{page.upsite.mwe}}releases/2.17.0/) (2.9.1) | no longer supported | [4.31.0]({{page.upsite.eclipse}}releases/2024-03) (4.23) | [2024-03]({{page.upsite.eclipse}}releases/2024-03)|
| [2.33.0]({{page.upsite.xtext}}releases/2.33.0/) | [2.36.0]({{page.upsite.eclipse}}modeling/emf/emf/builds/release/2.36.0) (2.29.0) | [2.16.0]({{page.upsite.mwe}}releases/2.16.0/) (2.9.1) | no longer supported | [4.30.0]({{page.upsite.eclipse}}releases/2023-12) (4.23) | [2023-12]({{page.upsite.eclipse}}releases/2023-12)|
@@ -340,7 +341,7 @@ To further speed up the p2 dependency resolution step, use the concrete build re
| [2.8.3]({{page.upsite.xtext}}releases/2.8.3/), [2.8.2]({{page.upsite.xtext}}releases/2.8.2/), [2.8.1]({{page.upsite.xtext}}releases/2.8.1/) | [2.11.0]({{page.upsite.emf}}2.11/core/R201506010402/) (2.10.2) | [2.8.0]({{page.upsite.mwe}}releases/2.8.0/) (2.7.1) | [2.1.0]({{page.upsite.xpand}}releases/R201505260349) (1.4) | [4.5.0]({{page.upsite.eclipse}}eclipse/updates/4.5/R-4.5-201506032000/) (3.6) | [Mars R]({{page.upsite.eclipse}}releases/mars/201506241002/)|
| [2.7.3]({{page.upsite.xtext}}releases/maintenance/R201411190455/) | [2.10.2]({{page.upsite.emf}}2.10.x/core/S201501230452/) (2.10) | [2.7.0]({{page.upsite.mwe}}releases/R201409021051/mwe2lang/) [1.3.4]({{page.upsite.mwe}}releases/R201409021027/mwe) (2.7.0/1.2) | [2.0.0]({{page.upsite.xpand}}releases/R201406030414) (1.4) | [4.4.2]({{page.upsite.eclipse}}eclipse/updates/4.4/R-4.4.2-201502041700) (3.6) |[Luna SR2]({{page.upsite.eclipse}}releases/luna/201502271000/)|
-The following is an example target platform definition for Xtext 2.37.0 and Eclipse 4.34 alias 2024-12.
+The following is an example target platform definition for Xtext 2.38.0 and Eclipse 4.35 alias 2025-03.
```xml
@@ -349,7 +350,7 @@ The following is an example target platform definition for Xtext 2.37.0 and Ecli
diff --git a/xtext-website/index.html b/xtext-website/index.html
index 4842941..01acfe2 100644
--- a/xtext-website/index.html
+++ b/xtext-website/index.html
@@ -177,7 +177,7 @@
e.g.