z-toml

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

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 0.17.0.

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

.dependencies = .{
    .z_toml = .{
        .url = "https://github.com/eneskemalergin/z-toml/archive/refs/tags/v0.4.1.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

Direction, not a schedule. Items land when they are ready.

• Documentation: guides and reference material for parsing, typed mapping, faithful output, and rewrites.
• CLI: to-json, fmt, lint, and rewrite commands, then extensions shaped by user feedback.
• Typed serialization: complete round trips, with parseInto(T) for reads and writeFromStruct(T) for writes.
• Config overlays: merge parsed trees, for layered configuration.
• Composability: zero-copy views together with format hints.
• Zig releases: keep up with new Zig versions as they ship.

License

MIT. See LICENSE.

---

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