TomlDocumentReader Struct

Definition

Namespace

Bodu.Text.Toml.Reader

Assembly

Bodu.Text.Toml.dll

Package

Bodu.Text.Toml 1.0.0

Source

TomlDocumentReader.cs

Provides a forward-only cursor over the normalized, tree-order token stream of a parsed TOML document, serving as the binding layer through which converters consume values. The reader is a ref struct, so it cannot be boxed or captured; pass it by ref to thread it through a converter.

public ref struct TomlDocumentReader

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

TOML cannot be tokenized into tree order in a single forward pass: out-of-line [table] and [[array-of-tables]] headers contribute to structure declared elsewhere in the document. The constructor therefore parses the entire document up front - scanning the UTF-8 bytes with Utf8TomlReader and enforcing TOML's key, value, table, and array-of-tables rules through Bodu.Text.Toml.Reader.TomlDocumentBuilder - into a flat row store, and Read() advances a depth-first cursor over that store, emitting the normalized token stream on demand rather than materializing it. This type walks a parsed document; Utf8TomlReader reads the UTF-8 source in document order.

The stream is normalized: the several TOML spellings of structure collapse to a single nested shape. A header table, a dotted key, and an inline { … } table all surface as PropertyName followed by StartTable … EndTable, with out-of-line headers merged into the correct nested table. An array-of-tables surfaces as StartArray whose elements are each a StartTable. Scalars are decoded once during parsing and exposed through the typed accessors.

Because parsing happens in the constructor, a malformed document raises TomlFormatException from the constructor rather than from Read().

Date-time values map onto the CLR date and time types, which imposes three deliberate deviations from the RFC 3339 grammar that TOML incorporates by reference: a leap second (23:59:60) is rejected because DateTime and TimeOnly cannot represent second 60; year 0000 is rejected because the CLR calendar begins at year 1; and offsets beyond ±14:00 are rejected by DateTimeOffset. Each surfaces as a TomlFormatException.

Constructors

TomlDocumentReader(in ReadOnlySequence<byte>)

Initializes a new instance of the TomlDocumentReader struct over the supplied sequence, enforcing strict TOML v1.0.0.

public TomlDocumentReader(in ReadOnlySequence<byte> utf8Toml)

Parameters

utf8Toml ReadOnlySequence<byte>

The UTF-8 TOML source bytes.

Remarks

A single-segment sequence is parsed in place; a multi-segment sequence is copied once into a contiguous buffer before parsing.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

TomlDocumentReader(in ReadOnlySequence<byte>, TomlReaderOptions)

Initializes a new instance of the TomlDocumentReader struct over the supplied sequence using the supplied options.

public TomlDocumentReader(in ReadOnlySequence<byte> utf8Toml, TomlReaderOptions options)

Parameters

utf8Toml ReadOnlySequence<byte>

The UTF-8 TOML source bytes.

options TomlReaderOptions

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

Remarks

A single-segment sequence is parsed in place; a multi-segment sequence is copied once into a contiguous buffer before parsing.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

TomlDocumentReader(ReadOnlySpan<byte>)

Initializes a new instance of the TomlDocumentReader struct over the supplied bytes, enforcing strict TOML v1.0.0.

public TomlDocumentReader(ReadOnlySpan<byte> utf8Toml)

Parameters

utf8Toml ReadOnlySpan<byte>

The UTF-8 TOML source bytes.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

TomlDocumentReader(ReadOnlySpan<byte>, TomlReaderOptions)

Initializes a new instance of the TomlDocumentReader struct over the supplied bytes using the supplied options.

public TomlDocumentReader(ReadOnlySpan<byte> utf8Toml, TomlReaderOptions options)

Parameters

utf8Toml ReadOnlySpan<byte>

The UTF-8 TOML source bytes.

options TomlReaderOptions

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

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 so that an unbounded configured value cannot drive the parser into a StackOverflowException; a document nested deeper than the effective limit throws TomlFormatException.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

Properties

CurrentDepth

Gets the current container nesting depth.

public readonly int CurrentDepth { get; }

Property Value

int

The depth, where zero is the document root. A top-level table or array opens depth one; nested containers increase it further.

TokenType

Gets the kind of the current token.

public readonly TomlTokenType TokenType { get; }

Property Value

TomlTokenType

The current token kind, or None before the first or after the last token.

Methods

GetBoolean()

Reads the current token as a Boolean.

public readonly bool GetBoolean()

Returns

bool

The Boolean value.

Exceptions

InvalidOperationException

Thrown when the current token is not a Boolean.

GetDateOnly()

Reads the current token as a local date.

public readonly DateOnly GetDateOnly()

Returns

DateOnly

The local date value.

Exceptions

InvalidOperationException

Thrown when the current token is not a LocalDate.

GetDateTime()

Reads the current token as a local date-time.

public readonly DateTime GetDateTime()

Returns

DateTime

The local date-time value, whose Kind is Unspecified.

Exceptions

InvalidOperationException

Thrown when the current token is not a LocalDateTime.

GetDateTimeOffset()

Reads the current token as an offset date-time.

public readonly DateTimeOffset GetDateTimeOffset()

Returns

DateTimeOffset

The offset date-time value.

Exceptions

InvalidOperationException

Thrown when the current token is not an OffsetDateTime.

GetDouble()

Reads the current token as an IEEE 754 binary64 floating-point value.

public readonly double GetDouble()

Returns

double

The floating-point value.

Exceptions

InvalidOperationException

Thrown when the current token is not a Float.

GetInt64()

Reads the current token as a 64-bit signed integer.

public readonly long GetInt64()

Returns

long

The integer value.

Exceptions

InvalidOperationException

Thrown when the current token is not an Integer.

GetString()

Reads the current token as UTF-8 text.

public readonly string GetString()

Returns

string

The string value.

Exceptions

InvalidOperationException

Thrown when the current token is not a String or PropertyName.

GetTimeOnly()

Reads the current token as a local time.

public readonly TimeOnly GetTimeOnly()

Returns

TimeOnly

The local time value.

Exceptions

InvalidOperationException

Thrown when the current token is not a LocalTime.

Read()

Advances the reader to the next token.

public bool Read()

Returns

bool

true when a token was read; false at the end of the document.

Skip()

Skips the current value, including the entire subtree when the reader is positioned on a StartTable or StartArray.

public void Skip()

Remarks

When the reader is positioned on a PropertyName, it advances to the property's value and then skips it. When it is positioned on a container start, the reader advances to the matching EndTable or EndArray at the same depth. When it is positioned on a scalar value, the call has no effect.

Applies to

Product	Versions
.NET	8, 10