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: aStringquoted and escaped, anInt,FloatorBoolas a TOML number or boolean, aDate,Time,NaiveDateTimeorOffsetDateTimeas a TOML date or time, aListas an array, and aMap<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.
Exports
Section titled “Exports”Types
Interfaces
type Toml
Section titled “type 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.
Toml.parse
Section titled “Toml.parse”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 = ")
Toml.text
Section titled “Toml.text”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'"
Toml.check
Section titled “Toml.check”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"
Toml.build
Section titled “Toml.build”impl CheckedLiteral<ToToml, Toml> for Toml
fn build(fragments: List<Fragment<ToToml>>) -> Toml
impl CheckedLiteral.build
Toml.inspect
Section titled “Toml.inspect”impl Debug for Toml
fn inspect(value: Toml) -> String
impl Debug.inspect
struct TomlError
Section titled “struct TomlError”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.
TomlError.to_string
Section titled “TomlError.to_string”impl Display for TomlError
fn to_string(error: TomlError) -> String
impl Display.to_string
TomlError.inspect
Section titled “TomlError.inspect”impl Debug for TomlError
fn inspect(value: TomlError) -> String
impl Debug.inspect
TomlError.equal
Section titled “TomlError.equal”impl Equatable for TomlError
fn equal(a: TomlError, b: TomlError) -> Bool
impl Equatable.equal
enum Toml.Value
Section titled “enum Toml.Value”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}"
Toml.Value.text
Section titled “Toml.Value.text”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.
Toml.Value.to_toml
Section titled “Toml.Value.to_toml”impl ToToml for Toml.Value
fn to_toml(value: Toml.Value) -> Toml.Value
impl ToToml.to_toml
The value itself.
Toml.Value.inspect
Section titled “Toml.Value.inspect”impl Debug for Toml.Value
fn inspect(value: Toml.Value) -> String
impl Debug.inspect
Toml.Value.equal
Section titled “Toml.Value.equal”impl Equatable for Toml.Value
fn equal(a: Toml.Value, b: Toml.Value) -> Bool
impl Equatable.equal
interface ToToml
Section titled “interface ToToml”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)})
ToToml.to_toml
Section titled “ToToml.to_toml”fn to_toml(value: self) -> Toml.Value
interface ToToml