`std/toml`

TOML 1.0.0 (https://toml.io/en/v1.0.0), read and written in iyi alone: a reader that answers a document as an Any or a TOMLError saying what is wrong and where, a writer whose text reads back to the value it was given, and derive toml_serializable.

import std/toml to use it. Source: src/std/toml.iyi at v0.18.0.

What it reads, which is all of 1.0.0:

* Keys bare (`A-Za-z0-9_-`, digits alone too, always a string),
  quoted as a basic or a literal string (the empty `""` included), and
  dotted, with blanks around the dots.
* Basic strings with the nine escapes the format has (`\b`, `\t`,
  `\n`, `\f`, `\r`, `\"`, `\\`, `\uXXXX`, `\UXXXXXXXX`, the last two
  naming a Unicode scalar value), literal strings, and the multi-line
  forms of both: the line break right after the opening `"""` or `'''`
  is dropped, a line-ending backslash drops the blanks and line breaks
  after it, and one or two quotes may stand just before the closing
  three. A CRLF inside a multi-line string is read as LF, as the spec
  allows and Python's `tomllib` does.
* Integers decimal (`+`/`-`, no leading zero but `0`, `+0` and `-0`),
  `0x`, `0o` and `0b` (no sign, leading zeros allowed), an underscore
  only between two digits, into an `Int64`; floats with a fraction, an
  exponent or both (a digit on each side of the point), `inf` and
  `nan` with either sign, into a `Float64`, the nearest double to the
  decimal (the prelude's `String#to_f` rounds correctly).
* `true` and `false`.
* Offset date-times, local date-times, local dates and local times,
  each a `TOMLDateTime` that keeps its kind. `T`, `t` or a space
  between date and time, `Z`/`z` or `+HH:MM`/`-HH:MM` for the offset.
  Fractional seconds are kept to the nanosecond; digits past the ninth
  are dropped, which the spec allows ("truncated, not rounded").
* Arrays of anything, mixed, across lines, with comments and a
  trailing comma; inline tables, on one line, closed to extension.
* `[table]` and `[[array.of.tables]]` headers, with blanks inside the
  brackets, and the tables dotted keys open.

Why its own date-time type and not std/time's Time: three of the four kinds are not instants (a local date-time has no zone, a local date no time, a local time no date), and an offset date-time keeps the offset it was written with, which a Time turned to UTC would lose and dump would then not write back. And std/time reads the clock and the zone files, which this module, pure computation over a String, has no reason to reach. TOMLDateTime#unix_seconds gives an offset date-time's instant to whoever wants a Time of it.

What it refuses, each a TOMLError naming the line and the column (counted in characters, from 1) where the trouble is:

* Text that is not UTF-8, and a byte order mark (the grammar has none,
  and `tomllib` refuses one too).
* A control character other than tab in a comment or a string
  (U+0000-U+0008, U+000A-U+001F, U+007F), a CR not before an LF, a
  line break in a single-line string, an escape the format does not
  have (TOML 1.1's `\e` and `\xHH` among them) or one naming a
  surrogate or past U+10FFFF, a string that does not close, six or
  more quotes closing a multi-line string.
* A key with no value or a value with no key, a key/value pair
  followed by more than a comment on its line, a bare key with a
  character outside its set, a multi-line string as a key.
* An integer with a leading zero, a doubled, leading or trailing
  underscore, a sign on `0x`/`0o`/`0b`, an uppercase prefix, or a value
  past the `Int64` range (the spec requires the refusal; `tomllib`
  reads any size, so the gate compares these as this reader's own); a
  float with no digit on one side of its point (`.7`, `7.`, `3.e+20`).
* A date that is not one (February 30th, month 13, hour 24, minute or
  second 60 - a leap second is refused, as `tomllib`'s datetime does),
  a time without its seconds (allowed only from TOML 1.1), an offset
  past 23:59, a date-time missing a part.
* An array or an inline table that does not close, a missing comma, a
  trailing comma or a line break in an inline table.
* Every redefinition the spec forbids: a key given twice (`a` and
  `"a"` are one key), a `[table]` declared twice, a `[table]` header
  naming a table that dotted keys made, dotted keys adding to a table
  a `[header]` declared or to one dotted keys made under another
  header, a header or dotted key going into an inline table or an
  array written as a value, `[[x]]` where `x` is a table or a static
  array, `[x]` where `x` is an array of tables, a value where a table
  is. A header may still go into a table dotted keys made
  (`[fruit.apple.texture]` after `apple.color = "red"` under
  `[fruit]`), and a super-table may be declared after its sub-table.
  These follow the spec's text and its examples, and where the text is
  silent, what `tomllib` does: dotted keys may add to a table a header
  made only on the way to another (`[a.b.c]` then `[a]` `b.d = 1`),
  and once they have, that table may not be declared by a header.
* Nesting past DEPTH_LIMIT levels, counting tables, arrays and inline
  tables alike, so `==`, `dump` and `hash` over any value this reader
  answers stay within a task's stack.

TOML.parse(text) answers Any | TOMLError; TOML.parse?(text) answers nil where parse answers the error, as JSON.parse? and YAML.parse? do. Neither panics on anything a document says. TOML.parse(text).or_panic panics with the sentence, and TOML.from_toml panics as YAML.from_yaml does.

TOML.dump(value) writes a table as TOML that this reader and tomllib read to an equal value: a table's plain keys first, as key = value, then each sub-table under a [header] and each non-empty array whose items are all tables as [[header]] entries; other arrays and tables inside arrays are written inline. Keys are bare where the bare set allows and quoted otherwise; strings are basic strings, with ", \ and every control character escaped (so no string spans lines); floats are the shortest text that reads back as the same double, inf, -inf and nan as TOML spells them. A value that is not a table cannot be a document and is refused, a panic: that is the program's mistake.

derive toml_serializable makes a type read and write itself as a table, a key per field, as std/yaml's derive yaml_serializable does: to_toml, self.from_toml(text), initialize(toml : Any) and the ToTOML trait's to_toml_any. TOML has no null: a nil field is left out when written and a missing key reads as nil where the field admits it; a nil anywhere else (inside an array, as a hash value) cannot be written and is refused by name.

Any holds a value: raw is the union, as_x/as_x? are the pairs, []/[]?/dig/dig? walk it, == is structural (two NaNs are equal, a document that says nan twice says the same thing) and hash agrees with it. As in std/yaml, every test of the union goes through Any#kind, which tests the reference types first.

`toml_serializable`macro

derive toml_serializable, in a struct or class whose fields are written with their types: the type reads and writes itself as a TOML table, a key per field, named as the field is.

  pub struct Coord
    getter x : Float64
    getter name : String
    derive toml_serializable
  end

  Coord.from_toml("x = 1.5\nname = \"a\"\n").x   # => 1.5
  coord.to_toml                                 # => "x = 1.5\nname = \"a\"\n"

It is std/yaml's derive yaml_serializable over TOML, field for field: a value is read and written as TOML.read_value and TOML.to_any take its type (Bool, Int32, Int64, UInt8, UInt64, Float64, String, TOMLDateTime, Any, an Array or a Hash(String, _) of them, another derived type, each of them or nil). TOML has no null, so a nil field is not written, and a missing key is read as YAML's derive reads one: a field with a default keeps it, a nilable field holds nil, and any other is refused by name. A key the type has no field for is passed over. A type that is several writes derive serializable, yaml_serializable, toml_serializable: what this one generates shares no method with theirs (to_toml, from_toml, to_toml_any and initialize(toml : Any) of this module's Any).