TomlDocument Class

Definition

Namespace

Bodu.Text.Toml.Document

Assembly

Bodu.Text.Toml.dll

Package

Bodu.Text.Toml 1.0.0

Source

TomlDocument.cs

Provides a read-only, high-performance document object model over TOML text, exposed as a flat index of row records through lightweight TomlElement struct views rather than a tree of node objects.

public sealed class TomlDocument : IDisposable

Inheritance

object

TomlDocument

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// The document owns a flat row store; dispose it (here via 'using') when finished.
// Every element view obtained from it is valid only until the document is disposed.
using TomlDocument document = TomlDocument.Parse("name = \"app\"\nport = 8080\n");
TomlElement root = document.RootElement;

string name = root.GetProperty("name").GetString();   // "app"
long port = root.GetProperty("port").GetInt64();       // 8080

Remarks

A TomlDocument holds the flat row store produced directly by the structural parser, so parsing materializes neither an intermediate node tree nor a token list. Value-type scalars are decoded into the row, while a string scalar is decoded on demand from the UTF-8 source the document retains, so a string is materialized only when read. Every TomlElement, enumerator, and TomlProperty obtained from a document is valid only until the document is disposed.

Call Dispose() when finished to invalidate the document and the TomlElement views taken from it; after disposal, any operation on such an element throws ObjectDisposedException. A parsed document rents its retained source from the shared array pool, so disposal returns that buffer as well as dropping the row store; neglecting to dispose leaks the buffer back to the garbage collector rather than the pool.

The root value of a TOML document is always a table, so for a document produced by Parse(string) or its overloads RootElement always reports Table. A document produced internally over a single value subtree may root any value kind.

Properties

RootElement

Gets the root element of the document.

public TomlElement RootElement { get; }

Property Value

TomlElement

A TomlElement positioned on the document's root value. For a document produced by Parse(string) or its overloads the root is always a table, so its ValueKind is Table.

Methods

Dispose()

Releases the row store and the retained source, and invalidates the document.

public void Dispose()

Remarks

Disposal is idempotent: calling it more than once has no further effect. A parsed document returns its pooled source buffer to the shared array pool; a subtree view shares a garbage-collected copy and returns nothing. After disposal, every element, enumerator, and property obtained from the document throws ObjectDisposedException.

Parse(ReadOnlySpan<byte>)

Parses the supplied UTF-8 TOML bytes into a TomlDocument.

public static TomlDocument Parse(ReadOnlySpan<byte> utf8Toml)

Parameters

utf8Toml ReadOnlySpan<byte>

The UTF-8 TOML source bytes.

Returns

TomlDocument

A document over the parsed structure.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

Parse(ReadOnlySpan<byte>, TomlDocumentOptions)

Parses the supplied UTF-8 TOML bytes into a TomlDocument using the supplied options.

public static TomlDocument Parse(ReadOnlySpan<byte> utf8Toml, TomlDocumentOptions options)

Parameters

utf8Toml ReadOnlySpan<byte>

The UTF-8 TOML source bytes.

options TomlDocumentOptions

The document options controlling the specification version and maximum nesting depth.

Returns

TomlDocument

A document over the parsed structure.

Remarks

A MaxDepth of zero or less selects the default maximum depth of 64, and a larger value is clamped to Bodu.Text.Toml.TomlLimits.AbsoluteMaxDepth; a document nested deeper than the effective limit throws TomlFormatException.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document, or nest deeper than the configured maximum.

Parse(string)

Parses the supplied TOML text into a TomlDocument.

public static TomlDocument Parse(string toml)

Parameters

toml string

The TOML source text.

Returns

TomlDocument

A document over the parsed structure.

Remarks

The text is encoded to UTF-8 and parsed by Parse(ReadOnlySpan<byte>).

Exceptions

ArgumentNullException

Thrown when toml is null.

TomlFormatException

Thrown when the text is not a valid TOML document.

Parse(string, TomlDocumentOptions)

Parses the supplied TOML text into a TomlDocument using the supplied options.

public static TomlDocument Parse(string toml, TomlDocumentOptions options)

Parameters

toml string

The TOML source text.

options TomlDocumentOptions

The document options controlling the specification version and maximum nesting depth.

Returns

TomlDocument

A document over the parsed structure.

Remarks

The text is encoded to UTF-8 and parsed by Parse(ReadOnlySpan<byte>, TomlDocumentOptions). A MaxDepth of zero or less selects the default maximum depth of 64.

Exceptions

ArgumentNullException

Thrown when toml is null.

TomlFormatException

Thrown when the text is not a valid TOML document, or nests deeper than the configured maximum.

Applies to

Product	Versions
.NET	8, 10