zon.zig

# zon.zig

A simple, direct Zig library for reading and writing ZON (Zig Object Notation) files.

Documentation | API Reference | Quick Start | Allocators | Contributing

A document-based ZON (Zig Object Notation) library for Zig, designed for configuration file editing, dynamic access, and data manipulation. Unlike std.zon which parses ZON into typed structures, zon.zig maintains an in-memory document tree that you can query, modify, and serialize.

Related Zig projects:

• For API framework support, check out api.zig.
• For web framework support, check out zix.
• For logging support, check out logly.zig.
• For data validation and serialization support, check out zigantic.
• For HTTP Server/Client support, check out httpx.zig.
• For ZON file format support, check out zon.zig
• For Args Parsing support, check out args.zig.

If you find zon.zig useful, please give it a star!

Installation

For Zig 0.16.0 support (recommended), use v0.0.5:

zig fetch --save https://github.com/muhammad-fiaz/zon.zig/archive/refs/tags/v0.0.5.tar.gz

For Zig 0.15.0, use v0.0.4:

zig fetch --save https://github.com/muhammad-fiaz/zon.zig/archive/refs/tags/0.0.4.tar.gz

or

for Nightly Installation, use this

zig fetch --save git+https://github.com/muhammad-fiaz/zon.zig.git

Then in your build.zig:

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

Quick Start

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

pub fn main() !void {
    var da = std.heap.DebugAllocator(.{}){};
    defer _ = da.deinit();
    const allocator = da.allocator();

    // Optional: Disable update checking
    zon.disableUpdateCheck();

    // Create a new ZON document
    var doc = zon.create(allocator);
    defer doc.deinit();

    // Set values
    try doc.setString("name", "myapp");
    try doc.setBool("private", true);
    try doc.setInt("port", 8080);

    // Nested paths - auto-creates intermediate objects
    try doc.setString("dependencies.http.path", "../http");

    // Read values
    std.debug.print("Name: {s}\n", .{doc.getString("name").?});

    // Save to file
    try doc.saveAs("config.zon");
}

Supported ZON Syntax

zon.zig fully supports the build.zig.zon format:

.{
    .name = .zon,                        // Identifier as value
    .version = "0.0.5",                  // String
    .fingerprint = 0xee480fa30d50cbf6,   // Multi-bit hex handled as i128
    .minimum_zig_version = "0.16.0",
    .paths = .{                          // Array of strings
        "build.zig",
        "build.zig.zon",
        "src",
        "examples",
        "README.md",
        "LICENSE",
    },
    .dependencies = .{                    // Nested objects
        .http = .{
            .url = "https://example.com",
            .hash = "abc123",
        },
    },
}

Examples

Parse build.zig.zon

const source =
    \\.{
    \\    .name = .my_package,
    \\    .version = "0.1.0",
    \\    .paths = .{
    \\        "build.zig",
    \\        "src",
    \\    },
    \\}
;

var doc = try zon.parse(allocator, source);
defer doc.deinit();

// Read identifier value
const name = doc.getString("name"); // "my_package"

// Read array
const paths_len = doc.arrayLen("paths"); // 2
const first_path = doc.getArrayString("paths", 0); // "build.zig"

Find and Replace

var doc = zon.create(allocator);
defer doc.deinit();

try doc.setString("host1", "localhost");
try doc.setString("host2", "localhost");
try doc.setString("host3", "192.168.1.1");

// Find all paths containing "localhost"
const found = try doc.findString("localhost");
defer allocator.free(found);
// found.len == 2

// Replace all occurrences
const count = try doc.replaceAll("localhost", "production.example.com");
// count == 2

// Replace first occurrence only
const replaced = try doc.replaceFirst("old", "new");

// Replace last occurrence only
const replaced_last = try doc.replaceLast("old", "new");

Array Operations

// Create array and append
try doc.setArray("items");
try doc.appendToArray("items", "first");
try doc.appendToArray("items", "second");
try doc.appendIntToArray("numbers", 42);

// Read array
const len = doc.arrayLen("items"); // 2
const elem = doc.getArrayString("items", 0); // "first"

Pretty Print

// Default 4-space indentation
const output = try doc.toString();

// Custom indentation
const two_space = try doc.toPrettyString(2);

// Compact (no indentation)
const compact = try doc.toCompactString();

Merge and Clone

var base = zon.create(allocator);
try base.setString("name", "app");
try base.setInt("port", 8080);

var override = zon.create(allocator);
try override.setInt("port", 9000);
try override.setBool("debug", true);

// Merge override into base
try base.merge(&override); // Shallow merge
try base.mergeRecursive(&override); // Deep merge (merges nested objects)
// base now has port=9000, debug=true

// Deep equality
if (base.eql(&override)) { ... }

// Deep clone
var copy = try base.clone();
defer copy.deinit();

API Reference

Module Functions

Document Methods - Getters

Document Methods - Setters

Document Methods - Array Operations

Document Methods - Find & Replace

Document Methods - Other

Examples Directory

The examples/ directory contains comprehensive examples:

• basic.zig - Core operations and getting started
• package_manifest.zig - Parsing build.zig.zon format
• find_replace.zig - Find and replace operations
• arrays.zig - Array operations
• pretty_print.zig - Pretty printing with different indentation
• merge_clone.zig - Merging and cloning documents
• config_management.zig - Configuration file management
• file_operations.zig - Atomic writes, backups, and file helpers
• identifier_values.zig - Identifier value parsing and usage
• nested_creation.zig - Creating deeply nested structures
• error_handling.zig - Examples of parse and file error handling
• walk_map.zig - Walking and mapping values in documents
• pick_omit.zig - Creating document subsets with pick and omit
• sort_format.zig - Key sorting and stringify sort_keys option
• validation_sort.zig - Type checking, case utilities, array sorting, truncation, filter

File helpers and utilities

Added file helpers for safer file operations:

• zon.readFile(path, allocator) - Read file contents into allocator-managed buffer
• zon.writeFileAtomic(path, contents) - Atomically write using a temporary file + rename
• zon.copyFile(src, dest, overwrite) - Copy file with optional overwrite
• zon.moveFile(src, dest, overwrite) - Move/rename file with optional overwrite
• Document.saveAsAtomic(path) - Save a document atomically
• Document.saveWithBackup(path) - Save and create a .bak backup of the previous file
• Document.saveIfChanged() - Only write when contents differ (normalizes trailing newline; returns true if a write occurred)

Building

# Run tests
zig build test

# Build library
zig build

# Run example
zig build example

# Format code
zig fmt src/ examples/

Documentation

Full documentation: https://muhammad-fiaz.github.io/zon.zig/

Benchmarks

[!NOTE] Benchmarks vary by OS, platform, hardware, and system load. Benchmark results for each release can be found at Releases.

Environment Details:

• Platform: windows
• Architecture: x86_64
• Warmup Iterations: 100
• Benchmark Iterations: 10000

Benchmark Summary

• Total benchmarks run: 6
• Average throughput: 19942 ops/sec
• Maximum throughput: 47340 ops/sec (Read Access (100 ops))
• Minimum throughput: 820 ops/sec (Modification (100 ops))
• Average latency: 50144 ns

Contributing

Contributions are welcome! Please read CONTRIBUTING.md.

License

MIT License - see LICENSE.

Links

• Documentation: https://muhammad-fiaz.github.io/zon.zig/
• Repository: https://github.com/muhammad-fiaz/zon.zig
• Issues: https://github.com/muhammad-fiaz/zon.zig/issues
• Releases: https://github.com/muhammad-fiaz/zon.zig/releases