Skip to content
lejmrPublic

About

HOCON (Human-Optimized Config Object Notation) parser for Zig

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

zig-hocon

Read HOCON config files into your own Zig structs, the way std.json reads JSON.
Includes, substitutions, merging, environment variables, durations and sizes; no dependencies beyond the standard library.
The same core also ships as the hocon command line tool, a C library and a Python package.

Install · Use · Command line & C · Python · Conformance

Beta: the API can change before 1.0 (CHANGELOG.md).

Install

Requires Zig 0.16.

zig fetch --save https://github.com/lejmr/zig-hocon/archive/refs/tags/v0.6.1.tar.gz
// build.zig
const hocon = b.dependency("hocon", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("hocon", hocon.module("hocon"));

Use

# app.conf
db {
  host = localhost
  pool = 4
}
timeout = 30s
cache = 512MiB
# prod.conf
include required("app.conf")
db.host = db.example.org
db.pool = ${?DB_POOL}   # only when DB_POOL is set
const std = @import("std");
const hocon = @import("hocon");

const Config = struct {
    db: struct { host: []const u8, pool: u16 },
    timeout: hocon.Duration,
    cache: hocon.Size,
    debug: bool = false,
};

pub fn main(init: std.process.Init) !void {
    const parsed = try hocon.parseFromFile(Config, init.gpa, init.io, "prod.conf", .{
        .env = .{ .map = init.environ_map },
    });
    defer parsed.deinit();
    const config = parsed.value;
    std.debug.print("{s} pool {d}, timeout {d} s\n", .{ config.db.host, config.db.pool, config.timeout.whole(.s) });
    // db.example.org pool 4 (or $DB_POOL), timeout 30 s; config.cache.whole(.B) == 536870912
}

A field can be any integer, float, bool, string, slice, array, struct (with defaults), enum, optional, tagged union, hocon.Duration, hocon.Size, hocon.Period.

Unlike std.json, unknown keys are skipped; set .ignore_unknown_fields = false to catch a misspelled key.

Errors

They are plain Zig errors. To see where, pass .diagnostics = &diag, and diag.render(writer) prints it the way the compiler would:

var diag: hocon.Diagnostics = .{};
defer diag.deinit(init.gpa);
const parsed = hocon.parseFromFile(Config, init.gpa, init.io, "prod.conf", .{
    .env = .{ .map = init.environ_map },
    .diagnostics = &diag,
}) catch |err| {
    var buffer: [1024]u8 = undefined;
    var stderr = std.Io.File.stderr().writerStreaming(init.io, &buffer);
    try diag.render(&stderr.interface);
    try stderr.interface.flush();
    return err;
};
defer parsed.deinit();

With DB_POOL=eight:

prod.conf:4:11: error: InvalidCharacter at db.pool: expected u16
db.pool = ${?DB_POOL}   # only when DB_POOL is set
          ^

Beyond Zig

  • Command line: hocon prints a config resolved, writes one deployable file with the ${…} left to resolve at run time, gets one value for a script, checks files against a Zig struct (--schema), and diffs two configs as they resolve: docs/cli.md.
  • C: libhocon for Linux, macOS and Windows on the releases page, or zig build lib; c/hocon.h is its documentation.
  • Python: pip install zig-hocon, see python/README.md.

The hocon command, C and Python read the process environment by default, where the Zig library reads none: docs/production.md has the defaults of each.

Conformance

HOCON had no shared, implementation-neutral test suite, the way JSON has JSONTestSuite and TOML toml-test, so this repository carries one, meant as a reference for any HOCON implementation: cases derived from the sentences of the prose spec, each a config file, with its includes and environment, and the JSON it must resolve to, or a rejection. It checks end to end, text in and resolved value out, so any parser can be scored through a ten-line adapter. Where the spec leaves room, the suite takes one reading and says so.

zig-hocon is the first parser built against it, and passes all of them. lightbend/config, the reference implementation, departs from the spec in places, through bugs (several reported upstream), deliberate choices and leniency; each such case records what it does, so conformance/run.sh --java scores a parser against lightbend/config instead. How other parsers score: conformance/README.md; every case: the report.

AI disclosure

I wrote the first working version by hand. The whole spec turned out to be much more, so from then on I switched to AI-augmented development: I broke the product into features, had them implemented one by one, and reviewed each. I use this library for my own services, and it will be maintained. More in What I learned writing a HOCON parser as my first Zig project.

Contributing

A failing test that shows what you need is the fastest way to get it; CONTRIBUTING.md has the workflow. BSD 3-Clause, see LICENSE.

About

HOCON (Human-Optimized Config Object Notation) parser for Zig

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages