std.toml

Reads and writes TOML 1.0 documents through std.codec's model.

The main types are TomlValue, the parsed tree, with TomlTable and TomlDatetime; TreeBuilder, the encoder that builds a tree; TomlReader, the decoder over a tree; and TomlError, a parse failure. toml.encode(v) writes any Encode value whose form is a table as a document, toml.decode<T>(text) reads any Decode value out of one, and toml.parse(text) returns the tree. A struct is a table of its wire names, a sequence an array, a map a table whose keys are strings — a number's digits for a number —, bytes an array of integers, a unit variant its name, a variant with a payload a table of one key. A table keeps the order its keys were written in. Date-times are TOML's own form, in their four kinds; an Instant writes as a quoted RFC 3339 string and reads from a date-time or a string.

Examples

import std.io { println };
import std.codec { Codable, DecodeError };
import std.toml;

struct Server :: [Codable] {
    host: string,
    port: int,
}

fn main(): void throws [toml.TomlError, DecodeError] {
    let s = try toml.decode<Server>("host = \"localhost\"\nport = 8080\n");
    println(f"{s.host}:{s.port}");
}

localhost:8080

Types

TomlError struct — The error for a text that is not valid TOML: the line and column where parsing stopped, and what was wrong.

TomlDatetime enum — A date-time in one of TOML's four forms: with an offset, local, a date alone, a time alone.

TomlTable class — A table: its keys in the order written, each with its value.

TomlValue enum — A TOML value in one of its seven forms; a parsed document is a Table.

TreeBuilder class — An encoder that builds a TomlValue: a struct as a table, a map as a table of string keys, a sequence as an array, bytes as an array of integers, a unit variant as its name, a payload variant as a table of one key.

TomlReader class — A decoder over a TomlValue tree: a struct from a table by its keys, a sequence from an array, a map from a table (its keys as strings, or as the numbers they spell), a variant from a string or a table of one key, bytes from an array of integers, a string from a string or a date-time's text.

Functions

pub fn encode<T :: [Encode]>(v: T): string throws EncodeError

Encodes a value as a TOML document.

Errors

Throws EncodeError where the value's form is not a table (encode a struct or a map), or where a part of it has no TOML form.

pub fn encodeTo<T :: [Encode], W :: [Writer]>(
    v: T,
    &w: W
): void throws [EncodeError, IoError, Cancelled]

Encodes a value as a TOML document and writes it into w.

Errors

Throws EncodeError as encode does, IoError where writing fails and Cancelled where the task is cancelled during the write.

pub fn parse(text: StringView): TomlValue throws TomlError

Parses a TOML document into its tree, a TomlValue.Table.

Errors

Throws TomlError with the line and column where the text is not valid TOML, is not UTF-8, defines a key or table twice, or nests deeper than 128 levels.

pub fn decode<T :: [Decode]>(text: StringView): T throws [TomlError, DecodeError]

Decodes a value of type T from a TOML document: parses it, then reads the value out of the tree.

Errors

Throws TomlError where the text is not valid TOML, and DecodeError where the tree does not fit T.

pub fn decodeFrom<T :: [Decode], R :: [Reader]>(
    &r: R
): T throws [TomlError, DecodeError, IoError, Cancelled]

Decodes a value of type T from the TOML document in r, read to its end first.

Errors

Throws TomlError and DecodeError as decode does, IoError where reading fails and Cancelled where the task is cancelled during the read.