Module encoding/toml
TOML v1.0.0 parsing and serialization.
toml.parse scans a whole document with a byte scanner and returns a
TomlValue tree; toml.stringify writes one back out. The value model is
the Rust toml crate's Value: string, integer, float, boolean,
date-time, array, table.
Everything TOML v1.0.0 admits is accepted: comments, bare / quoted /
dotted keys, basic and literal strings (single and multi-line, with
escapes), decimal / hex / octal / binary integers, floats including
inf and nan, the four date-time forms, arrays (heterogeneous,
nested, trailing comma, newlines inside the brackets), inline tables,
[table] headers and [[array of tables]]. Everything it does not
admit is an .Err with a byte offset — a document that parses is the
document that was written.
Example
toml :: import("std/encoding/toml");
{ TomlValue } :: import("std/encoding/toml");
doc := toml.parse(`title = "yo"
[server]
port = 8080
`).unwrap();
println(doc.get(`server`).unwrap().get(`port`).unwrap().as_int().unwrap());
println(toml.stringify(doc));
Stability
unstable — this replaced the line-based subset parser (which returned .Ok
with a corrupted document for twelve inputs), so the value model gained
Float, Datetime and Array, insert returns the value it replaced,
and the error type changed from String to TomlError. The API may still
change until the next release; drop this section to freeze it.
Types
A TOML parse failure. Every variant carries a BYTE OFFSET into the input,
the same contract EncodingError and CsvError have: a caller decoding a
4 KiB config learns WHERE the document is wrong, not merely that it is.
Variants
| Variant | Fields | Description |
|---|---|---|
UnexpectedChar | ch: u8, pos: usize | A byte that cannot appear here — a garbage line, a missing |
UnexpectedEnd | pos: usize | The input ended inside a construct (a header, an array, an inline
table, a key/value pair). |
UnterminatedString | start: usize | A string ran to the end of its line (single-line forms) or to the end
of the input without its closing delimiter. |
InvalidEscape | pos: usize | A backslash escape that is not one of TOML's ( |
InvalidUnicode | pos: usize | A |
InvalidNumber | pos: usize | A numeric literal outside TOML's integer/float grammar, or an integer
outside |
InvalidDatetime | pos: usize | A date-time literal that is not one of RFC 3339's forms TOML admits, or whose components are outside the calendar. |
DuplicateKey | key: String, pos: usize | A key defined twice in the same table. |
RedefinedTable | key: String, pos: usize | A table header that reopens a table already closed — defined by an
earlier header, by a dotted key, or as an inline-table value — or an
|
ExpectedTable | key: String, pos: usize | A dotted key or header path that runs THROUGH a value which is not a
table ( |
Trait Implementations
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> StringRender self under spec. An unrecognised spec degrades to the plain
to_string() rendering rather than failing.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
spec | str |
Returns: String
impl(TomlError, ...)
pos : (TomlError) fn(self : TomlError) -> usizeThe byte offset the fault was found at. Unlike EncodingError.pos this
is total: every TOML failure has a position, because the scanner always
knows where it is.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlError |
Returns: usize
Methods
to_string : (TomlError) fn(self : TomlError) -> Stringsource : (TomlError) fn(self : TomlError) -> Option(dyn( + ToString))The error that caused this one, or .None at the root of the chain.
Rust's Error::source. Defaulted to .None, so an error with nothing
underneath it implements the trait by saying only what it is; a wrapper
overrides it to hand back what it wrapped. Walking the chain to the root
cause is not expressible yet — the returned Dyn loses the Error
trait on an erased receiver, so a caller can print one link but cannot
follow it (#521,
issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlError |
Which of TOML's four date-time forms a TomlDateTime holds. The tag is
what DateTime alone cannot supply, and every form needs it:
1979-05-27T07:32:00Z and 1979-05-27T07:32:00 are DIFFERENT TOML values
(one names an instant, one a wall-clock reading with no zone), and a local
date has no time while a local time has no date. Without the tag a parse
would have to invent a zone or a date and the serializer could not write
back what it read.
Variants
| Variant | Fields | Description |
|---|---|---|
OffsetDateTime |
| |
LocalDateTime |
| |
LocalDate |
| |
LocalTime |
|
Trait Implementations
Methods
== : (TomlDateTimeKind) fn(lhs : TomlDateTimeKind, rhs : TomlDateTimeKind) -> bool!= : (TomlDateTimeKind) fn(lhs : TomlDateTimeKind, rhs : TomlDateTimeKind) -> boolA TOML date-time: std/time/datetime's DateTime for the components,
plus the tag saying which of them are significant.
The components are REUSED rather than redeclared so the calendar rules
live in one place — DateTime.new is what validates a leap day, and this
module would otherwise carry a second copy of the leap-year table. What
DateTime cannot do is distinguish TOML's four forms (it has no "no
offset" state and no date-less or time-less form), which is why kind
exists; the components the tag calls absent are set to the epoch's
(1970-01-01 for a local time, 00:00:00 for a local date) and must not
be read.
Fields
| Name | Type | Description |
|---|---|---|
kind | TomlDateTimeKind | Which form this is — and therefore which components mean anything. |
value | DateTime | The components. |
Trait Implementations
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> StringRender self under spec. An unrecognised spec degrades to the plain
to_string() rendering rather than failing.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
spec | str |
Returns: String
impl(TomlDateTime, ToString(...))
to_string : (TomlDateTime) fn(self : TomlDateTime) -> StringRender self as the text a USER should read — Rust's Display::fmt,
not its Debug. Hand-written (or generated by derive(Error) from a
per-variant format string) whenever the structural form would be wrong.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlDateTime |
Returns: String
TOML value type — the result of parsing a TOML document. The variants are
the Rust toml crate's Value, in its order.
Variants
| Variant | Fields | Description |
|---|---|---|
Str | value: String | A TOML string value. |
Int | value: i64 | A TOML integer value (64-bit signed, as TOML requires). |
Float | value: f64 | A TOML float value (IEEE 754 double, as TOML requires). |
Bool | value: bool | A TOML boolean value. |
Datetime | value: TomlDateTime | A TOML offset/local date-time, local date, or local time. |
Array | items: ArrayList(<enum:enum_decl_505353_file____home_runner_work_Yo_Yo_std_encoding_toml_yo__self_shell>) | A TOML array. TOML v1.0.0 allows mixed element types. |
Table | keys: ArrayList(String), values: ArrayList(<enum:enum_decl_505353_file____home_runner_work_Yo_Yo_std_encoding_toml_yo__self_shell>) | A TOML table, keys in insertion order. |
Trait Implementations
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> StringRender self under spec. An unrecognised spec degrades to the plain
to_string() rendering rather than failing.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
spec | str |
Returns: String
impl(TomlValue, ...)
new_table : (TomlValue) fn() -> TomlValueCreate a new empty table.
Returns: TomlValue
new_array : (TomlValue) fn() -> TomlValueCreate a new empty array.
Returns: TomlValue
get : (TomlValue) fn(self : TomlValue, key : String) -> Option(TomlValue)has_key : (TomlValue) fn(self : TomlValue, key : String) -> boolinsert : (TomlValue) fn(self : TomlValue, key : String, value : TomlValue) -> Option(TomlValue)Set key to value, returning the value it REPLACED (.None when the
key is new) — the D2 shape for a map insert, matching
JsonValue.insert. Insertion order is preserved and a replacement keeps
the key's original position. A non-table receiver is a no-op returning
.None.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
self | TomlValue | ||
key | String | ||
value | TomlValue | The components. |
table_len : (TomlValue) fn(self : TomlValue) -> usizeReturn the number of keys in the table, or 0 if not a table.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlValue |
Returns: usize
array_len : (TomlValue) fn(self : TomlValue) -> usizeReturn the number of elements in the array, or 0 if not an array.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlValue |
Returns: usize
at : (TomlValue) fn(self : TomlValue, index : usize) -> Option(TomlValue)The byte off past the cursor, or 0 at/after the end of input. No TOML
construct admits a NUL — _is_forbidden_control rejects it inside every
string, key and comment — so 0 is an unambiguous end marker for the
lookahead tests below.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlValue | |
index | usize |
as_string : (TomlValue) fn(self : TomlValue) -> Option(String)as_int : (TomlValue) fn(self : TomlValue) -> Option(i64)as_float : (TomlValue) fn(self : TomlValue) -> Option(f64)as_bool : (TomlValue) fn(self : TomlValue) -> Option(bool)as_datetime : (TomlValue) fn(self : TomlValue) -> Option(TomlDateTime)Extract the date-time value, or .None if not a Datetime.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlValue |
Returns: Option(TomlDateTime)
as_array : (TomlValue) fn(self : TomlValue) -> Option(ArrayList(<enum:enum_decl_505353_file____home_runner_work_Yo_Yo_std_encoding_toml_yo__self_shell>))is_string : (TomlValue) fn(self : TomlValue) -> boolis_int : (TomlValue) fn(self : TomlValue) -> boolis_float : (TomlValue) fn(self : TomlValue) -> boolis_bool : (TomlValue) fn(self : TomlValue) -> boolis_datetime : (TomlValue) fn(self : TomlValue) -> boolTrue for a TOML date-time of any of the four forms.
Parameters
| Name | Type | Notes |
|---|---|---|
self | TomlValue |
Returns: bool
is_array : (TomlValue) fn(self : TomlValue) -> boolis_table : (TomlValue) fn(self : TomlValue) -> boolimpl(TomlValue, ToString(...))
to_string : (TomlValue) fn(self : TomlValue) -> Stringimpl(TomlValue, Eq(TomlValue)(...))
Functions
Serialize a TomlValue to TOML text. A table renders as a document
(toml.parse(toml.stringify(v)) gives v back for every value the
parser produces); any other value renders in its inline form, which is
what a caller stringifying one field wants.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
value | TomlValue | The components. |
Returns: String