API reference

TOML 1.1.0 in Zig: a strict parser, a value tree, and a writer.

parseFromSlice reads a document into a Document: a tree of Values in one arena. stringify writes a tree back out. The parser rejects every document that breaks TOML 1.1.0. The writer emits TOML 1.0.0, so a 1.0 parser reads its output, and the parser reads that output back to an equal tree.

struct Array

src

pub const Array = @import("value.zig").Array

An array, with its elements in document order.

Fields

items: std.ArrayList(Value)

kind: Kind

How the document declared the array.

Functions

`pub fn init(kind: Kind) Array`

src

An empty array of kind.

`pub fn count(self: Array) u32`

src

The number of elements.

`pub fn append(self: *Array, allocator: Allocator, value: Value) Allocator.Error!void`

src

Append an element.

Types

enum Kind

src

Fields

list list

a = [ ... ]: a value array.

tables tables

[[a]] headers: an array of tables.

module Datetime

src

One of the four TOML datetime forms, down to the nanosecond.

Constants

`pub const Error = error{InvalidDatetime}`

src

The only failure scan and parse report: the text is not a datetime.

Functions

`pub fn init(kind: Kind) Datetime`

src

A datetime of kind with nothing set: no date, the time at midnight, and no offset.

`pub fn scan(text: []const u8) Error!?Scanned`

src

Read a datetime from the start of text.

Returns null when text does not begin with a date or a time. Returns error.InvalidDatetime when it begins like one but breaks the grammar or a field range. The caller decides what may follow the bytes that were used.

`pub fn parse(text: []const u8) Error!Datetime`

src

Parse text as one datetime and nothing else.

`pub fn write(self: Datetime, writer: *Io.Writer) Io.Writer.Error!void`

src

Write the datetime the way TOML spells it.

Types

enum Kind

src

Which of the four forms a value is.

Fields

offset offset

Date, time, and offset: an instant.

local_datetime local_datetime

Date and time with no offset.

local_date local_date

A calendar date with no time.

local_time local_time

A clock time with no date.

struct Scanned

src

A datetime found at the start of some text, and the bytes it used.

Fields

value: Datetime

The value.

len: usize

Bytes of the input the value's text occupies.

module Diagnostics

src

Where a parse failed: the bytes, the position, and a message. The caller owns this struct and passes it in ParseOptions.

Constants

`pub const empty: Diagnostics = …`

src

value

.{
    .span = .{ .start = 0, .end = 0 },
    .line = 1,
    .column = 1,
    .len = 0,
    .buf = undefined,
}

A diagnostic before any parse: an empty span at the start of the source, line 1, column 1, and no message.

Functions

`pub fn message(self: *const Diagnostics) []const u8`

src

The explanation, for example "the key shape is already defined".

The bytes live in this struct, so the message stays valid after the parser that made it is gone.

`pub fn setMessage(self: *Diagnostics, comptime fmt: []const u8, args: anytype) void`

src

Render a message into the diagnostic, truncating on a character boundary when it does not fit.

Types

struct Span

src

Byte offsets into the source. start is the first byte the message refers to, and end is one past the last byte.

Fields

start: u32

end: u32

struct Span

src

pub const Span = Diagnostics.Span

Byte offsets into the source: the first offending byte and one past the last.

Fields

start: u32

end: u32

struct Table

src

pub const Table = @import("value.zig").Table

A table, with its keys in the order the document declared them.

Fields

entries: EntryMap

The entries, keyed by the unescaped key text.

flags: Flags

Parser bookkeeping. Readers and the writer ignore it.

Constants

`pub const empty: Table = .{ .entries = .empty, .flags = .zero }`

src

An empty table: no entries, and no declaration behind it.

Functions

`pub fn get(self: Table, key: []const u8) ?Value`

src

The value stored under key, or null.

`pub fn contains(self: Table, key: []const u8) bool`

src

Whether key is present.

`pub fn count(self: Table) u32`

