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, a Map that keeps keys in first-written order.
  • Int is a signed 64-bit integer (a larger value is a parse error). Float holds inf and nan. Arrays may mix types.
  • DateTime keeps 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
end
Output
ok(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 = value lines first, then [a.b] sub-tables, then [[a.b]] arrays of tables, each group in Map order, 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, -inf and nan. An invalid DateTime is an error.
  • parse of 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_json stops 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?)
end
Output
version = 1

[[package]]
name = "acme/text"
deps = ["acme/lists"]

true

Typed 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)
end
Output
web
4
port: expected signed 64-bit Int