Module

std::toml

TOML

TOML parsing, lookup, and serialization front-end for Ignis data.

Overview

The Toml namespace parses UTF-8 TOML text into owned tables, arrays, and values. It also exposes writer helpers backed by std::serializer for serializing primitive and Serialize values as TOML-compatible output.

Types

Type	Description
`TomlDocument`	Root document with table storage
`TomlTable`	Key/value table
`TomlArray`	Ordered TOML array values
`TomlValue`	Tagged TOML scalar, array, or table value
`TomlError`	Structured parse or lookup error with span

APIs

Function	Description
`Toml::parse`	Parse TOML text into a `TomlDocument`
`Toml::writer`	TOML writer configuration
`Toml::writeRoot`	Serialize a root `Serialize` value

Notes

TOML root output must be a record-like serialized value. Scalar roots are rejected by the shared serializer because they are not valid TOML documents.

Example

import Toml, TomlDocument, TomlError from "std::toml";
import Result from "std::result";

function main(): i32 {
  let parsed: Result<TomlDocument, TomlError> = Toml::parse("name = \"ignis\"\n");
  return parsed.isOk() ? 0 : 1;
}

namespace Toml

Public TOML front-end for lexing, parsing, token inspection, and writing.

Most users should call Toml::parse to obtain a TomlDocument. The lexer is exposed for tests and tooling that need token-level diagnostics or syntax highlighting.

Functions

function lex(source: &String): Result<Vector<TomlToken>, TomlError>

Lexes owned TOML source text into a fresh token vector.

Whitespace except newlines is skipped, comments are ignored, CRLF and CR are normalized to newline tokens, and every successful token stream ends with TomlTokenKind::EOF.

function lex(source: &String): Result<Vector<TomlToken>, TomlError>

Lexes owned TOML source text into a fresh token vector.

Whitespace except newlines is skipped, comments are ignored, CRLF and CR are normalized to newline tokens, and every successful token stream ends with TomlTokenKind::EOF.

function lexInto(source: &String, tokens: &mut Vector<TomlToken>): Option<TomlError>

Lexes owned TOML source text into tokens without allocating a new vector.

This is useful for callers that reuse token storage across parses. Existing contents are discarded before lexing starts. On error, the vector contains the tokens produced before the failing character or literal.

function lexInto(source: &String, tokens: &mut Vector<TomlToken>): Option<TomlError>

Lexes owned TOML source text into tokens without allocating a new vector.

This is useful for callers that reuse token storage across parses. Existing contents are discarded before lexing starts. On error, the vector contains the tokens produced before the failing character or literal.

function parse(source: &String): Result<TomlDocument, TomlError>

Parses owned TOML source text into a TomlDocument.

Parsing is two-stage: source text is tokenized first, then parseTokens builds the table/value model. Lexer errors are returned unchanged; parser errors include duplicate keys, table conflicts, and unexpected tokens.

function parse(source: &String): Result<TomlDocument, TomlError>

Parses owned TOML source text into a TomlDocument.

Parsing is two-stage: source text is tokenized first, then parseTokens builds the table/value model. Lexer errors are returned unchanged; parser errors include duplicate keys, table conflicts, and unexpected tokens.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function stringify<T>(value: &T): Result<String, Error>

Serializes a record-like value as a TOML document string.

The type’s Serialize implementation controls which fields are emitted. Serializer errors are propagated, including unsupported nested shapes or an implementation that does not produce a TOML-compatible root record.

function tokenAt(tokens: &Vector<TomlToken>, index: u64): Option<&TomlToken>

Returns the token at index when it exists.

function tokenCount(tokens: &Vector<TomlToken>): u64

Returns the number of tokens in a token vector.

This small wrapper keeps token inspection available through the TOML module without exposing vector implementation details to simple tooling tests.

function unsupportedRootValue(): Result<String, Error>

Returns the shared error for scalar TOML root serialization attempts.

TOML documents require table-like roots. Primitive overloads of stringify route through this helper so they all report the same contract violation.

function writer(): Writer

Returns the serializer configuration used for TOML record output.

The writer emits field entries as key = value lines, does not wrap records in braces, and rejects scalar roots.

Records

record TomlCursor

Members

source: &String

offset: u64

static create(source: &String): TomlCursor

advance(&mut self): Option<char>

eatAscii(&mut self, expected: char): boolean

isAtEnd(&self): boolean

length(&self): u64

peek(&self, outEndByte: &mut u64): Option<char>

peek(&self, outEndByte: &mut u64): Option<char>

position(&self): u64

slice(&self, startByte: u64, endByte: u64): String

record TomlLexeme

Internal lexer result describing a token kind and its exclusive end offset.

The lexer keeps decoded string contents separately in temporary String values. TomlLexeme records only the syntactic classification and how far the cursor advanced through the source text.

