Customizing Error Messages in Xtext 1.0

As the Eclipse Helios Release is around the corner I'll use the chance to describe some nice odds and ends in Xtext 1.0. One of which is a newly introduced API that allows to customize the default messages for parse errors and linking diagnostics.

If you try to read erroneous models, you'll get annotations for syntax errors and linking problems in the editor by default. These error messages are not always the most meaningful ones from a user's point of view. Furthermore it was not possible to i18n them. This was changed with Xtext 1.0 by means of two newly introduced customization hooks.

Users who want to alter the default messages that the parser produces may implement a so called ISyntaxErrorMessageProvider which allows to change the wording of syntax errors and messages from the value converter.

<br /> interface ISyntaxErrorMessageProvider {<br /> SyntaxErrorMessage getSyntaxErrorMessage(<br /> IParserErrorContext context);<br /> SyntaxErrorMessage getSyntaxErrorMessage(<br /> IValueConverterErrorContext context);<br /> }<br />
The implementor has the current state of the parser at hand to produce a meaningful message for the user. Basically any information is available to compute the SyntaxErrorMessage. She is free to use the intermediate semantic model, the attached node model that reflects the parsed tokens, or the really low level stream that the parser works with.

<br /> interface IErrorContext {<br /> String getDefaultMessage();<br /> EObject getCurrentContext();<br /> AbstractNode getCurrentNode();<br /> }<br /> interface IParserErrorContext<br /> extends IErrorContext {<br /> RecognitionException<br /> getRecognitionException();<br /> String[] getTokenNames();<br /> }<br /> interface IValueConverterErrorContext<br /> extends IErrorContext {<br /> ValueConverterException<br /> getValueConverterException();<br /> }<br />
Especially handy is the option to assign an issue code to a syntax error message. This is the constant that a quick fix refers to, to solve your models syntactic problems easily. Assuming you evolve the syntax of your language, you may want to define such quick fixes that migrate old files to the new notation. Of course there are more use cases such as mandatory keyword sequences at the end of an element.

There is another component that produces default error messages: If the linker cannot resolve an EMF proxy when navigating a cross reference, it will create an error diagnostic, too. We used the same pattern to allow clients to customize this message.

<br /> interface ILinkingDiagnosticMessageProvider{<br /> DiagnosticMessage getUnresolvedProxyMessage(<br /> ILinkingDiagnosticContext context);<br /> }<br /> interface ILinkingDiagnosticContext {<br /> EObject getContext();<br /> EReference getReference();<br /> String getLinkText();<br /> }<br />
Again, every piece of information is available in the context, that is passed to the message provider and of course it is possible to assign an issue code to the linking diagnostic. Even more, clients may choose to reduce the severity of the linking problem to a warning. Languages that support a kind of dynamic invoke like C# may establish real links for the statically bound features but ignore unresolved references for dynamic parts.

Both APIs may come quite handy if you want to i18n your applicaton or tailor the error messages that are presented to the user.