Jump to: navigation, search

Difference between revisions of "Xtext/FAQ"

m (How can I control the Xtext meta model inference ?)
m (Workflow / Generator)
Line 34: Line 34:
 
= Workflow / Generator  =
 
= Workflow / Generator  =
  
== Why do I get warnings like "warning(200): InternalFoo.g:42:3: Decision can match ..." when running the generator ?  ==
+
== Why do I get warnings like "warning(200): InternalFoo.g:42:3: Decision can match ..." when running the generator ?  ==
  
 
Here's an example of the full error message:  
 
Here's an example of the full error message:  
Line 45: Line 45:
 
These warnings are generated by the ANTLR code generator. Based on the rules in your grammar the ANTLR generated parser cannot disambiguate what rules to apply for a given input. You should try to refactor your grammar (see [http://www.antlr.org/pipermail/antlr-interest/2008-November/031697.html example]) or you can enable backtracking for your parser (see next question).  
 
These warnings are generated by the ANTLR code generator. Based on the rules in your grammar the ANTLR generated parser cannot disambiguate what rules to apply for a given input. You should try to refactor your grammar (see [http://www.antlr.org/pipermail/antlr-interest/2008-November/031697.html example]) or you can enable backtracking for your parser (see next question).  
  
== OK, but I didn't get these warnings in oAW Xtext !  ==
+
== OK, but I didn't get these warnings in oAW Xtext !  ==
  
 
Unlike in oAW Xtext the ANTLR grammar generated by TMF Xtext doesn't have [http://www.antlr.org/wiki/display/ANTLR3/Grammar+options backtracking] enabled by default. To enable backtracking you have to add a nested element <code>&lt;options backtrack="true"/&gt;</code> to the ANTLR generator fragments in your Xtext project's MWE workflow. So replace:  
 
Unlike in oAW Xtext the ANTLR grammar generated by TMF Xtext doesn't have [http://www.antlr.org/wiki/display/ANTLR3/Grammar+options backtracking] enabled by default. To enable backtracking you have to add a nested element <code>&lt;options backtrack="true"/&gt;</code> to the ANTLR generator fragments in your Xtext project's MWE workflow. So replace:  
Line 73: Line 73:
 
Note that you can in both cases also specify <code>memoize="true"</code> as an additional option.  
 
Note that you can in both cases also specify <code>memoize="true"</code> as an additional option.  
  
== Why are generated packages from an imported grammar A duplicated in dependent grammar B ?  ==
+
== Why are generated packages from an imported grammar A duplicated in dependent grammar B&nbsp;?  ==
  
 
In addition to the import statement in ''B.xtext'' you must also configure your ''GenerateB.mwe'' workflow to let it know about the corresponding GenModels of grammar A. You do this by [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#UsingresourceURIstoimportexistingEPackages setting the genModels attribute] of the EcoreGeneratorFragment:  
 
In addition to the import statement in ''B.xtext'' you must also configure your ''GenerateB.mwe'' workflow to let it know about the corresponding GenModels of grammar A. You do this by [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#UsingresourceURIstoimportexistingEPackages setting the genModels attribute] of the EcoreGeneratorFragment:  
Line 80: Line 80:
 
   <fragment class="org.eclipse.xtext.generator.ecore.EcoreGeneratorFragment"
 
   <fragment class="org.eclipse.xtext.generator.ecore.EcoreGeneratorFragment"
 
       genModels="platform:/resource/my.b.project/src-gen/my/b/B.genmodel"/>
 
       genModels="platform:/resource/my.b.project/src-gen/my/b/B.genmodel"/>
</source>
+
</source>  
  
== How can I control the Xtext meta model inference ?  ==
+
== How can I control the Xtext meta model inference&nbsp;?  ==
  
 
The typical use case is to let Xtext automatically [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#metamodelInference infer a meta model] corresponding to the Xtext grammar. Quite often this meta model is exactly what you want. If you on the other hand want to make some small changes to the inferred meta model (e.g. set attribute default values, add operations, features, or enumeration literals, etc.) you must implement a ''post processor''. Please refer to the [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#customPostProcessing relevant documentation] and the following example for more details.  
 
The typical use case is to let Xtext automatically [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#metamodelInference infer a meta model] corresponding to the Xtext grammar. Quite often this meta model is exactly what you want. If you on the other hand want to make some small changes to the inferred meta model (e.g. set attribute default values, add operations, features, or enumeration literals, etc.) you must implement a ''post processor''. Please refer to the [http://www.eclipse.org/Xtext/documentation/latest/xtext.html#customPostProcessing relevant documentation] and the following example for more details.  
Line 124: Line 124:
 
</source>  
 
</source>  
  
Here is another example where EOperations (here "doFoo" and "getBar") with method bodies are added to types (here "Foo") in the model. The method body simply delegates to a static method with the same name in another class (here "com.mycompany.FooHelper"):
+
Here is another example where EOperations (here "doFoo" and "getBar") with method bodies are added to types (here "Foo") in the model. The method body simply delegates to a static method with the same name in another class (here "com.mycompany.FooHelper"):  
  
 
<source lang="text">
 
<source lang="text">
Line 165: Line 165:
 
"com.mycompany." + eContainingClass.name + "Helper." + name
 
"com.mycompany." + eContainingClass.name + "Helper." + name
 
;
 
;
 +
</source>
 +
 +
== How can I get rid of the ecore model generation (and use only imported EMF models)? ==
 +
Let's start with this simple dsl:
 +
<source lang="text">
 +
grammar org.xtext.example.MyDsl with org.eclipse.xtext.common.Terminals
 +
generate myDsl "http://www.xtext.org/example/MyDsl"
 +
Model:
 +
(elements+=Type)*;
 +
Type:
 +
'type' name=ID;
 +
 
</source>
 
</source>
 +
Here is the model that we want to use:
 +
<source lang="text">
 +
@namespace(uri="http://org.other.model/example/OtherModel", prefix="otherModel")
 +
package otherModel;
 +
 +
class OtherModel {
 +
  val SimpleType[*] elements;
 +
}
 +
 +
class SimpleType {
 +
  attr String name;
 +
}
 +
</source>
 +
 +
#import the ecore model(s)
 +
<source lang="text">
 +
grammar org.xtext.example.MyDsl with org.eclipse.xtext.common.Terminals
 +
import "platform:/resource/org.xtext.example.mydsl/src/org/other/model/OtherModel.ecore" as other
 +
 +
generate myDsl "http://www.xtext.org/example/MyDsl"
 +
 +
Model returns other::OtherModel:
 +
(elements+=Type)*;
 +
 +
Type returns other::SimpleType:
 +
'type' name=ID;
 +
</source>
 +
 +
 +
#make sure you have imported the packages that contain the EMF model in the MANIFEST.MF
  
 
[[Category:FAQ]] [[Category:Xtext]]
 
[[Category:FAQ]] [[Category:Xtext]]

Revision as of 12:33, 28 September 2009

General

How do I load my model in a standalone Java application ?

Assuming you have the standard example grammar MyDsl.xtext the Java code to load a corresponding top-level Model object from a resource (here with URI platform:/resource/org.xtext.example.mydsl/src/example.mydsl) should look something like this:

new org.eclipse.emf.mwe.utils.StandaloneSetup().setPlatformUri("../");
Injector injector = new MyDslStandaloneSetup().createInjectorAndDoEMFRegistration();
XtextResourceSet resourceSet = injector.getInstance(XtextResourceSet.class);
resourceSet.addLoadOption(XtextResource.OPTION_RESOLVE_ALL, Boolean.TRUE);
Resource resource = resourceSet.getResource(
    URI.createURI("platform:/resource/org.xtext.example.mydsl/src/example.mydsl"), true);
Model model = (Model) resource.getContents().get(0);

Note that the argument in the first line is the path to your workspace root and is only required if you use platform:/resource URIs (as in the example) to reference your model files. I.e. if you for instance use file: URIs instead this line is not required.

You can also load a model from a String or an InputStream, yet you still need a resource. As the resource's URI you can any legal dummy URI (here we use dummy:/example.mydsl), just make sure it has the correct file extension, as that is required to look up your DSL's EMF ResourceFactory. Building on the previous example you just need to replace the last two lines with the following:

Resource resource = resourceSet.createResource(URI.createURI("dummy:/example.mydsl"));
InputStream in = new ByteArrayInputStream("type foo type bar".getBytes());
resource.load(in, resourceSet.getLoadOptions());
Model model = (Model) resource.getContents().get(0);

Potential parse errors are available as resource.getErrors().

How can I load my model in the EMF reflective model editor ?

Simply select your model and click the context action Open With > Sample Reflective Ecore Model Editor. This works because Xtext generates and registers a standard EMF resource factory for your DSL (see also previous question) and thus complies with the EMF resource API.

Workflow / Generator

Why do I get warnings like "warning(200): InternalFoo.g:42:3: Decision can match ..." when running the generator ?

Here's an example of the full error message:

warning(200): InternalFoo.g:42:3: Decision can match input such as "FOO" using multiple alternatives: 1, 2
As a result, alternative(s) 2 were disabled for that input

These warnings are generated by the ANTLR code generator. Based on the rules in your grammar the ANTLR generated parser cannot disambiguate what rules to apply for a given input. You should try to refactor your grammar (see example) or you can enable backtracking for your parser (see next question).

OK, but I didn't get these warnings in oAW Xtext !

Unlike in oAW Xtext the ANTLR grammar generated by TMF Xtext doesn't have backtracking enabled by default. To enable backtracking you have to add a nested element <options backtrack="true"/> to the ANTLR generator fragments in your Xtext project's MWE workflow. So replace:

<!-- Antlr Generator fragment -->
<fragment class="org.eclipse.xtext.generator.AntlrDelegatingFragment"/>

with:

<!-- Antlr Generator fragment -->
<fragment class="de.itemis.xtext.antlr.XtextAntlrGeneratorFragment">
   <options backtrack="true"/>
</fragment>

Further down in the workflow you will find another use of the AntlrDelegatingFragment fragment (used for content assist) you have to replace with:

<fragment class="de.itemis.xtext.antlr.XtextAntlrUiGeneratorFragment">
   <options backtrack="true"/>
</fragment>

Note that you can in both cases also specify memoize="true" as an additional option.

Why are generated packages from an imported grammar A duplicated in dependent grammar B ?

In addition to the import statement in B.xtext you must also configure your GenerateB.mwe workflow to let it know about the corresponding GenModels of grammar A. You do this by setting the genModels attribute of the EcoreGeneratorFragment:

   <fragment class="org.eclipse.xtext.generator.ecore.EcoreGeneratorFragment"
      genModels="platform:/resource/my.b.project/src-gen/my/b/B.genmodel"/>

How can I control the Xtext meta model inference ?

The typical use case is to let Xtext automatically infer a meta model corresponding to the Xtext grammar. Quite often this meta model is exactly what you want. If you on the other hand want to make some small changes to the inferred meta model (e.g. set attribute default values, add operations, features, or enumeration literals, etc.) you must implement a post processor. Please refer to the relevant documentation and the following example for more details.

The following example shows how to add an enumeration literal (here NULL) to an enumeration (here VisibilityModifier) and sets it as the default value for all attributes of that type.

import ecore;
 
process(xtext::GeneratedMetamodel this) :
     ePackage.process()
;
 
process(EPackage this) :
     eClassifiers.process()
;
 
process(EClassifier this) :
     null
;
 
process(EClass this) :
     eStructuralFeatures.process()
;
 
process(EEnum this) :
     if name == 'VisibilityModifier' then eLiterals.add(newLiteral('null', 'NULL', eLiterals.size))
;
 
create EEnumLiteral newLiteral(String literal, String name, int value) :
     setLiteral(literal) -> setName(name) -> setValue(value)
;
 
process(EStructuralFeature this) :
     null
;
 
process(EAttribute this) :
     if eAttributeType.name == 'VisibilityModifier' then setDefaultValueLiteral('NULL')
;

Here is another example where EOperations (here "doFoo" and "getBar") with method bodies are added to types (here "Foo") in the model. The method body simply delegates to a static method with the same name in another class (here "com.mycompany.FooHelper"):

import ecore;
 
process(xtext::GeneratedMetamodel this) :
	process(ePackage)
;
 
process(EPackage this) :
	eClassifiers.typeSelect(EClass).process()
;
 
process(EClass this) :
	switch (name) {
		case "Foo": (addOperation("doFoo", null) -> addOperation("getBar", ePackage.getEClassifier("Bar")))
		default:	null
	}
;
 
addOperation(EClass this, String name, EClassifier type) :
	let op  = newOperation(name, type) :
		newDelegatingBodyAnnotation(op)
;
 
create EOperation newOperation(EClass owner, String name, EClassifier type) :
	setName(name) -> setEType(type) -> owner.eOperations.add(this)
;
 
create EAnnotation newDelegatingBodyAnnotation(EOperation op) :
	let d = new EStringToStringMapEntry :
		setSource("http://www.eclipse.org/emf/2002/GenModel") ->
		d.setKey("body") ->
		d.setValue((op.eType != null ? "return " : "") + op.delegateMethodName() + "(this);") ->
		details.add(d) ->
		op.eAnnotations.add(this)
;
 
delegateMethodName(EOperation this) :
	"com.mycompany." + eContainingClass.name + "Helper." +	name
;

How can I get rid of the ecore model generation (and use only imported EMF models)?

Let's start with this simple dsl:

grammar org.xtext.example.MyDsl with org.eclipse.xtext.common.Terminals
generate myDsl "http://www.xtext.org/example/MyDsl"
Model:
	(elements+=Type)*;
Type:
	'type' name=ID;

Here is the model that we want to use:

@namespace(uri="http://org.other.model/example/OtherModel", prefix="otherModel")
package otherModel;
 
class OtherModel {
  val SimpleType[*] elements;
}
 
class SimpleType {
  attr String name;
}
  1. import the ecore model(s)
grammar org.xtext.example.MyDsl with org.eclipse.xtext.common.Terminals
import "platform:/resource/org.xtext.example.mydsl/src/org/other/model/OtherModel.ecore" as other
 
generate myDsl "http://www.xtext.org/example/MyDsl"
 
Model returns other::OtherModel:
	(elements+=Type)*;
 
Type returns other::SimpleType:
	'type' name=ID;


  1. make sure you have imported the packages that contain the EMF model in the MANIFEST.MF