Members

kind: TomlTokenKind

end: u64

Functions

function tomlAdvanceCount(cursor: &mut TomlCursor, count: u64): void

Advances the cursor by count UTF-8 characters.

function tomlAscii(ch: char): Option<char>

Converts a decoded character to ASCII when TOML punctuation can use it.

function tomlBooleanKind(lexeme: &String): TomlTokenKind

Classifies an identifier lexeme as a boolean keyword or a plain identifier.

function tomlCharAtOrNull(value: &String, index: u64): char

Reads a character from value, returning \0 when index is out of range.

Number and date validators call this only on tokenizer candidate strings. The sentinel keeps validation branches explicit instead of relying on panics.

function tomlCountDigits(value: &String, index: u64): u64

Counts consecutive decimal digits in value starting at index.

function tomlHasLeadingZeroViolation(value: &String, start: u64, digitCount: u64): boolean

Returns whether a multi-digit integer component starts with a forbidden 0.

function tomlHexValue(ch: char): Option<u32>

Converts an ASCII hexadecimal digit into its numeric nibble value.

function tomlIsBareKeyContinue(ch: char): boolean

Returns whether ch can continue an unquoted TOML bare key.

function tomlIsBareKeyStart(ch: char): boolean

Returns whether ch can begin an unquoted TOML bare key.

function tomlIsDateTimeMarker(ch: char): boolean

Returns whether ch suggests that a scalar literal may be date/time-shaped.

function tomlIsDigit(ch: char): boolean

Returns whether ch is an ASCII decimal digit.

function tomlIsExponentMarker(ch: char): boolean

Returns whether ch starts a floating-point exponent suffix.

function tomlIsLiteralDelimiter(ch: char): boolean

Returns whether ch terminates an unquoted scalar literal.

Delimiters include whitespace, comments, collection separators, and key/value syntax. The scanned literal does not include the delimiter.

function tomlIsSign(ch: char): boolean

Returns whether ch is a numeric sign accepted before numbers and offsets.

function tomlLexBasicMultilineString(cursor: &mut TomlCursor, start: u64, output: &mut String): Result<TomlLexeme, TomlError>

Lexes a TOML basic multiline string ("""...""").

The decoded string contents are appended to output. Escapes are interpreted and the initial newline after the opening delimiter is trimmed according to TOML rules. Unterminated strings and invalid escapes return parser errors.

function tomlLexBasicString(cursor: &mut TomlCursor, start: u64, output: &mut String): Result<TomlLexeme, TomlError>

Lexes a TOML basic string ("...").

Escapes are decoded into output. Bare newlines are rejected because ordinary basic strings cannot span lines.

function tomlLexIdentifier(cursor: &mut TomlCursor, start: u64): TomlLexeme

Lexes an identifier or bare-key token starting at start.

The cursor is expected to be positioned at the first character of the key. It is advanced through all allowed continuation bytes and the returned lexeme stores the end offset for later slicing.

function tomlLexInteger(cursor: &mut TomlCursor, start: u64): Result<TomlLexeme, TomlError>

Lexes an integer or floating-point literal from a cursor position.

This routine handles the fast path while walking the cursor. The stricter whole-literal validator is still used by tomlLexScalarLiteral for scanned scalar text; this helper exists for source positions known to begin with a sign or digit.

function tomlLexLiteralString(cursor: &mut TomlCursor, start: u64, output: &mut String): Result<TomlLexeme, TomlError>

Lexes a TOML literal or literal multiline string.

Literal strings do not process escapes; source text between delimiters is copied directly into output. The multiline form trims one initial newline.

function tomlLexQuotedString(cursor: &mut TomlCursor, start: u64, output: &mut String): Result<TomlLexeme, TomlError>

Dispatches to basic or basic multiline string lexing based on the delimiter.

function tomlLexScalarLiteral(cursor: &mut TomlCursor, start: u64): Result<TomlLexeme, TomlError>

Lexes a numeric or date/time scalar literal at start.

Signed inf and nan are recognized before generic scanning. Date/time-like text is validated as a date/time token; all other scalar text is validated as an integer or float. Invalid candidates return precise TOML diagnostics.

function tomlLexSignedFloatKeyword(cursor: &mut TomlCursor): Option<TomlLexeme>

Lexes signed special float keywords (+inf, -inf, +nan, -nan).

On success the cursor is advanced past the keyword and a float lexeme is returned. Unsigned inf and nan are not handled here because this helper is only reached from sign-prefixed numeric paths.

function tomlLooksLikeDateTime(value: &String): boolean

Performs a cheap precheck for date/time-looking scalar text.

This avoids routing ordinary integers through the stricter date/time validator while still recognizing local dates, local times, and offset forms.

