Difference between revisions of "Xtext/FAQ"

From Eclipsepedia

Jump to: navigation, search
m (How can I get rid of the ecore model generation (and use only imported EMF models)?)
m (How can I get rid of the ecore model generation (and use only imported EMF models)?)
Line 178: Line 178:
 
'type' name=ID;
 
'type' name=ID;
  
</source> Here is the model that we want to use:  
+
</source> Here is the EMF model that we want to use (in [[Emfatic]] syntax):  
 
<source lang="text">
 
<source lang="text">
 
@namespace(uri="http://org.other.model/example/OtherModel", prefix="otherModel")
 
@namespace(uri="http://org.other.model/example/OtherModel", prefix="otherModel")

Revision as of 13:59, 28 September 2009

Contents

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 EMF model that we want to use (in Emfatic syntax):
@namespace(uri="http://org.other.model/example/OtherModel", prefix="otherModel")
package otherModel;
class OtherModel {
  val SimpleType[*] elements;
}
class SimpleType {
  attr String name;
}
Make sure you have imported the packages that contain the EMF model in the MANIFEST.MF Change the workflow and add the following attributes to the existing workflow elements. Add "genModels" to the EcoreGeneratorFragment fragment. This is needed so that the generator finds your genmodel:
  <fragment class="org.eclipse.xtext.generator.ecore.EcoreGeneratorFragment"
      genModels="platform:/resource/org.xtext.example.mydsl/src/org/other/model/OtherModel.genmodel"/>
Add "registerGeneratedEPackage" to the StandaloneSetup bean. This is needed so that xtext finds your package. If there are more then one model, use a comma separated list in the registerGeneratedEPackage attribute:
   <bean class="org.eclipse.emf.mwe.utils.StandaloneSetup" platformUri="${runtimeProject}/.."
    registerGeneratedEPackage="otherModel.MyDslPackage"/>

Import the ecore model(s) and use it in your grammar. You know that you are ready for the next step if the generated Mydsl.ecore file contains an empty package.

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;
Remove the generate statement form your grammar.
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
Model returns other::OtherModel:
	(elements+=Type)*;
Type returns other::SimpleType:
	'type' name=ID;

You might remove the genModels from the EcoreGeneratorFragment because you are not generation any EMF anymore!