Customizing Content Assist with Xtext

As basically every part of Eclipse Xtext, the content assist API provides a reasonable default behavior and is greatly customizable by means of dependency injection. This blog post demonstrates, how easy it is to create own completion proposals with this API.

For the sake of simplicity, I'll use a grammar that fits in a single line:
<br /> Color: 'color' rgb=STRING;<br />
It allows to define exactly one color literal and the syntax is not really strict about the literal's format. Valid input files are considered to look like color "0,0,0" or color "255,255,255".

Now comes the fun part: The proposal list for the rgb string should provide some frequently used values, e.g. literals for black or white.

Therefore I have to customize the proposal provider. Xtext already provides an empty stub implementation that will take the custom code. In order to change the proposals for the rgb-value in the parser rule Color, the method completeColor_Rgb(..) has to be overridden. JDT's content assist or the quick outline in the proposal provider implementation helps to find all suitable entry points.
<br /> @Override<br >public void completeColor_Rgb(EObject model,<br > Assignment assignment,<br > ContentAssistContext context,<br > ICompletionProposalAcceptor acceptor) {<br > acceptor.accept(createCompletionProposal(<br > "\"0,0,0\"", "black",<br > null /*getBlackImage()*/, context));<br > acceptor.accept(createCompletionProposal(<br > "\"255,255,255\"", "white",<br > null /*getWhiteImage()*/, context));<br >}<br />
Two lines of code later, I can already insert literals for black or white:

However, there are far more possibilities than simply creating plain vanilla proposals. The overloaded factory method createCompletionProposal(..) returns an instance of the ConfigurableCompletionProposal which has a quite powerful API. It allows to change the appearance of the display string, I can set additional hover information, enable linked edit modes for the custom proposal or make it auto-insertable to name only a few.

The next example uses an own ReplacementTextApplier to hook into the actual moment, when the proposal is applied:
<br /> @Override<br >public void completeColor_Rgb(EObject model,<br > Assignment assignment,<br > final ContentAssistContext context,<br > ICompletionProposalAcceptor acceptor) {<br > ConfigurableCompletionProposal pickColor =<br > (~cast~) createCompletionProposal("Pick color...",<br > context);<br > if (pickColor != null) {<br > pickColor.setTextApplier(<br > new ReplacementTextApplier() {<br > @Override<br > public String getActualReplacementString(<br > ConfigurableCompletionProposal proposal) {<br > Display display = context.getViewer()<br > .getTextWidget().getDisplay();<br > ColorDialog colorDialog = new ColorDialog(<br > display.getActiveShell());<br > RGB newColor = colorDialog.open();<br > return "\"" + newColor.red + "," + <br > newColor.green + "," + <br > newColor.blue + "\"";<br > }<br > });<br > acceptor.accept(pickColor);<br > }<br > ..<br >}<br />
You'll guess that already from the code: This implementation allows to pick the color by means of a color chooser after the proposal has been selected, but see yourself:

There are plenty of other interesting APIs and services around the code completion in Xtext that are worthy of talking about (e.g. the prefix matcher, which Alex covered in his recent post), but I'll leave them for another post.

Xdoc: A Documentation Language For Eclipse Frameworks

Xdoc is a small markup language that allows to create code centric documentation in a very convenient way. The documents can be rendered to HTML, to Eclipse Help files and to a printable PDF.
Besides the usual markup tags to emphasize text, add images and tables or create structures such as chapters, sections and the like, there are two unique features of Xdoc that I want to highlight.

First of all, it is possible to refer to Java types in a way that allows to statically validate these references. This feature comes very handy as soon as you want to describe important hooks of a framework or codebase. The references will be rendered as hyperlinks to the online Javadoc and if there is a public source repository, a second link points directly to the code.

The second interesting feature is related to code snippets in the documentation. It is often valuable to document some usage patterns for a certain class or interface by example. However, making these snippets easy to read and achieving the familiar look of an Eclipse editor with syntax coloring and the like often requires a lot of effort. Xdoc simplifies this greatly. You just define a set of keywords for a language and the renderer will take care of the highlighting for your code snippets in a consistent manner. This is a big improvement when it comes to the appearance of your help files.



To provide just a few technical details: Xdoc was build with Xtext. That is, the Eclipse editor supports all the nice features that you are already familiar with from other editors. The code generator which creates the Eclipse Help files on the fly is written in Xtend which in turn is implemented on top of Xtext 2.0. Xdoc itself was used to write the Eclipse Help for Xtext and Xtend. Actually, the Xtend Help was written before Xtend was implemented, but that's another story. The chicken or the egg? Things get a little blurry these days... Did I mention that Xtext was used to implement Xtext?

New Features In The Xtext Grammar Editor

Besides the huge new features like the Xbase library, the new Xtend and the cross language refactoring capabilities, we made sure that we still find some time to implement small refinements and improvements in Xtext's core. Some of them may be not too obvious but I'm pretty sure they will actually have some impact on the overall user experience when building new languages with the framework. This blog post is about two nice additions in the grammar editor that are available in Xtext 2.0 with Eclipse Indigo.

Improved content assist

You'll often want to create a concrete syntax for an existing EPackage which was somewhat cumbersome in the past since it involved copy and paste of the namespace uri. The good news is:
Adding imported packages was greatly simplified. It's now far easier to find the actual EPackage that you want to use in your grammar because content assist matches for the more selective last segments of the namespace uri, too:



Speaking about imported packages: If you want to override a rule from another grammar, you can now use content assist to create a stub for that. The editor will take care of necessary import clauses:



Quick Fixes

If your workflow is similar to mine, you'll usually develop a grammar top-down. This implies that your grammar often contains a bunch of unresolved rule calls since the invocation of a parser rule appears before the rule itself is written. A new quick fix allows to create stubs for unknown rules as soon as you refer to a rule which does not yet exist:



I hope you like these small improvements as much as I do!