function tomlParseFixedDigits(value: &String, index: u64, digits: u64): i64

Parses exactly digits decimal digits at index, or returns -1.

Date/time validation uses the sentinel to validate fixed-width components without allocating substrings.

function tomlPeekAscii(cursor: &mut TomlCursor): Option<char>

Peeks at the cursor and returns the current character only when it is ASCII.

function tomlPushEscaped(value: &mut String, escaped: char): boolean

Appends the decoded value for a basic-string single-character escape.

Returns false when escaped is not one of TOML’s recognized short escape codes. Unicode escapes are handled by tomlPushQuotedEscape.

function tomlPushIdentifierToken(tokens: &mut Vector<TomlToken>, cursor: &mut TomlCursor, start: u64): void

Lexes and pushes a bare identifier or boolean token.

function tomlPushIntegerToken(tokens: &mut Vector<TomlToken>, cursor: &mut TomlCursor, start: u64): Result<boolean, TomlError>

Lexes and pushes a numeric or date/time scalar token.

function tomlPushLiteralStringToken(tokens: &mut Vector<TomlToken>, cursor: &mut TomlCursor, start: u64): Result<boolean, TomlError>

Lexes and pushes a decoded literal string token.

function tomlPushLiteralToken(tokens: &mut Vector<TomlToken>, kind: TomlTokenKind, lexeme: str, span: TomlSpan): void

Pushes a token whose lexeme is a static string slice.

function tomlPushQuotedEscape(output: &mut String, cursor: &mut TomlCursor, escapedStart: u64, escapedAscii: char): Result<boolean, TomlError>

Decodes one escape sequence in a basic string or basic multiline string.

The cursor is positioned at the escaped character, not at the preceding backslash. Short escapes and Unicode scalar escapes are appended to output; invalid escapes return TomlError::InvalidEscape.

function tomlPushQuotedToken(tokens: &mut Vector<TomlToken>, cursor: &mut TomlCursor, start: u64): Result<boolean, TomlError>

Lexes and pushes a decoded basic string token.

function tomlPushStringToken(tokens: &mut Vector<TomlToken>, kind: TomlTokenKind, lexeme: &String, span: TomlSpan): void

Pushes a token by cloning an owned string lexeme into the token vector.

function tomlPushUtf8Scalar(output: &mut String, scalar: u32): boolean

Encodes a Unicode scalar value into output as UTF-8 bytes.

Returns false for surrogate code points and values above the Unicode scalar range. The implementation writes encoded bytes explicitly so UTF-8 byte boundaries stay stable even though String::pushChar now accepts scalars.

function tomlReadHexScalar(cursor: &mut TomlCursor, start: u64, digits: u64): Result<u32, TomlError>

Reads a fixed-width hexadecimal Unicode scalar from the cursor.

The cursor is advanced over exactly digits hex characters on success. Any missing, non-ASCII, or non-hex character returns an invalid-escape error at the offending source span.

function tomlRemainingStartsWith(cursor: &mut TomlCursor, expected: str): boolean

Returns whether the cursor’s remaining source starts with expected.

The cursor position is not changed. This helper is used for multi-character delimiters such as triple-quoted strings and signed float keywords.

function tomlScanLiteralEnd(cursor: &mut TomlCursor): u64

Advances through an unquoted scalar literal and returns its end offset.

Scanning stops at the first literal delimiter, non-ASCII character, or end of input. The cursor is left at the returned offset.

function tomlSkipComment(cursor: &mut TomlCursor): void

Advances cursor over a TOML comment without consuming the line ending.

The caller handles newlines as significant top-level separators, so this helper stops immediately before \n or \r.

function tomlTrimInitialMultilineNewline(cursor: &mut TomlCursor): void

Consumes the optional first newline after a multiline string opening marker.

TOML trims one immediately following line ending for both basic and literal multiline strings. CRLF is consumed as a single logical newline.

function tomlValidateDateTimeLiteral(value: &String): boolean

Validates TOML local-date, local-time, local-date-time, and offset literals.

The tokenizer stores the original text as the value lexeme; this function only decides whether the candidate is structurally valid enough to become a date/time token.

function tomlValidateNumberLiteral(value: &String): TomlTokenKind

Validates a TOML numeric literal and returns its token kind.

Valid integers return TomlTokenKind::INTEGER; valid floats return TomlTokenKind::FLOAT. TomlTokenKind::EOF is used as an internal invalid sentinel so callers can choose the appropriate diagnostic span.

function tomlValidateTimeTail(value: &String, index: u64): boolean

Validates the time, fractional second, and optional offset tail of a literal.

index must point to the first hour digit. The accepted forms are local time (HH:MM:SS with optional fraction), Z offsets, and signed +HH:MM or -HH:MM offsets.