TOML (std)
std/toml is written in Agentica and reads and writes all of TOML 1.0: import Toml from "std/toml". parse makes a Toml.Value (a recursive enum), encode writes it back, to_json converts it so JSON.decode can fill a struct. Every function returns a Result and never halts, whatever the input.
Toml.parse(text: String) -> Result[Toml.Value]
Toml.encode(value: Toml.Value) -> Result[String]
Toml.to_json(value: Toml.Value) -> Result[JSON.Value]
Toml.get(value: Toml.Value, path: String) -> Result[Toml.Value]Values #
enum Toml.Value
Str(String)
Int(Int)
Float(Float)
Bool(Bool)
DateTime(String)
Array(List[Toml.Value])
Table(Map[String, Toml.Value])
end- The root is always a
Table, aMapthat keeps keys in first-written order. Intis a signed 64-bit integer (a larger value is a parse error).Floatholdsinfandnan. Arrays may mix types.DateTimekeeps its text as written (the language has no date type). Offset and local date-times, local dates (1979-05-27) and local times (07:32:00) are accepted, and the month, day (leap years), time and offset are checked, not converted. A leap second (:60) is accepted, and fractional seconds keep every digit.
Reading #
Toml.parse accepts TOML 1.0 and nothing else. A float magnitude above the largest float reads as inf, one below the smallest as zero, as in Python’s tomllib. CRLF counts as one LF, also inside a multi-line string.
Errors: a duplicate key, a table defined twice, adding to an inline table or a static array, a dotted key that names a [header] table (or the reverse), [[a]] on a static array or table, control characters in strings and comments, and a lone carriage return.
Toml.get(value, path) reads a dotted path ("package.name"). A segment of plain digits (no sign, no leading zero) also indexes an array: "bin.1.path" is the second [[bin]]. A missing key gives an error naming it. A key that holds a dot cannot be reached this way: use case on the Table.
import Toml from "std/toml"
def main() -> Void
text = "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n\n[[bin]]\npath = \"a.agc\"\n\n[[bin]]\npath = \"b.agc\"\n"
doc = Toml.parse(text).unwrap!
puts(Toml.get(doc, "package.name")) # a dotted path
puts(Toml.get(doc, "bin.1.path")) # digits index an array
puts(Toml.get(doc, "package.license")) # a missing key is an error
puts(Toml.parse("a = 1\nb = 2\nc d\n")) # a parse error names its place
endok(Toml.Value.Str("demo"))
ok(Toml.Value.Str("b.agc"))
error("no key \"license\" in \"package.license\"", kind: "toml.decode")
error("line 3, column 3: expected '=' after key", kind: "toml.parse")Errors #
A parse error starts with the place, line 3, column 7: expected '=' after key. Lines and columns count from 1, columns in characters, not bytes. Messages are lowercase with no final period.
Arrays and inline tables nest at most 256 levels, and a key has at most 256 parts. Deeper input is an error at the bracket or key, never a halt.
Writing #
Toml.encode takes a Table (any other root is an error) and returns the document with a final newline, the same bytes for the same value.
- In each table: plain
key = valuelines first, then[a.b]sub-tables, then[[a.b]]arrays of tables, each group inMaporder, so a scalar never lands inside a[[...]]section. - A table with only sub-tables gets no header; an empty table does. An array that is not a direct table entry, or a table in a mixed array, is written inline.
- A key that is not bare (
A-Za-z0-9_-) is quoted. Strings are basic strings with escapes; non-ASCII text stays as is. - A float reads back the same, including
inf,-infandnan. An invalidDateTimeis an error. parseof the output gives the same values, with keys possibly regrouped in the order above.- The reader’s limits apply (256 parts in a table path, 256 levels inline), so the output can always be read back.
Toml.to_jsonstops at 2,048 levels. Deep values are errors, never halts.
import Toml from "std/toml"
def main() -> Void
pkg: Map[String, Toml.Value] = {
"name": Toml.Value.Str("acme/text"),
"deps": Toml.Value.Array([Toml.Value.Str("acme/lists")]),
}
root: Map[String, Toml.Value] = {}
root = root.put("package", Toml.Value.Array([Toml.Value.Table(pkg)]))
root = root.put("version", Toml.Value.Int(1))
text = Toml.encode(Toml.Value.Table(root)).unwrap!
puts(text)
puts(Toml.parse(text).ok?)
endversion = 1
[[package]]
name = "acme/text"
deps = ["acme/lists"]
trueTyped decoding #
Toml.to_json turns a DateTime into its string and keeps integers and floats apart (port = 8080.0 does not decode into an Int). inf and nan have no JSON form: errors. JSON.decode(json, Config) then fills a struct, and its errors name the field path.
import Toml from "std/toml"
struct Limits
cpu: Int
end
struct Config
name: String
port: Int
limits: Limits
end
def load(text: String) -> Result[Config]
doc = try Toml.parse(text)
json = try Toml.to_json(doc)
JSON.decode(json, Config)
end
def main() -> Void
config = load("name = \"web\"\nport = 8080\n\n[limits]\ncpu = 4\n").unwrap!
puts(config.name)
puts(config.limits.cpu)
puts(load("name = \"web\"\nport = 8080.0\n[limits]\ncpu = 4\n").message)
endweb
4
port: expected signed 64-bit Int