Meziantou.FrameworkTomlSyntaxTree Class
A parsed TOML document.
public sealed class TomlSyntaxTree : SyntaxTreeRemarks
Parsing never throws and never gives up: whatever the text says, the tree reproduces it exactly, and anything wrong with it is reported through TomlSyntaxTree.GetDiagnostics -- from a missing bracket to a key defined twice.
What breaks the grammar is carried by the nodes, and is what SyntaxNode.ContainsDiagnostics tells. Whether a key or a table is defined twice, or a value extended after the fact, depends on the whole document instead, so the tree works it out from its root the first time it is asked. A node carries none of these, and neither does a node that is not part of a tree.
A tree made from a root with TomlSyntaxTree.Create or TomlSyntaxTree.WithRoot reports the diagnostics of its text instead, which it parses again the first time it is asked: an edit can build nodes that do not read back as themselves, such as a comment that hides the bracket after it, and the options of the tree can be those of another version than the nodes were parsed with.
Example
var tree = TomlSyntaxTree.ParseText("[server]\nport = 8080\n");
var port = (TomlIntegerSyntax)tree.GetRoot().Tables.Single().Properties.Single().Value;
Assert.Equal(8080, port.Value);- Inheritance
SyntaxTreeTomlSyntaxTree
Properties
| Name | Description |
|---|---|
| FilePath | |
| Options | Gets the options the text was parsed with. |
FilePath
TomlSyntaxTree.csOptions
TomlSyntaxTree.csMethods
| Name | Description |
|---|---|
| Create(TomlDocumentSyntax, TomlParseOptions?, string?) | Creates a tree over root, taking its text from the root itself. |
| Create(TomlDocumentSyntax, string?) | Creates a tree over root, taking its text from the root itself. |
| GetChanges(TomlSyntaxTree) | Describes how oldTree would have to change to become this one. |
| GetDiagnostics() | Gets every diagnostic in the tree, in source order. |
| GetDiagnostics(SyntaxNode) | Gets the diagnostics at or below node, including the keys and tables it defines twice. |
| GetDiagnostics(SyntaxToken) | Gets the diagnostics on token and the trivia around it. |
| GetDiagnostics(SyntaxTrivia) | Gets the diagnostics on trivia. |
| GetRoot() | Gets the root of the tree. |
| GetText() | |
| IsEquivalentTo(TomlSyntaxTree?) | Determines whether the two trees have the same structure and text. |
| ParseText(SourceText, TomlParseOptions?, string?) | Parses text. |
| ParseText(SourceText, string?) | Parses text as the latest version of TOML. |
| ParseText(string, TomlParseOptions?, string?) | Parses text. |
| ParseText(string, string?) | Parses text as the latest version of TOML. |
| WithChangedText(SourceText) | Returns a tree over newText, parsed with the same options. |
| WithChanges(TextChange[]) | Returns a tree over this text with changes applied. |
| WithChanges(IEnumerable<TextChange>) | Returns a tree over this text with changes applied. |
| WithRoot(TomlDocumentSyntax) | Returns a tree whose root is root. |
Create overloads
Create(TomlDocumentSyntax, TomlParseOptions?, string?)
TomlSyntaxTree.csCreates a tree over root, taking its text from the root itself.
public static TomlSyntaxTree Create(TomlDocumentSyntax root, TomlParseOptions? options, string? path = null)Parameters
rootTomlDocumentSyntaxoptionsTomlParseOptions?pathstring?
Returns
Exceptions
ArgumentNullExceptionrootisnull.
Remarks
root becomes the root of the tree when it is not part of another one yet. The nodes are kept, but the diagnostics are those of the text: it is parsed again with options the first time they are asked for, so that they are right even when an edit built nodes that do not read back as themselves, or when the nodes were parsed as another version of TOML.
Create(TomlDocumentSyntax, string?)
TomlSyntaxTree.csCreates a tree over root, taking its text from the root itself.
public static TomlSyntaxTree Create(TomlDocumentSyntax root, string? path = null)Parameters
rootTomlDocumentSyntaxpathstring?
Returns
Exceptions
ArgumentNullExceptionrootisnull.
Remarks
root becomes the root of the tree when it is not part of another one yet. The nodes are kept, but the diagnostics are those of the text: it is parsed again the first time they are asked for, so that they are right even when an edit built nodes that do not read back as themselves.
GetChanges(TomlSyntaxTree)
TomlSyntaxTree.csDescribes how oldTree would have to change to become this one.
public IReadOnlyList<TextChange> GetChanges(TomlSyntaxTree oldTree)GetDiagnostics overloads
GetDiagnostics()
TomlSyntaxTree.csGets every diagnostic in the tree, in source order.
public override IReadOnlyList<Diagnostic> GetDiagnostics()Returns
GetDiagnostics(SyntaxNode)
TomlSyntaxTree.csGets the diagnostics at or below node, including the keys and tables it defines twice.
public override IEnumerable<Diagnostic> GetDiagnostics(SyntaxNode node)GetDiagnostics(SyntaxToken)
TomlSyntaxTree.csGets the diagnostics on token and the trivia around it.
public override IEnumerable<Diagnostic> GetDiagnostics(SyntaxToken token)GetDiagnostics(SyntaxTrivia)
TomlSyntaxTree.csGets the diagnostics on trivia.
public override IEnumerable<Diagnostic> GetDiagnostics(SyntaxTrivia trivia)GetRoot()
TomlSyntaxTree.csGetText()
TomlSyntaxTree.csIsEquivalentTo(TomlSyntaxTree?)
TomlSyntaxTree.csDetermines whether the two trees have the same structure and text.
public bool IsEquivalentTo(TomlSyntaxTree? other)ParseText overloads
ParseText(SourceText, TomlParseOptions?, string?)
TomlSyntaxTree.csParses text.
public static TomlSyntaxTree ParseText(SourceText text, TomlParseOptions? options, string? path = null)Parameters
textSourceTextoptionsTomlParseOptions?pathstring?
Returns
Exceptions
ArgumentNullExceptiontextisnull.
ParseText(SourceText, string?)
TomlSyntaxTree.csParses text as the latest version of TOML.
public static TomlSyntaxTree ParseText(SourceText text, string? path = null)ParseText(string, TomlParseOptions?, string?)
TomlSyntaxTree.csParses text.
public static TomlSyntaxTree ParseText(string text, TomlParseOptions? options, string? path = null)Parameters
textstring- The TOML document to read.
optionsTomlParseOptions?- How to read it, or
nullforTomlParseOptions.Default. pathstring?- Where the text came from, for the diagnostics to refer to.
Returns
Exceptions
ArgumentNullExceptiontextisnull.
ParseText(string, string?)
TomlSyntaxTree.csParses text as the latest version of TOML.
public static TomlSyntaxTree ParseText(string text, string? path = null)Parameters
textstring- The TOML document to read.
pathstring?- Where the text came from, for the diagnostics to refer to.
Returns
Exceptions
ArgumentNullExceptiontextisnull.
WithChangedText(SourceText)
TomlSyntaxTree.csReturns a tree over newText, parsed with the same options.
public TomlSyntaxTree WithChangedText(SourceText newText)WithChanges overloads
WithChanges(TextChange[])
TomlSyntaxTree.csReturns a tree over this text with changes applied.
public TomlSyntaxTree WithChanges(params TextChange[] changes)WithChanges(IEnumerable<TextChange>)
TomlSyntaxTree.csReturns a tree over this text with changes applied.
public TomlSyntaxTree WithChanges(IEnumerable<TextChange> changes)WithRoot(TomlDocumentSyntax)
TomlSyntaxTree.csReturns a tree whose root is root.
public TomlSyntaxTree WithRoot(TomlDocumentSyntax root)