Skip to content

std::toml

TOML text built from a literal. A Toml holds TOML source text, and Toml.text returns it. This module writes TOML; it does not read TOML into values. Toml.parse checks TOML text the program reads while it runs, by the rules a literal’s text is checked by.

A Toml literal is a Toml in every quote style, never a Result. Its text is read as TOML when the program is checked, so text that is not TOML is a compile error. Each ${...} slot is written for where it stands:

  • In value position (after =, or as an array item), the slot is its value’s TOML: a String quoted and escaped, an Int, Float or Bool as a TOML number or boolean, a Date, Time, NaiveDateTime or OffsetDateTime as a TOML date or time, a List as an array, and a Map<String, V> as an inline table.
  • In key position (at the start of a line, after . in a dotted key, in a [table] header, or as an inline table’s key), the slot is one quoted key part.
  • Anywhere else, inside a string or a comment or next to other text of the same key or value, the slot is a compile error, since no escaping makes it safe there.
import std::toml.Toml

fn server(name: String, port: Int, hosts: List<String>) -> Toml
    Toml"""
    [servers.${name}]
    port = ${port}
    hosts = ${hosts}
    """
end

A slot’s value must implement ToToml, which turns it into a Toml.Value. std implements it for the types above, and a program’s own type can implement it too. The literal writes the Toml.Value itself, so no impl can put TOML text in the document.

Import with import std::toml.

type Toml String

TOML source text, made by a Toml"..." literal. Its own type keeps it apart from an arbitrary String, so a function that takes TOML says so.

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

type function on Toml

Reads text as TOML, by the rules a Toml"..." literal without slots is checked by when the program is checked, or returns what is wrong and where. Use it for TOML text the program reads while it runs.

import std::toml.{Toml, TomlError}

assert Ok(t) = Toml.parse("title = 'demo'")
assert Toml.text(t) == "title = 'demo'"
assert Err(TomlError{offset: 7, message: "unexpected EOF; expected value"}) = Toml.parse("title = ")
fn text(source: Toml) -> String

type function on Toml

Returns the literal TOML text.

assert Toml.text(
    Toml"""
    [module]
    name = "demo"
    """
) == """
    [module]
    name = "demo"
    """

assert Toml.text(Toml"title = 'demo'") == "title = 'demo'"

impl CheckedLiteral<ToToml, Toml> for Toml

fn check(statics: List<String>) -> Result<Unit, LiteralError>

impl CheckedLiteral.check

A Toml literal is checked when the program is checked: its text, with a stand-in for each slot, must be TOML, and each slot must stand for a whole key or value. In value position a slot is its value’s TOML; in key position it is one quoted key part.

import std::toml.Toml

name = "web 1"
port = 8080
tags = ["a", "b"]

t = Toml"""
    [servers.${name}]
    port = ${port}
    tags = ${tags}
    """

assert Toml.text(t) == """
    [servers."web 1"]
    port = 8080
    tags = ["a", "b"]
    """

// A string cannot add a key: its quotes and newline are escaped.
evil = "x\"\nadmin = true"
assert Toml.text(Toml"user = ${evil}") == "user = \"x\\\"\\nadmin = true\""

// In key position every value is one quoted key.
id = 42
assert Toml.text(Toml"${id} = true") == "\"42\" = true"

impl CheckedLiteral<ToToml, Toml> for Toml

fn build(fragments: List<Fragment<ToToml>>) -> Toml

impl CheckedLiteral.build

impl Debug for Toml

fn inspect(value: Toml) -> String

impl Debug.inspect

struct TomlError
    offset: Int
    message: String
end

Why text is not TOML, for Toml.parse: the code point offset into the text where reading stopped, and message, as a compile error at a Toml"..." literal of the text words it.

impl Display for TomlError

fn to_string(error: TomlError) -> String

impl Display.to_string

impl Debug for TomlError

fn inspect(value: TomlError) -> String

impl Debug.inspect

impl Equatable for TomlError

fn equal(a: TomlError, b: TomlError) -> Bool

impl Equatable.equal

enum Toml.Value
    String String
    Int Int
    Float Float
    Bool Bool
    Date Date
    Time Time
    NaiveDateTime NaiveDateTime
    OffsetDateTime OffsetDateTime
    Array List<Toml.Value>
    Table Map<String, Toml.Value>
end

A TOML value, which ToToml makes and a Toml"..." literal writes. The literal writes each kind itself, so a value cannot hold TOML text: a String is quoted and escaped wherever it sits, and a Table’s keys are quoted keys.

Int is written as its decimal digits. TOML integers are 64-bit, so a reader may refuse an Int outside that range. Table is an inline table, {"a" = 1, "b" = 2}, its keys in the map’s order.

import std::toml.Toml

v = Toml.Value.Array([Toml.Value.Int(1), Toml.Value.String("a\"b")])
assert Toml.Value.text(v) == "[1, \"a\\\"b\"]"

t = Toml.Value.Table({"x y" => Toml.Value.Int(1)})
assert Toml.Value.text(t) == "{\"x y\" = 1}"
fn text(value: Toml.Value) -> String

type function on Toml.Value

The value as TOML, as a Toml"..." literal writes it where a slot stands for a value.

impl ToToml for Toml.Value

fn to_toml(value: Toml.Value) -> Toml.Value

impl ToToml.to_toml

The value itself.

impl Debug for Toml.Value

fn inspect(value: Toml.Value) -> String

impl Debug.inspect

impl Equatable for Toml.Value

fn equal(a: Toml.Value, b: Toml.Value) -> Bool

impl Equatable.equal

interface ToToml
    fn to_toml(value: self) -> Toml.Value
end

A value a Toml"..." slot can hold. to_toml returns the value as a Toml.Value, which the literal writes where the slot stands for a value, and quotes as one key where it stands for a key.

A program’s own type implements it by returning a Toml.Value, often another ToToml’s:

impl ToToml for Port
    fn to_toml(port: Port) -> Toml.Value
        ToToml.to_toml(port.number)
    end
end

No impl can write TOML text. The literal writes every Toml.Value itself, quoting and escaping each string and key, so a slot cannot add a key or break the document’s structure.

import std::toml.{ToToml, Toml}

assert ToToml.to_toml("a\"b") == Toml.Value.String("a\"b")
assert ToToml.to_toml([1, 2]) == Toml.Value.Array([Toml.Value.Int(1), Toml.Value.Int(2)])
assert ToToml.to_toml({"n" => 2.0}) == Toml.Value.Table({"n" => Toml.Value.Float(2.0)})
fn to_toml(value: self) -> Toml.Value

interface ToToml