Table of Contents

TomlDocumentReader Struct

Definition

Namespace
Bodu.Text.Toml.Reader
Assembly
Bodu.Text.Toml.dll
Package
Bodu.Text.Toml 1.3.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

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 the hard ceiling of 64 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.

Remarks

A float literal is rounded to binary64 as IEEE 754 conversion rounds it, so a literal beyond the binary64 range, such as 1e400, reads as positive or negative infinity, and one too small to represent reads as zero.

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

ProductVersions
.NET8, 10