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
| TOML | Value |
|---|---|
[table], [a.b], inline { k = v }, dotted keys a.b = 1 | object (nested) |
[[name]] | array of objects |
"basic" with escapes, 'literal' | string |
42, -7, 1_000, 0x1F, 0o17, 0b101 | int (64-bit) |
3.5, 1e6, inf, nan | float |
true, false | bool |
dates and times such as 1979-05-27T07:32:00Z | string, unchanged |
What trips people up
- Errors stop the whole read.
Decodethrows at the first mistake, withe.lineande.columnpointing at it, so a typo never silently drops the rest of the file. A key or[table]defined twice, an unquoted word such asmode = 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.
Encodewrites 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.
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
endA 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.
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)
endGuide: 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.
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"))
endThree 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.
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 = ")
endThe 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>Value. On invalid text it throws an Error with the kind, a toml.* code and the line and column of the mistake.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
endValid
func Valid(text: str): boolThe example for this item is shown with the ones above: encoding-toml-Decode.salam
Encode
func Encode(v: value.Value): Throws<str>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