Xtext/FAQ

• Overview
• Contributor Guide
• FAQ

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.

Also note that the MyDslStandaloneSetup.createInjectorAndDoEMFRegistration() call only registers Ecore models generated by the grammar. Imported grammars must be registered manually by e.g. by adding the following statement MyDslPackage.eINSTANCE.eClass();.

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 feature to post process the inferred meta model was removed. It is strongly advised to switch the an imported meta model if the inferrer does not produce the desired result.

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!

Why do I get compilation errors when trying to import an existing Xtext grammar using the with statement?

Consider the following grammars:

grammar my.grammar.Terminals
 
terminal ID : ('a'..'z'|'A'..'Z'|'_'|'0'..'9')+;

grammar my.grammar.DomainModel with my.grammar.Terminals
 
DomainModel: name=ID;

After you run the default MWE2 workflow, you will most likely encounter compilation errors such as:

AbstractTerminalsProposalProvider cannot be resolved to a type
TerminalsGrammarAccess cannot be resolved to a type
...

To resolve this, you need to update your MWE2 workflow so that these classes do get generated.

Try add the following block to the "Generator" workflow in the MWE2 file:

language = {
	uri = terminalURI
	fileExtensions="___terms"
	fragment = grammarAccess.GrammarAccessFragment {}
	fragment = parseTreeConstructor.ParseTreeConstructorFragment {}
	fragment = contentAssist.JavaBasedContentAssistFragment {}
}

How do I enable multiple file extensions for a single DSL?

Open up the plugin.xml for your mydsl.ui project.

For the org.eclipse.ui.editors extension point, enter in a comma-separated list of the file extensions which should be handled by your DSL. E.g.:

<editor
   class="ansa.autotest.ui.HtmlExecutableExtensionFactory:org.eclipse.xtext.ui.editor.XtextEditor"
   contributorClass="org.eclipse.ui.editors.text.TextEditorActionContributor"
   default="true"
   extensions="htm,html"
   id="mydsl.html"
   name="HTML Editor">
</editor>

Make a copy of the existing org.eclipse.emf.ecore.extension_parser and org.eclipse.xtext.extension_resourceServiceProvider extension points, replacing the type and uriExtension attributes with each additional file extension.

UI

How do I implement a generic label provider ?

The official way is to put the icons into a folder icons in the

UI project and add a method to your LabelProvider for each of your Ecore classes:

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

If the name of your icons corresponds to the name of your Ecore classes you can declare a generic method:

    public String image(EObject obj) {
        return obj.eClass().getName() + ".gif";
    }

You may also want to look for a PNG as a fallback. The following code will first look for the image as determined by the label provider (see above) and in case this is a non-existing GIF then as a fallback for a PNG with the same name:

    @Override
    public Image getImage(Object element) {
    	Image image = super.getImage(element);
    	if (image == null) {
        	String imageName = getImageDispatcher().invoke(element);
        	if (imageName != null && imageName.endsWith(".gif"))
        		image = getImageHelper().getImage(imageName.substring(0, imageName.length() - 3) + "png");
    	}
    	return image;
    }