Esc

Toml

moduleextensionSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#import "Extensions/Toml";

General TOML 1.1 values, parsing and semantic writing. The core only consumes memory. Documents own their source, nodes and decoded strings; free_toml releases them together.

Example↗
doc, error := parse_toml("name = 'tool'\n");
assert(error.kind == .NONE);
assert(toml_get(doc.root, "name").text == "tool");
free_toml(*doc);

Procedures#

General#

(error: *Toml_Error) -> string

The error's allocation-independent path, borrowed from the error record. Truncation is explicit in path_truncated; full byte spans remain authoritative. Example: assert(toml_error_path(*error) == "$["format"]["indent_width"]");

toml_getsince 0.36.1Source
(table: *Toml_Value, key: string) -> *Toml_Value

Looks up one exact decoded key; null means absent or a non-table. Dots are literal here. Example: toml_get(doc.root, "format") finds the format table.

(table: *Toml_Value, keys: [] string) -> (*Toml_Value, Toml_Error)

Follows exact key segments. Absence is null/NONE; traversing a scalar is TYPE. Nodes remain document-owned. Lookup errors have byte spans where available and no computed line/column. Example: value, error := toml_get_path(doc.root, string.["format", "indent_width"]);

free_tomlsince 0.36.1Source

Releases the complete document with its original allocator; safe to call again. Example: free_toml(*doc);

parse_tomlsince 0.36.1Source
(text: string, options := Toml_Options.{}) -> (Toml_Document, Toml_Error)

Parses a complete TOML 1.1 document atomically. All returned storage is independent of input. Example: doc, error := parse_toml("enabled = true\n");

from_tomlsince 0.36.1Source
($T: Type, text: string, options := Toml_Options.{}) -> (T, Toml_Error)

Decodes text into a T, which must be a struct, without building a document. The result takes its strings, arrays and pointers from context.allocator; free_toml_value releases them. After a failure everything was freed already and the value is a default T.

Server :: struct {
    host: string;
    port: int; @toml(default)
    tags: [..] string; @toml(default)
}

server, error := from_toml(Server, "host = 'a'\nport = 80\n");
assert(error.kind == .NONE && server.host == "a" && server.port == 80);
free_toml_value(*server);
↗
to_tomlsince 0.36.1Source
(value: $T, options := Toml_Options.{}) -> (string, Toml_Error)

Writes a struct as a TOML document: key/value lines first, then [table] and [[array of tables]] headers for struct fields; null pointers are omitted. Honors the notes of from_toml and the output limits of options. Free the text with free.

Point :: struct {
    x: float64;
    y: float64;
}

text, error := to_toml(Point.{ 1, 2.5 });
assert(error.kind == .NONE && text == "x = 1.0\ny = 2.5\n");
free(text);
↗
toml_encodesince 0.36.1Source
(value: *$T, options := Toml_Options.{}) -> (string, Toml_Error)

Encodes the value value points to as TOML, like to_toml without copying it first. Returns owned text to free, or an empty string and the error.

Point :: struct {
    x: float64;
    y: float64;
}

p := Point.{ 1, 2.5 };
text, error := toml_encode(*p);
assert(error.kind == .NONE && text == "x = 1.0\ny = 2.5\n");
free(text);
↗
(value: *$T)

Releases what a decode allocated, for a decoded struct: strings, arrays, pointers (and what they point to) and nested structs. Fields still holding their declared default are left alone, so name := "guest" is safe. The fields are reset; a second call does nothing.

Host :: struct {
    name: string;
}

host, _ := from_toml(Host, "name = 'a'\n");
free_toml_value(*host);
assert(host.name.count == 0);
↗

Build#

Allocates a detached node. Its kind stays fixed; assign only scalar fields matching that kind. Use toml_set_text/toml_set_fraction for owned text, and toml_insert/toml_push to attach it. Example: value, error := toml_new_value(*doc, .INTEGER); value.integer = 7;

(doc: *Toml_Document, value: *Toml_Value, text: string) -> Toml_Error

Copies a string with the document's allocator. Failure preserves both value and budget. max_string_bytes limits one decoded string/key/fraction; retained bytes bound their total. Example: error = toml_set_text(*doc, value, "tool");

(doc: *Toml_Document, value: *Toml_Value, digits: string) -> Toml_Error

Copies exact fractional-second digits. Empty means no fractional component. Replacement temporarily holds both old and new strings; max_retained_bytes bounds the resulting document. Example: error = toml_set_fraction(*doc, value, "123456789012");

toml_insertsince 0.36.1Source
(doc: *Toml_Document, table: *Toml_Value, key: string, value: *Toml_Value) -> Toml_Error

Inserts an absent key and a detached same-document node. Duplicates never replace silently. All depth/storage checks precede mutation. Node pointers remain stable across array/index growth. Example: error = toml_insert(*doc, doc.root, "count", value);

Statements#

(doc: *Toml_Document, statement: Toml_Statement, buffer: [] string) -> ([] string, Toml_Error)

Copies a statement's decoded key segments into caller storage, borrowing the strings from doc. Array element indices are omitted. The projection describes the parsed source; statements and returned keys expire with the document. Internal parent/slot fields are read-only. Example: path, error := toml_statement_path(*doc, doc.statements[0], buffer);

