Xtext Quick Fix Variants

One of my favorite Eclipse features is the quick fix functionality. When there is an error in your source code, Eclipse may have a quick fix available - it shows up with a bulb symbol on the left editor margin and may offer you several actions to fix it. You can also use the shortcut [Ctrl-1] to activate it. Xtext ships with a quick fix API which makes it easy to provide quick fixes for your own DSL, so you can provide quick fixes for your customized validation errors and warnings, which is really nice.

Quick fix actions in Xtext may either manipulate the Xtext document directly, or modify the underlying semantic model, and Xtext takes care of changing the document. Isn't that neat? For pure text manipulation, the IModification interface can be used, while for working on the model you may implement ISemanticModification. The example below shows you how to use those two variants. In the example, we use a simple domain specific language for a tourist guide. The model may contain an arbitrary number of cities, and each city may contain zero or more sights, where a sight has a name and a description. We implemented two validation warnings: One checks whether the city's name starts with a capital letter, the other warns the user when a city doesn't have any sights. Quick fixes could be to capitalize the first letter (by changing the Xtext document) and, for the sake of the example, just add a generic sight, but this time by modifying the semantic model. To associate a quick fix with a certain validation, an identification code is used, so you have to define one for your validation like this:

public static final String INVALID_NAME = "xtext.workshop.advanced.quickfix.InvalidTypeName";

The check could look like this:

public class TouristguideDslJavaValidator extends
        AbstractTouristguideDslJavaValidator {
[...]

    @Check
    public void checkTypeNameStartsWithCapital(City city) {
        if (city.getName() == null || city.getName().length() == 0)
            return;
        if (!Character.isUpperCase(city.getName().charAt(0))) {
            warning("Name should start with a capital letter.",
                    TouristguideDslPackage.CITY__NAME, INVALID_NAME,
                    city.getName());
        }
    }
}

Note that the warning takes additional parameters (in the example only one is supplied) with "user data". Here you can supply an arbitrary number of Strings with user data that may be useful for the quick fix. Here is a step-by-step guide:

1. Import the plug-ins with the Touristguide Language (download examples). If you only want to try the quick fix but not implement it yourself, just download the finished projects where quick fixes are already implemented. Have a quick look at the Touristguide.xtext file in to understand how a valid .guide-file looks like.
2. Launch an Eclipse runtime application, create an new project, a new .guide-file and test if you get two validation warnings in the Problems view (Shift-Alt-Q X) for the following text:

   city "bonn" { }

3. Switch back to the Eclipse development environment workbench and review the validator TouristguideDslJavaValidator.java (you may cf. section 7.3 Quick Fixes of the Xtext 1.0.0 documentation)
4. Open the file TouristguideDslQuickfixProvider.java in the ui-Project. To implement the quick fix for the capital letters, you may implement methods like the ones below.

public class TouristguideDslQuickfixProvider extends DefaultQuickfixProvider {

    @Fix(TouristguideDslJavaValidator.INVALID_NAME)
    public void capitalizeName(final Issue issue,
                               IssueResolutionAcceptor acceptor) {
        // retrieve the 'user data' from the validation warning
        // upcase.png ... icon to display (in the icons folder)
        acceptor.accept(issue, "Capitalize name", "Capitalize the name \""
                        + issue.getData()[0] + "\".",
                "upcase.png", new IModification() {
                    public void apply(IModificationContext context)
                            throws BadLocationException {
                        IXtextDocument xtextDocument = context
                                .getXtextDocument();
                        String firstLetter = xtextDocument.get(
                                issue.getOffset() + 1, 1);
                        xtextDocument.replace(issue.getOffset() + 1, 1,
                                firstLetter.toUpperCase());
                    }
                });
    }

    @Fix(TouristguideDslJavaValidator.CITY_NOT_INTERESTING)
    public void addSightToCity(final Issue issue,
                               IssueResolutionAcceptor acceptor) {
        acceptor.accept(issue, "Add sight to make city more interesting",
                "Add a random sight, to make the city look more interesting.",
        
                // providing null for the icon name makes Eclipse use the
                // standard quick fix icon
                null, new ISemanticModification() {
                    public void apply(EObject element,
                                      IModificationContext context) throws Exception {
                        // we know that the warning applies to cities
                        City c = (City) element;
                        // programmatic modification of the model
                        Sight sight = TouristguideDslFactory.eINSTANCE
                                .createSight();
                        sight.setName("Central Station");
                        sight.setDescription("The famous central station of "
                                + Strings.toFirstUpper(c.getName()) + ".");
                        c.getSights().add(sight);
                        // Xtext automatically inserts text for the above
                    }
                });
    }
}

5. Restart the runtime workbench and have fun testing your new quick fixes :-)