API Overview

Complete API reference for zon.zig — a document-based ZON library.

Document vs Type-Based API

zon.zig provides a document-based (DOM-like) API where you work with a Document object containing a Value tree. This differs from Zig's std.zon which deserializes directly into typed Zig structures.

Use zon.zig when you need to edit, search, or manipulate ZON files dynamically.

Module Functions

Top-level functions exposed by the zon module.

Document Creation

const zon = @import("zon");

// Create empty document (aliases: init, new)
var doc = zon.create(allocator);

// Open file (aliases: load, fromFile)
var doc = try zon.open(allocator, "config.zon");

// Parse string (aliases: fromSource, parseString)
var doc = try zon.parse(allocator, source);

// Load or Create
var doc = try zon.loadOrCreate(allocator, "settings.zon", ".{}");

File Utilities

// Check if file exists
if (zon.fileExists("config.zon")) { ... }

// Read file into allocator-owned buffer (caller frees)
const contents = try zon.readFile(allocator, "config.zon");
allocator.free(contents);

// Copy file (overwrite = true to replace destination)
try zon.copyFile("source.zon", "dest.zon", true);

// Move (rename) file (alias: renameFile)
try zon.moveFile("old.zon", "new.zon", true);

// Delete file (alias: removeFile)
try zon.deleteFile("temp.zon");

// Key Operations (alias: movePathInFile, copyPathInFile)
try zon.movePathInFile(allocator, "config.zon", "old.key", "new.key");

// Write atomically (writes to temp and renames)
try zon.writeFileAtomic(allocator, "out.zon", sourceData);

// Delete file
try zon.deleteFile("temp.zon");

Update Checking

// Disable update notifications
zon.disableUpdateCheck();

// Enable update notifications
zon.enableUpdateCheck();

// Check if enabled
if (zon.isUpdateCheckEnabled()) { ... }

// Manual check
zon.checkForUpdates(allocator);

Version

// Get version string
std.debug.print("Version: {s}\n", .{zon.version});

Document Methods

Getters

Method	Return	Description
getString(path)	?[]const u8	Get string value
getIdentifier(path)	?[]const u8	Get identifier value
getBool(path)	?bool	Get boolean value
getInt(path)	?i64	Get integer value
getFloat(path)	?f64	Get float value
getNumber(path)	?f64	Alias for getFloat
getValue(path)	?*const Value	Get raw Value

Setters

Method	Description
setString(path, value)	Set string value
setIdentifier(path, value)	Set identifier (.value)
setBool(path, value)	Set boolean value
setInt(path, value)	Set integer value
setFloat(path, value)	Set float value
setNumber(path, value)	Alias for setFloat
setNull(path)	Set to null
setObject(path)	Create empty object
setArray(path)	Create empty array
setValue(path, value)	Set raw Value

Checkers

Method	Return	Description
exists(path)	bool	Check if path exists
isNull(path)	bool	Check if value is null
isIdentifier(path)	bool	Check if value is identifier
getType(path)	?[]const u8	Get base type name
getTypeName(path)	?[]const u8	Get precise type name
isNan(path)	bool	Check if value is NaN
isInf(path)	bool	Check if value is Inf
isEmpty()	bool	Check if document empty

Modification

Method	Return	Description
delete(path)	bool	Delete key
clear()	void	Clear all data
count()	usize	Number of root keys
keys()	![][]const u8	Get all root keys

Array Operations

Method	Return	Description
arrayLen(path)	?usize	Get array length
getArrayElement(path, index)	?*const Value	Get element
getArrayString(path, index)	?[]const u8	Get string element
getArrayInt(path, index)	?i64	Get integer element
getArrayBool(path, index)	?bool	Get boolean element
appendToArray(path, string)	!void	Append string
appendIntToArray(path, int)	!void	Append integer
appendFloatToArray(path, float)	!void	Append float
appendBoolToArray(path, bool)	!void	Append boolean
removeFromArray(path, index)	bool	Remove item
insertStringIntoArray(path, idx, val)	!void	Insert string
insertIntIntoArray(path, idx, val)	!void	Insert integer
indexOf(path, value)	?usize	Find string index
countAt(path)	usize	Count items at path

Find & Replace

Method	Return	Description
findString(needle)	![][]const u8	Find paths containing
findExact(needle)	![][]const u8	Find paths with exact match
replaceAll(find, replace)	!usize	Replace all occurrences
replaceFirst(find, replace)	!bool	Replace first occurrence
replaceLast(find, replace)	!bool	Replace last occurrence

Merge & Clone

Method	Return	Description
merge(other)	!void	Shallow merge document
mergeRecursive(other)	!void	Recursive (deep) merge
clone()	!Document	Create deep copy
eql(other)	bool	Deep equality check
diff(other)	![][]const u8	Get differing keys

Extra Conversions

Method	Return	Description
getUint(path)	?u64	Get u64 value (hashes, etc.)
toBool(path)	bool	Coerce value to boolean

Output

Method	Return	Description
toString()	![]u8	4-space indent
toCompactString()	![]u8	No indentation
toPrettyString(indent)	![]u8	Custom indent
save()	!void	Save to original path
saveAs(path)	!void	Save to new path

Cleanup

doc.deinit(); // Always call when done

Value Types

Value Union

pub const Value = union(enum) {
    null_val,
    bool_val: bool,
    number: Number,
    string: []const u8,
    identifier: []const u8,
    object: Object,
    array: Array,
};

Value Methods

Method	Return	Description
asString()	?[]const u8	Get as string
asIdentifier()	?[]const u8	Get as identifier
asBool()	?bool	Get as boolean
asInt()	?i64	Get as integer
asFloat()	?f64	Get as float
asObject()	?*Object	Get as object
asArray()	?*Array	Get as array
isNull()	bool	Check if null
isIdentifier()	bool	Check if identifier
clone(allocator)	!Value	Deep copy
deinit(allocator)	void	Free memory

Error Types

ParseError

pub const ParseError = error{
    UnexpectedToken,
    InvalidNumber,
    InvalidString,
    UnterminatedString,
    OutOfMemory,
};

Type Name Strings

The getType() method returns these strings:

Value	Type String
null	"null"
true/false	"bool"
Integer	"int"
Float	"float"
"string"	"string"
.identifier	"identifier"
.{ ... } object	"object"
.{ ... } array	"array"

Quick Reference

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

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

    zon.disableUpdateCheck();

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

    // Set
    try doc.setIdentifier("name", "myapp");
    try doc.setString("version", "1.0.0");
    try doc.setInt("port", 8080);
    try doc.setBool("debug", true);
    try doc.setFloat("rate", 0.05);
    try doc.setNull("password");

    // Nested
    try doc.setString("db.host", "localhost");
    try doc.setInt("db.port", 5432);

    // Arrays
    try doc.setArray("paths");
    try doc.appendToArray("paths", "src");
    try doc.appendToArray("paths", "lib");

    // Get
    const name = doc.getIdentifier("name").?;
    const port = doc.getInt("port").?;
    const len = doc.arrayLen("paths").?;

    // Check
    _ = doc.exists("port");
    _ = doc.isNull("password");
    _ = doc.isIdentifier("name");
    _ = doc.getType("port");

    // Modify
    _ = doc.delete("debug");

    // Output
    const output = try doc.toString();
    defer allocator.free(output);

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