vercel-labs--zerolang/docs/articles/modules/toml.md

When To Use std.toml

In Zerolang, use std.toml for TOML validation, shallow field lookup, and typed scalar decode helpers.

Runnable today:

API	Return	Notes
std.toml.validate(text)	Bool	Checks the current TOML subset without allocation.
std.toml.validateBytes(bytes)	Bool	Checks a Span<u8> TOML payload without allocation.
std.toml.field(bytes, key)	Maybe<Span<u8>>	Returns the raw value for a direct, dotted, or shallow table field.
std.toml.stringDecode(buffer, value)	Maybe<Span<u8>>	Decodes a TOML string value into caller storage.
std.toml.string(buffer, bytes, key)	Maybe<Span<u8>>	Looks up and decodes a TOML string field.
std.toml.u32(bytes, key)	Maybe<u32>	Looks up and decodes an unsigned integer field.
std.toml.i32(bytes, key)	Maybe<i32>	Looks up and decodes a signed integer field.
std.toml.bool(bytes, key)	Maybe<Bool>	Looks up and decodes a boolean field.
std.toml.arrayCount(value)	Maybe<usize>	Counts items in a raw array value.
std.toml.arrayValue(value, index)	Maybe<Span<u8>>	Borrows a raw array item by ordinal.
std.toml.arrayString(buffer, value, index)	Maybe<Span<u8>>	Decodes a string array item into caller storage.
std.toml.arrayU32(value, index)	Maybe<u32>	Decodes an unsigned integer array item.
std.toml.arrayI32(value, index)	Maybe<i32>	Decodes a signed integer array item.
std.toml.arrayBool(value, index)	Maybe<Bool>	Decodes a boolean array item.
std.toml.writeKeyValueString(buffer, key, value)	Maybe<Span<u8>>	Writes one string key/value line.
std.toml.writeKeyValueU32(buffer, key, value)	Maybe<Span<u8>>	Writes one unsigned integer key/value line.
std.toml.writeKeyValueBool(buffer, key, value)	Maybe<Span<u8>>	Writes one boolean key/value line.
std.toml.writeTableHeader(buffer, table)	Maybe<Span<u8>>	Writes one table header line.

Metadata labels:

• effects: parse
• allocation behavior: allocation-free; decoded strings and writer output use caller storage
• target support: target-neutral
• error behavior: Maybe helpers return null on malformed or missing fields
• ownership notes: returned raw fields borrow from the input span; decoded strings borrow from the caller buffer
• examples: conformance/native/pass/std-toml-basic.graph

Example

pub fn main(world: World) -> Void raises {
    let input: Span<u8> = "[package]\nname = \"demo\"\n\n[features]\ngraph = true\nlevels = [1, 2, 3]\n"
    var name_buffer: [16]u8 = [0_u8; 16]
    let name: Maybe<Span<u8>> = std.toml.string(name_buffer, input, "package.name")
    let graph: Maybe<Bool> = std.toml.bool(input, "features.graph")
    let levels: Maybe<Span<u8>> = std.toml.field(input, "features.levels")
    var count: Maybe<usize> = null
    if levels.has {
        count = std.toml.arrayCount(levels.value)
    }
    if std.toml.validateBytes(input) && name.has && graph.has && graph.value && count.has && count.value == 3 {
        check world.out.write("toml ok\n")
    }
}

Design Notes

The current TOML helper surface is deliberately narrow. It supports the package manifest subset used by Zero packages: tables, dotted keys, strings, booleans, integers, scalar arrays, and small writer helpers. Field lookup is shallow and table-aware, so std.toml.string(buffer, input, "package.name") can read name inside a [package] table.

The helpers avoid hidden allocation. Use field when a raw value slice is enough, and use string or stringDecode when escape decoding into explicit caller storage is required.