Standard library · Encoding and data

encoding.toml

Reading and writing TOML configuration files.

import encoding.toml

TOML is the configuration format of [section] tables and key = value lines used by Cargo.toml, pyproject.toml and many server configs. This package reads TOML text into a dynamic Value and writes a Value back as TOML. It has three functions: Decode and Valid for reading, Encode for writing. Decode and Encode are declared throws: on bad input they throw an Error and give back nothing half-read.

Pick TOML for files people edit by hand. For data that programs exchange use encoding.json; for YAML files such as CI or Kubernetes configs use encoding.yaml; for KEY=value secrets files use encoding.envfile. If you only want settings loaded from a file with defaults and environment overrides, config may already do the job.

How TOML maps to a Value

TOMLValue
[table], [a.b], inline { k = v }, dotted keys a.b = 1object (nested)
[[name]]array of objects
"basic" with escapes, 'literal'string
42, -7, 1_000, 0x1F, 0o17, 0b101int (64-bit)
3.5, 1e6, inf, nanfloat
true, falsebool
dates and times such as 1979-05-27T07:32:00Zstring, unchanged

What trips people up

  • Errors stop the whole read. Decode throws at the first mistake, with e.line and e.column pointing at it, so a typo never silently drops the rest of the file. A key or [table] defined twice, an unquoted word such as mode = fast, a bad escape and an integer that does not fit in 64 bits are all errors.
  • Multi-line strings work. Both """ and ''' are read, including the first-newline trim, line-ending backslash and embedded quotes. Dates stay strings; parse them with time if you need them.
  • Writing is not formatting. Encode writes keys in no fixed order, drops keys whose value is null, and writes an array of objects as an inline array [{...}, {...}] rather than [[table]] blocks. The result is valid TOML that reads back to the same data, but comments and layout of an original file are lost.

Guide: read a project manifest

Project files such as Cargo.toml or pyproject.toml mix plain tables, inline tables and arrays of tables. Decode reads the whole file into a Value, or throws if it is not valid TOML; since main is declared throws, a broken file ends the program with the error. From there the value functions walk it.

encoding-toml-guide-manifest.salam
import encoding.toml
import encoding.value
import sort

func main throws:
    text := `[package]
name = "shop"
version = "1.4.0"
authors = ["Sara", "Reza"]

[dependencies]
http = "2.1"
json = { version = "1.0", optional = true }
log = "0.9"

[[bin]]
name = "shop"
path = "src/main.salam"

[[bin]]
name = "shop-admin"
path = "src/admin.salam"
`
    doc := try toml.Decode(text)
    pkg := value.ObjectGet(doc, "package")
    println value.AsString(value.ObjectGet(pkg, "name")), value.AsString(value.ObjectGet(pkg, "version"))
    println "authors:", value.ArrayLen(value.ObjectGet(pkg, "authors"))

    deps := value.ObjectGet(doc, "dependencies")
    names := value.ObjectKeys(deps)
    sort.QuickSort(names)
    each n in names:
        d := value.ObjectGet(deps, n)
        if value.IsString(d):
            println "dep", n, value.AsString(d)
        else:
            println "dep", n, value.AsString(value.ObjectGet(d, "version")), "(optional)"
        end
    end

    bins := value.ObjectGet(doc, "bin")
    repeat value.ArrayLen(bins) in i:
        b := value.ArrayGet(bins, i)
        println "binary", value.AsString(value.ObjectGet(b, "name")), "from", value.AsString(value.ObjectGet(b, "path"))
    end
end
Outputshop 1.4.0 authors: 2 dep http 2.1 dep json 1.0 (optional) dep log 0.9 binary shop from src/main.salam binary shop-admin from src/admin.salam

A dependency can be a plain version string or an inline table with more detail, so the program asks IsString before reading it. Objects do not keep the order of their keys; sorting ObjectKeys with sort.QuickSort gives a stable listing.

Guide: TOML into a struct

For settings you use all over a program, load them into a struct once. Encode the decoded value as JSON with json.EncodeDefault and let json.UnmarshalLenient fill the struct: keys the file leaves out keep the struct's defaults, and a [server] table fills a nested struct.

encoding-toml-guide-struct.salam
import encoding.toml
import encoding.json

struct Server:
    pub host: str = "127.0.0.1"
    pub port: int = 8000
end

struct Settings:
    pub title: str = ""
    pub debug: bool = false
    pub server: Server = Server {}
    pub allowed: Vector<str> = Vector {}
end

func main:
    text := `title = "Shop admin"
allowed = ["10.0.0.0/8", "192.168.1.0/24"]

[server]
port = 9090
`
    mut s := Settings {}
    try:
        doc := toml.Decode(text)
        json.UnmarshalLenient(json.EncodeDefault(doc), s)
    catch e:
        println "bad settings:", e.ToStr()
        ret 1
    end
    println s.title, "debug:", s.debug
    println "listen on", s.server.host, s.server.port
    println "allowed networks:", s.allowed.Len(), s.allowed.Get(0)
end
OutputShop admin debug: false listen on 127.0.0.1 9090 allowed networks: 2 10.0.0.0/8

Guide: write a TOML file

To write TOML, build a Value object and pass it to Encode. A nested object becomes a [table]. The top level must be an object, since a TOML document is always a table; Encode throws Unsupported for anything else, and for a null inside an array, with e.path naming where it is.

encoding-toml-guide-write.salam
import encoding.toml
import encoding.value

func replica(host: str, weight: int): value.Value:
    mut r := value.NewValueObject()
    value.ObjectSet(r, "host", value.ValueString(host))
    value.ObjectSet(r, "weight", value.ValueInt(weight))
    ret r
end

func main throws:
    mut db := value.NewValueObject()
    value.ObjectSet(db, "url", value.ValueString("postgres://localhost/shop"))
    value.ObjectSet(db, "pool", value.ValueInt(8))
    value.ObjectSet(db, "timeout", value.ValueFloat(30.0))
    value.ObjectSet(db, "password", value.ValueNull())

    mut replicas := value.NewValueArray()
    value.ArrayPush(replicas, replica("10.0.0.2", 2))
    value.ArrayPush(replicas, replica("10.0.0.3", 1))
    value.ObjectSet(db, "replicas", replicas)

    mut root := value.NewValueObject()
    value.ObjectSet(root, "database", db)

    text := try toml.Encode(root)
    print text

    back := value.ObjectGet(try toml.Decode(text), "database")
    println "timeout is still a float:", value.IsFloat(value.ObjectGet(back, "timeout"))
    println "password written:", value.ObjectHas(back, "password")
    println "replicas read back:", value.ArrayLen(value.ObjectGet(back, "replicas"))
end
Output[database] url = "postgres://localhost/shop" pool = 8 timeout = 30.0 replicas = [{host = "10.0.0.2", weight = 2}, {host = "10.0.0.3", weight = 1}] timeout is still a float: true password written: false replicas read back: 2

Three things show in the output. The null password is left out, because TOML has no null. The array of replica objects is written inline on one line. The float 30.0 keeps its .0, so it reads back as a float and not as the integer 30. Keys come out in no particular order, so never compare the text with a fixed string; compare the data, for example with value.Equal after decoding the text again.

Guide: catching mistakes

Decode throws on the first mistake, and Valid answers the same question as a plain bool. The error says what is wrong in e.message and where in e.line and e.column; e.kind sorts it (Syntax, UnexpectedEnd, AlreadyExists, TypeMismatch, OutOfRange, Unsupported) and e.code names it exactly, such as toml.duplicate_key.

encoding-toml-guide-errors.salam
import encoding.toml

func check(label: str, text: str):
    try:
        toml.Decode(text)
        println label, "ok"
    catch e:
        println label, e.message, "(line " + e.line + ", column " + e.column + ")"
    end
end

func main:
    check("good:            ", "a = 1\nb = 'two'\n")
    check("no value:        ", "a = \n")
    check("unclosed string: ", "a = \"open\n")
    check("unclosed array:  ", "a = [1, 2\n")
    check("unclosed table:  ", "[server\nport = 1\n")
    check("multi-line text: ", "a = \"\"\"x\"\"\"\n")
    check("duplicate key:   ", "a = 1\na = 2\n")
    check("unquoted string: ", "mode = fast\n")
    println "Valid agrees:", toml.Valid("a = 1"), toml.Valid("a = ")
end
Outputgood: ok no value: expected a value (line 1, column 5) unclosed string: the string is not closed before the end of the line (line 1, column 5) unclosed array: the array is not closed (line 1, column 5) unclosed table: expected ']' to close the table header (line 1, column 8) multi-line text: ok duplicate key: duplicate key 'a' (line 2, column 1) unquoted string: invalid value 'fast' (line 1, column 8) Valid agrees: true false

The last two lines are mistakes that a looser parser would let through: a key given twice, and mode = fast without the quotes TOML requires around a string. Both are rejected, so a file that decodes holds exactly what it says.

Functions

Decode

func Decode(text: str): Throws<value.Value>
Turns TOML into a Value. On invalid text it throws an Error with the kind, a toml.* code and the line and column of the mistake.
encoding-toml-Decode.salam
import encoding.toml
import encoding.value

func main throws:
    text := "title = \"salam\"\n\n[server]\nhost = \"localhost\"\nport = 8080\ntags = [\"a\", \"b\"]\n"
    println toml.Valid(text), toml.Valid("= no key")
    v := try toml.Decode(text)
    server := value.ObjectGet(v, "server")
    println value.AsString(value.ObjectGet(v, "title")), value.AsInt(value.ObjectGet(server, "port"))
    print try toml.Encode(v)
    try:
        toml.Decode("a = 1\nb = \n")
    catch e:
        println e.kind_name(), e.line, e.column, e.code
    end
    try:
        println toml.Encode(value.ValueInt(1))
    catch e:
        println e.ToStr()
    end
end
Outputtrue false salam 8080 title = "salam" [server] host = "localhost" port = 8080 tags = ["a", "b"] syntax error 2 5 toml.expected_value toml: the top level must be an object, since a TOML document is a table, not an integer

Valid

func Valid(text: str): bool
True when the text is valid TOML.

The example for this item is shown with the ones above: encoding-toml-Decode.salam

Encode

func Encode(v: value.Value): Throws<str>
Turns a value into TOML; null keys in a table are skipped. Throws Unsupported when the top level is not an object or an array holds a null.

The example for this item is shown with the ones above: encoding-toml-Decode.salam