Writer#

write_tomlsince 0.36.1Source
(root: *Toml_Value, options := Toml_Options.{}) -> (string, Toml_Error)

Writes a deterministic semantic TOML document. Comments/layout are not preserved. A table inside a table is written under a [header] and a nonempty array of tables under [[header]], after the table's own key = value lines (an empty table is a bare [header], as in the typed encoder). A table inside any other array stays inline. Example: text, error := write_toml(doc.root); defer free(text);

Types#

Toml_Kindenumsince 0.36.1Source

The value stored in a TOML node; temporal spellings retain their distinct kinds.

Toml_Kind :: enum u8 {
    TABLE;
    ARRAY;
    STRING;
    INTEGER;
    FLOAT;
    BOOL;
    LOCAL_DATE;
    LOCAL_TIME;
    LOCAL_DATETIME;
    OFFSET_DATETIME;
}
Toml_Spanstructsince 0.36.1Source

Half-open byte offsets in the document source; -1 means no source location.

Toml_Span :: struct {
    start: int = -1;
    end: int = -1;
}
Toml_Error_Kindenumsince 0.36.1Source

Failure category; NONE means parsing or writing succeeded.

Toml_Error_Kind :: enum u8 {
    NONE;
    SYNTAX;
    TYPE;
    DUPLICATE;
    ENCODING;
    RANGE;
    LIMIT;
    OUTPUT;
}
Toml_Errorstructsince 0.36.1Source

Messages are static; errors remain valid after input/document release. Columns count Unicode scalars from one, tabs count one, and spans are half-open byte ranges. related is spanless unless an earlier declaration caused the error.

Toml_Error :: struct {
    kind: Toml_Error_Kind;
    message: string;
    span: Toml_Span;
    related: Toml_Span;
    line: int;
    column: int;
    path_bytes: [512] u8;
    path_count: int;
    path_truncated: bool;
}
Toml_Temporalstructsince 0.36.1Source

Civil fields never consult a timezone. Fractions retain all digits. :60 is retained as a leap-second spelling; this format layer does not verify historical leap insertion events.

Toml_Temporal :: struct {
    year: int;
    month: int;
    day: int;
    hour: int;
    minute: int;
    second: int;
    fraction: string;
    offset_minutes: int;
    negative_zero_offset: bool;
}
Toml_Memberstructsince 0.36.1Source

One decoded table key and its document-owned value, in insertion order.

Toml_Member :: struct {
    key: string;
    value: *Toml_Value;
    key_span: Toml_Span;
}
Toml_Valuestructsince 0.36.1Source

Nodes are document-owned and stay at the same address. Do not copy ownership, attach nodes from another document or introduce cycles. Members/items are insertion-ordered; their array storage may move on growth. Parsed values' spans refer to document.source.

Toml_Value :: struct {
    kind: Toml_Kind;
    union {
        members: [..] Toml_Member;
        text: string;
        integer: s64;
        real: float64;
        boolean: bool;
        temporal: Toml_Temporal;
        items: [..] *Toml_Value;
    }
    span: Toml_Span;
    internal_index: int;
    internal_parent: *Toml_Value;
    internal_lookup: *Toml_Index;
    internal_parent_slot: int;
    internal_height: int;
}
Toml_Optionsstructsince 0.36.1Source

Memory, nesting and output limits shared by parsing and writing. Set record_statements before parsing to retain source statement order.

Toml_Options :: struct {
    max_input_bytes: int = 16 << 20;
    max_depth: int = 128;
    max_nodes: int = 1 << 20;
    max_string_bytes: int = 16 << 20;
    record_statements: bool;
    max_number_bytes: int = 4096;
    max_retained_bytes: int = 128 << 20;
    max_output_bytes: int = 32 << 20;

    deny_unknown_fields: bool;
}
Toml_Datetimestructsince 0.36.1Source

A date or time field of a typed struct: which of the four spellings it is, and its fields. A value whose kind is not temporal is never written.

Toml_Datetime :: struct {
    kind: Toml_Kind;
    value: Toml_Temporal;
}
Toml_Unknownstructsince 0.36.1Source

One key a typed decode had no field for, collected into a struct's @toml(unknown) list. path is the dotted key below that table (a.b for a.b = 1 or [x.a.b] under x); start and end are the half-open source bytes of the statement and value is where an assignment's value begins (-1 for headers), so the value text is source[value:end]. header marks [table] and [[table]] lines.

Toml_Unknown :: struct {
    path: string;
    start: int;
    value: int;
    end: int;
    header: bool;
}
Toml_Documentstructsince 0.36.1Source

Owns the source, nodes and decoded strings; release with free_toml. Node pointers and statement records remain valid until that release.

Toml_Document :: struct {
    root: *Toml_Value;
    source: string;
    nodes: [..] *Toml_Value;
    allocator: Allocator;
    options: Toml_Options;
    retained_bytes: int;
    statements: [..] Toml_Statement;
}

Source statements are optional: record_statements enables this ordered projection without a second parser. Inline assignments are included; an outer assignment precedes its children.

Toml_Statement_Kind :: enum u8 {
    ASSIGNMENT;
    TABLE;
    ARRAY_TABLE;
}