Reference

std/toml/toml

std/toml/src/toml.trb

Toml, the format: a value with the options of TOML, which reads and writes typed values through Encode and Decode, and reads documents into the tree of TomlValues and writes that tree back.

type Toml

type Toml

TOML, with its options. The default writes every field under the name the type declares, ignores a field of the document that no type asked for, and writes TOML 1.1.

The reader takes every released 1.x: a document is read by the union of their grammars, so one that is valid TOML 1.0 and one that uses 1.1 (an inline table over several lines, a time without seconds, the escapes \e and \xHH) are both read. version only chooses what the writer may use.

Examples

type Service {
  name: String
  replicas: Int = 1
  ports: List<Int> = []
}

const toml = Toml()
const service = toml.decode<Service>("name = \"web\"\nports = [80, 443]\n")?
print(toml.encode(service)?)

Related

  • TomlValue - the tree of a document, for one whose shape is not known ahead of time.
  • TomlError - what a failed decode, parse or encode says.

field naming

naming: Naming = Naming.Unchanged

How the field names are written and read: Naming.SnakeCase writes logLabel as log_label.

field strict

strict: Bool = false

Whether a key of the document that no type asked for is an error, instead of being ignored.

field version

version: TomlVersion = TomlVersion.Toml11

The version of TOML the writer keeps to.

fn encode

fn encode<Value: Encode>(value: Value): Result<String, TomlError>

value as TOML text. A field that holds None is left out.

Errors

A TomlError for a value that TOML cannot say: one that is not a table, because a document is one; None inside an array, because TOML has no null; a key that is not text; and a number beyond a 64 bit integer.

fn decode

fn decode<Value: Decode>(text: String): Result<Value, TomlError>

Reads text, which holds one document, as a Value. A key the document leaves out reads as the field's default, or as None.

Errors

A TomlError for text that is not TOML, with its line and column, and for a document that does not fit Value, with the chain of fields it went wrong in.

fn parse

fn parse(text: String): Result<TomlValue, TomlError>

Parses text, which holds one document, into its tree: every value as it was written, in the order of the document.

Errors

A syntax error with its line and column, or the first place the document defines something twice.

fn value

fn value<Value: Encode>(value: Value): Result<TomlValue, TomlError>

Any Encode value as the tree this format writes it as: a table.

fn write

fn write(tree: TomlValue): String

A tree as the text of a document: the values of a table first, then its tables and arrays of tables.