src

The number of keys.

`pub fn put( self: *Table, allocator: Allocator, key: []const u8, value: Value, ) error{ DuplicateKey, OutOfMemory }!void`

src

Store value under key. Fails with error.DuplicateKey when the key is already present, so a table never silently loses an entry.

`pub fn iterator(self: Table) EntryMap.Iterator`

src

Iterate the entries in document order.

Types

struct Flags

src

pub const Flags = packed struct(u8)

What the parser remembers about how a table was declared.

Fields

header: bool

A [header] defined the table.

dotted: bool

A dotted key created the table as an intermediate step.

implicit: bool

A header created the table as an intermediate step.

sealed: bool

An inline table, or a table inside one: nothing may be added after the closing brace.

_: u4

Constants

`pub const zero: Flags = …`

src

value

.{
            .header = false,
            .dotted = false,
            .implicit = false,
            .sealed = false,
            ._ = 0,
        }

No flag set: no declaration has touched the table.

union Value

src

pub const Value = @import("value.zig").Value

A TOML value: a table, an array, a scalar, or a datetime.

Fields

string: []const u8

Bytes. A string from a parse is owned by the document's arena.

integer: i64

A signed 64-bit integer.

float: f64

An IEEE 754 binary64 float, including inf and nan.

boolean: bool

True or false.

datetime: Datetime

One of the four TOML datetime forms.

array: *Array

A TOML array, in document order.

table: *Table

A TOML table, in document order.

Functions

`pub fn eql(a: Value, b: Value) bool`

src

Whether two trees hold the same document.

Key order and the parser's bookkeeping are ignored, because neither changes what a reader of the document sees. Whether an array was written as [[x]] headers or as [ ... ] values is compared, because it changes the text the writer emits.

`pub const ParseError = Allocator.Error || error{SyntaxError}`

src

What a parse can return: the allocator failed, or the source breaks the grammar. On error.SyntaxError, the Diagnostics the caller passed says where.

struct ParseOptions

src

How to parse a document.

Fields

diagnostics: ?*Diagnostics = null

Filled on error.SyntaxError. Untouched when the parse succeeds, and on error.OutOfMemory. Null means the caller wants only the error.

struct Document

src

A parsed document and the memory that holds it.

Fields

arena: ?ArenaAllocator

The arena that owns every string, table, and array in root, when the document came from parseFromSlice. Null when it came from parseFromSliceLeaky, whose memory belongs to the caller.

root: Value

The root table.

Functions

`pub fn deinit(self: *Document) void`

src

Free the memory this document owns. Does nothing when the parse was leaky; that memory belongs to the allocator the caller passed.

`pub fn parseFromSlice( allocator: Allocator, source: []const u8, options: ParseOptions, ) ParseError!Document`

src

Parse one TOML document.

Every string, table, and array is copied into an arena that the returned Document owns, so the source may be freed as soon as this returns. Document.deinit frees the arena. A document that breaks the grammar is error.SyntaxError, and options.diagnostics says where.

`pub fn parseFromSliceLeaky( allocator: Allocator, source: []const u8, options: ParseOptions, ) ParseError!Document`

src

Parse one TOML document into memory the caller already owns.

Use this when the caller has an arena whose lifetime is known, such as a request or a configuration load. The returned document owns nothing, and Document.deinit does not free the caller's memory. The source is still copied, so it may be freed as soon as this returns.

`pub const StringifyError = Io.Writer.Error || error{ NotATable, NestingTooDeep }`

src

What stringify can fail with: the sink, a value that is not a table, or a tree nested deeper than the writer walks.

`pub fn stringify(value: Value, writer: *Io.Writer) StringifyError!void`

src

Write value as a TOML document.

value must be a table; anything else is error.NotATable. Keys are quoted only when the bare form cannot carry them. A table's values are written before its sub-tables, which is what keeps the output a valid document, so the order of a table's own keys relative to its sub-tables is not preserved.