z-toml

TOML v1.1.0 parser and rewrite toolkit for Zig 0.16.

Typed parse. Dynamic trees. Zero-copy views. Faithful output. Byte-local rewrites.

z-toml is built for tools that need more than parse-and-print. It gives you a single-pass TOML parser, a zero-copy read path, profile-based writers, and structured-path rewrites that preserve untouched bytes around the edit.

Highlights

• parseInto(T) maps TOML directly onto Zig structs.
• parseSlice gives you a dynamic tree for unknown document shapes.
• parseSliceView borrows strings from the input buffer for zero-copy reads.
• writeTomlWithProfile supports compact, preserve, canonical, and faithful output modes.
• rewriteValueAtPath, setValueAtPath, and rewriteValues perform structured-path edits without reserializing the whole file.
• toJson, writeToml, and writeTomlView cover export, roundtrip, and view-based output flows.
• The core is zero-dependency, corpus-validated, and backed by explicit test, validate, and fuzz gates.

Quick Look

const std = @import("std");
const toml = @import("toml");

pub fn main() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const gpa = arena.allocator();

    const src =
        \\title = "My App"
        \\[server]
        \\port = 8080
    ;

    const root = try toml.parseSlice(gpa, src, null);
    defer toml.deinit(root, gpa);

    const port = root.get("server").?.table.get("port").?.integer.value;
    _ = port;
}

try toml.rewriteValueAtPath(
    src,
    &[_]toml.PathSegment{ .{ .key = "server" }, .{ .key = "port" } },
    .{ .integer = .{ .value = 9090 } },
    &writer,
    gpa,
);

Install

Requires Zig 0.16.0 or later.

zig fetch --save https://github.com/eneskemalergin/z-toml/archive/refs/tags/v0.4.0.tar.gz

.dependencies = .{
    .z_toml = .{
        .url = "https://github.com/eneskemalergin/z-toml/archive/refs/tags/v0.4.0.tar.gz",
        .hash = "<run zig fetch to get the hash>",
    },
};

const z_toml = b.dependency("z_toml", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("toml", z_toml.module("toml"));

Validation

• zig build test runs the package suite and corpus-backed checks.
• zig build validate runs the end-to-end real-document validation gate.
• zig build fuzz runs the 5000-iteration fuzz harness.

Roadmap

• v0.4.0: faithful output, structured-path rewrites, spans, and real-document validation.
• v0.4.1: detailed documentation, guides, and reference material.
• v0.5.0: CLI with to-json, fmt, lint, and rewrite commands.

License

MIT. See LICENSE.

Keys nest in the deep,
One pass clears the tangled brush,
The value remains.