Version

Customize Error Messages

Topic Overview

Purpose

This topic explains how to customize the error messages produced by the Syntax Parsing Engine.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides an overview of the Syntax Parsing Engine.

This topic provides an overview of the Syntax Parsing Engine’s Grammar.

This topic explains the process of creating a custom language.

Error Messages

Overview

The Syntax Parsing Engine generates messages when an error is detected. Unless otherwise specified, the error messages will have the following form:

  • For skipped tokens: “Unexpected token ‘<text from token>’”

  • For inserted missing nodes:

    • If the node is a non-terminal symbol: “<NonTerminalSymbol.Name> expected”

    • If the node is a terminal symbol with a Comparison value of RegularExpression: “<TerminalSymbol.Name> expected”

    • If the node is any other terminal symbol: “<TerminalSymbol.Value> expected”

For nodes representing non-terminal symbols with their IsError value set to true: “ <NonTerminalSymbol.Name> is incorrect”

Customizing error messages

In some situations, the default error messages may not be suitable for the purpose of the application. In this case you can customize the messages using one of the methods below:

Overriding the GetErrorAlias method

When an error occurs, the parser will call the GetErrorAlias method, which allows the language to provide an alias for the specified Symbol. It returns null by default. If you override it and return a non-null value, the error messages will be changed like so:

  • For skipped tokens: “Unexpected token ‘<alias>’”

  • For inserted missing nodes: “<alias> expected”

  • For nodes representing non-terminal symbols with their IsError value set to true: “<alias> is incorrect”

An example of where this might be used is in the Visual Basic language, which has a symbol named “EndGetStatement” to represent the pair of keywords “End Get”. If a user omits an “End Get” at the end of a property get accessor, it might appear odd to the user if the default error message “EndGetStatement expected” were used. Instead, an implementer of the language would probably want to override GetErrorAlias and return ‘End Get’ for this symbol so the error message would appear as “‘End Get’ expected”.

Overriding the OnError method

To get more control over the error messages displayed or add or remove error messages, you can alternatively override the OnError method. The ParseErrorContext class, which is an argument to the OnError method, has the following members for allowing you to inspect and customize the error:

Property * Description*

The collection of errors, which will only contain the single error detected by the parser. This collection can be modified to change the errors attached to the document at the location of the error.

Indicates whether the error represents a missing syntax node structure which needed to be inserted because it was expected but not provided by the user.

Indicates whether the error represents skipped content which was unexpected in the document. Only terminal symbols will be skipped.

Indicates the location of the error in the document with respect to the current TextDocumentSnapshot being parsed.

Indicates the location of the error in the document. This is the same as SnapshotSpan, but is not associated with a snapshot.

The Symbol associated with the error which was either skipped or expected.

For example if you have an “IncompleteMember” error non-terminal defined in C# (see the Error Production Strategy topic for details on this), instead of having an error message that says “IncompleteMember is incorrect”, you might want to replace it entirely by saying “Incomplete member definition in class or struct”.

Related Content

Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic explains the process of creating a custom language.

This topic introduces the TextDocument and explains how to set a language on the TextDocument.

The topics in this group explain in detail how to work with the Syntax Tree.