toml
Converts TOML 1.0 text to and from the core Value tree, and to and from your own types through the compiler-derived to_value/from_value. It handles every TOML 1.0 feature: bare, quoted and dotted keys, [tables], [[arrays of tables]], inline tables, all four string kinds, integers with _ and 0x/0o/0b, floats including inf/nan, booleans, and dates and times. It enforces the spec's rules on redefining tables and keys. Parse errors are a typed TomlErr that carries the line and column. The API mirrors json.
Effects: none. Dependencies: none.
struct Server { host: str, port: int }
struct Config { title: str, debug: bool, server: Server }
let v = toml.parse("title = \"demo\"\n[server]\nport = 8080")? // Map({"title": Str("demo"), "server": Map({"port": Int(8080)})})
let c: Config = toml.decode(fs.read("app.toml")?)?
fs.write("app.toml", toml.encode(c)?)?
match toml.parse("a: 1") {
err(e) => print(toml.message(e)) // 1:2: expected '=', found ':'
ok(_) => {}
}
API
enum TomlErr { Unexpected(found: char, want: str, line, col), Eof(want: str, line, col), BadNumber(text: str, line, col), BadDateTime(text: str, line, col), BadEscape(text: str, line, col), ControlChar(line, col), DuplicateKey(key: str, line, col), NotATable(key: str, line, col), TooDeep(line, col) }: all positions areintand 1-based (columns count chars).wantsays what was expected, for example"'='"or"a value".keyis the full dotted path, for examplefruit.apple.parse(s: str): Value!TomlErr: the document as aMap. Tables and inline tables becomeMap, with keys in document order. Arrays and arrays of tables becomeList, integersInt, floatsFloat, and booleansBool. Arrays, inline tables and their combinations can nest up toMAX_DEPTH(512) levels.str(v: Value): str!: TOML text. Each table's plainkey = valuelines come first, then its[sub.tables], then its[[arrays.of.tables]](a non-emptyListwhose items are allMaps). Keys keep map order and are quoted only when they aren't bare. A[header]is left out for a table that holds only other tables.Nullmap entries are omitted, because TOML has no null. The call fails when the root isn't aMapor when aNullsits inside an array. Floats always keep a.or an exponent; NaN and the infinities are writtennan,infand-inf.decode<T: Data>(s: str): T!:parsefollowed by the derivedfrom_value; the typeTcomes from the annotation (let c: Config = toml.decode(s)?). An integer fills afloatfield.encode<T: Data>(x: T): str!: the derivedto_valuefollowed bystr, soxmust be a struct or a{str: T}map.message(e: TomlErr): str: a one-line description, for example4:2: 'fruit' is already defined.
Dates and times
Value has no date variant, so TOML dates and times parse to Str in RFC 3339 form. Each one is validated first, including the month, the day of the month (leap years included), the hour, the minute, the second (60 is allowed for a leap second) and the offset. The text is kept as written, except that a space or t between the date and the time becomes T and a z offset becomes Z:
| TOML | parses to |
|---|---|
1979-05-27T07:32:00Z, 1979-05-27 07:32:00z |
Str("1979-05-27T07:32:00Z") |
1979-05-27T00:32:00.999999-07:00 |
Str("1979-05-27T00:32:00.999999-07:00") |
1979-05-27T07:32:00 (local) |
Str("1979-05-27T07:32:00") |
1979-05-27 (local date) |
Str("1979-05-27") |
07:32:00 (local time) |
Str("07:32:00") |
The writer can't tell such a string from any other, so str writes it as a quoted string. Reading it back gives the same Str, but other TOML readers see a string, not a date.
Limits in 0.1
- Seconds are required in times, as TOML 1.0 says. TOML 1.1's optional seconds,
\eand\xHHescapes, and newlines inside inline tables aren't accepted yet. - Integers must fit in 64 bits; a larger one is a
BadNumbererror. Floats beyond thefloatrange becomeinf. -nanand+nanparse to the same NaN.\r\ninside multi-line strings is read as\n.strdoesn't keep comments, formatting or the original key order of a parsed file beyond what theMapholds.