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).
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"));# 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 setconst 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.
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
^
- Command line:
hoconprints 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.his 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.
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.
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.
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.
