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"]");
#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.
doc, error := parse_toml("name = 'tool'\n");
assert(error.kind == .NONE);
assert(toml_get(doc.root, "name").text == "tool");
free_toml(*doc);Procedures#
General#
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.
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"]);
Releases the complete document with its original allocator; safe to call again. Example: free_toml(*doc);
Parses a complete TOML 1.1 document atomically. All returned storage is independent of input. Example: doc, error := parse_toml("enabled = true\n");
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);Decodes text into out, which must hold a default T; see from_toml.
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.
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);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#
Creates an empty owning document. Builder nodes belong to it until free_toml. Example: doc, error := new_toml_document();
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;
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");
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");
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);
Appends a detached same-document node. Shared children, cycles and excessive depth are errors. Example: error = toml_push(*doc, list, value);
Statements#
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#
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#
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;
}Half-open byte offsets in the document source; -1 means no source location.
Toml_Span :: struct {
start: int = -1;
end: int = -1;
}Failure category; NONE means parsing or writing succeeded.
Toml_Error_Kind :: enum u8 {
NONE;
SYNTAX;
TYPE;
DUPLICATE;
ENCODING;
RANGE;
LIMIT;
OUTPUT;
}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;
}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;
}One decoded table key and its document-owned value, in insertion order.
Toml_Member :: struct {
key: string;
value: *Toml_Value;
key_span: Toml_Span;
}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;
}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;
}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;
}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;
}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;
}One optional source projection record; spans and values belong to its document.
Toml_Statement :: struct {
kind: Toml_Statement_Kind;
value: *Toml_Value;
span: Toml_Span;
header_depth: int;
line: int;
}