Version

Custom Diagnostics and Annotations (Syntax Parsing Engine)

Topic Overview

Purpose

This topic explains how to attach and obtain additional data to and from the syntax tree.

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 when the syntax tree is created and how to access it.

In this topic

This topic contains the following sections:

Introduction

Overview

In addition to obtaining information from a syntax tree, you may want to store information on it as well. The SyntaxTree and all objects within it are immutable, so the only way to store additional information is to make a copy of the tree with the additional data included. This can be done for either diagnostic information (such as semantic errors or warnings) or annotations, which can be any kind of data. The methods which allow you to attach this data to the tree are defined on SyntaxTree.

Note
Note

When attaching annotations or diagnostic information a new tree is created containing the same snapshot as the original tree. Both trees represent the same textual content and have an identical node structure and can logically be considered "sibling trees". Since they have the same node structure, you can specify a node from any sibling tree when you want to attach information to a tree.

Adding Annotations

Annotations summary

To attach annotations use the AddAnnotation method of the SyntaxTree and provide the SyntaxAnnotation you want to attach. The SyntaxAnnotation class can be derived so you can attach any data to a node. As a result the AddAnnotation method will return a copy of the Syntax Tree with the new annotation attached to the specified node.

To obtain annotation information on a specific node use the HasAnnotations property to determine whether that specific node has annotations, GetAnnotations overloaded methods for getting the annotations attached to that specific node, and GetAnnotatedNodes overloaded methods for enumerating the nodes with annotations in that node’s sub-tree. Both methods mentioned here have overloads taking a Type so you get annotations or nodes with annotations whose SyntaxAnnotation instances are of the specified Type or derived.

The following is an example of how to attach annotations to the syntax tree:

In Visual Basic:

Dim document = New TextDocument()
document.Language = CSharpLanguage.Instance
' ... Parse a document
Dim originalTree = document.SyntaxTree
Dim node1 = originalTree.RootNode.GetChild(0)
Dim node2 = originalTree.RootNode.GetChild(1)
Dim annotatedTree = originalTree.AddAnnotation(node1, New SyntaxAnnotation())
Dim annotatedTreeAgain = annotatedTree.AddAnnotation(node2, New SyntaxAnnotation())

In C#:

var document = new TextDocument();
document.Language = CSharpLanguage.Instance;
// ... Parse a document
var originalTree = document.SyntaxTree;
var node1 = originalTree.RootNode.GetChild(0);
var node2 = originalTree.RootNode.GetChild(1);
var annotatedTree = originalTree.AddAnnotation(node1, new SyntaxAnnotation());
var annotatedTreeAgain = annotatedTree.AddAnnotation(node2, new SyntaxAnnotation());
Note
Note

Notice how node2 is obtained from originalTree but passed to annotatedTree. This is legal because originalTree, annotatedTree, and annotatedTreeAgain are sibling trees.

Adding Diagnostics

Diagnostics summary

To attach diagnostic information use the AddDiagnostic method of the SyntaxTree which takes the Diagnostic and the tree node to which you want to attach the diagnostic. As a result the AddDiagnostic method will return a copy of the Syntax Tree with the new diagnostic attached to the specified node.

To obtain diagnostic information use the ContainsDiagnostics property and the GetDiagnostics methods on the SyntaxNode class. These methods do not distinguish between Syntax Parsing Engine’s diagnostics and custom diagnostics, so those members automatically return all diagnostics information from the node and its descendants.

The following is an example of how to attach diagnostics to the syntax tree:

In Visual Basic:

Dim document = New TextDocument()
document.Language = CSharpLanguage.Instance
' ... Parse a document
Dim syntaxNode = document.SyntaxTree.RootNode.GetChild(0)
Dim newTree = document.SyntaxTree.AddDiagnostic( _
    syntaxNode, _
    New Diagnostic( _
            New TextSpan(syntaxNode.LeadingIgnoredContentLength, syntaxNode.GetText().Trim().Length), _
                         "Something wrong happened!", _
                         DiagnosticSeverity.Warning))

In C#:

var document = new TextDocument();
document.Language = CSharpLanguage.Instance;
// ... Parse a document
var syntaxNode = document.SyntaxTree.RootNode.GetChild(0);
var newTree = document.SyntaxTree.AddDiagnostic(
    syntaxNode,
    new Diagnostic(
        new TextSpan(syntaxNode.LeadingIgnoredContentLength, syntaxNode.GetText().Trim().Length),
                     "Something wrong happened!",
                     DiagnosticSeverity.Warning));

Obtain and Modify the Syntax Tree

Summary

You can obtain the newly created Syntax Tree after the parsing operation has completed and before it is returned to the TextDocument by attaching a handler to the SyntaxTreeCreated event defined in the LanguageBase class. The SyntaxTreeCreatedEventArgs class exposes a get/set SyntaxTree property which can be set to the new SyntaxTree returned from a call to AddAnnotation or AddDiagnostic method. In this way, custom diagnostics an annotations can be displayed by the xamSyntaxEditor .

The following is an example of how to attach an event handler to the SyntaxTreeCreated event:

In Visual Basic:

Me.xamSyntaxEditor1.Document.Language.SyntaxTreeCreated += Language_SyntaxTreeCreated
Private Sub Language_SyntaxTreeCreated(sender As Object, e As SyntaxTreeCreatedEventArgs)
    Dim syntaxNode = e.SyntaxTree.RootNode.GetChild(0)
    ' Add a diagnostic
    Dim newTree = e.SyntaxTree.AddDiagnostic(syntaxNode, New Diagnostic(New TextSpan(syntaxNode.LeadingIgnoredContentLength, syntaxNode.GetText().Trim().Length), "Something wrong happened!", DiagnosticSeverity.Warning))
    ' Add an annotation
    Dim anotherNewTree = newTree.AddAnnotation(newTree.RootNode.GetChild(0), New SyntaxAnnotation())
    e.SyntaxTree = anotherNewTree
End Sub

In C#:

this.xamSyntaxEditor1.Document.Language.SyntaxTreeCreated += Language_SyntaxTreeCreated;
void Language_SyntaxTreeCreated(object sender, SyntaxTreeCreatedEventArgs e)
{
    var syntaxNode = e.SyntaxTree.RootNode.GetChild(0);
    // Add a diagnostic
    var newTree = e.SyntaxTree.AddDiagnostic(
        syntaxNode,
        new Diagnostic(
            new TextSpan(syntaxNode.LeadingIgnoredContentLength, syntaxNode.GetText().Trim().Length),
            "Something wrong happened!",
            DiagnosticSeverity.Warning));
    // Add an annotation
    var anotherNewTree = newTree.AddAnnotation(
        newTree.RootNode.GetChild(0), new SyntaxAnnotation());
    e.SyntaxTree = anotherNewTree;
}

Related Content

Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic explains how to access the ignored content produced during syntax analysis.

This topic explains the syntax tree pruning types performed by the Syntax Parsing Engine.