Jump to: navigation, search

Difference between revisions of "Xtext/FAQ"

m (How show icons into the outline)
m (fixed title of How show icons in the outline)
Line 223: Line 223:
 
You might remove the <code>genModels</code> from the <code>EcoreGeneratorFragment</code> because you are not generating any EMF anymore!  
 
You might remove the <code>genModels</code> from the <code>EcoreGeneratorFragment</code> because you are not generating any EMF anymore!  
  
== How show icons into the outline ==
+
== How show icons in the outline ==
 
The official way to put the icons into a folder named <code>icons</code> in the  
 
The official way to put the icons into a folder named <code>icons</code> in the  
 
ui package and add a method for each of your ecore classes like this:
 
ui package and add a method for each of your ecore classes like this:

Revision as of 13:47, 29 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 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 only 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 generating any EMF anymore!

How show icons in the outline

The official way to put the icons into a folder named icons in the ui package and add a method for each of your ecore classes like this:

    String image(MyModel ele) {
      return "MyModel.gif";
    }
    String image(Foo ele) {
      return "Foo.gif";
    }
    ....

If you have icons with the same name as the ecore classes you can use a generic image loader:

	@Override
	public Image getImage(Object element) {
		if(element instanceof EObject) {
			String className=((EObject)element).eClass().getName();
			// let's see if we can find a gif image with the same name as the
			// class name...
			Image image = getImageHelper().getImage(className+".gif");
			if(image!=null)
				return image;
			// well, maybe there is a png image...
			image = getImageHelper().getImage(className+".png");
			if(image!=null)
				return image;
		}
		return super.getImage(element);
	}

This will look first look for a .gif and then for a .png with the same name as the class in the icons folder in your project (unless you change the ImageHelper to one that looks somewhere else).