What I learned writing a HOCON parser as my first Zig project

Sun, 11 Oct 2026 00:00:00 +0000

I have decided to build a tool that will resolve my configuration dilemma for all languages at once. The tool has a CLI and a native API. Point it at a config file and it prints what your service will really read: includes spliced in, substitutions resolved against the environment it will run in, duplicate keys merged, the whole thing as JSON.

I built a HOCON conformance suite. It found bugs in the reference implementation.

Sat, 10 Oct 2026 00:00:00 +0000

I have used HOCON in production for years. I like the format because it is readable and it allows config file composition, so it allows simple multi-environment config shared config files overrides minimizing config differences. As a Python developer, my ultimate combo for config management is Pydantic + pyhocon.

I like to try new things, so this June my eyes landed on Zig. I wanted to go back to the roots of programming and see what a modern “C” feels like. After reading the language reference I needed a project, and knowing the Java and Python implementations of HOCON don’t fully agree, it gave me an idea: “Zig has a native C interface, so why not write HOCON in Zig and expose it through C shim? Then every language can share one implementation. Magic!”

What a simple project I have picked, right?

Writing the tokenizer, the abstract syntax tree, the config and the resolution is the beautiful part. But right after the first implementation works, the question comes: am I really compatible? Luckily there is a written spec and a whole internet of examples. Well, it turned out the spec and the reference implementation do not always agree. Here is a basic config that contains an error:

hosts = [db1, db2] db3

The spec says an array next to a string in a concatenation is invalid. lightbend/config 1.4.9, the reference implementation, the one the spec was written for, gives you this:

{"hosts":["db1","db2"]}

No error, no warning. db3 is gone. Write it the other way round, db3 [db1, db2], and you get the error you were promised.

So before going further with the parser, I wrote down what HOCON is supposed to do. That became a conformance suite: 445 cases, each one a sentence of the spec turned into a config file and the value it must produce. lightbend/config 1.4.9 passes 90% of them, pyhocon 70%. My Zig parser, zig-hocon, 69%, and from here on it is built against the suite.

Parsing on Miloš Kozák

What I learned writing a HOCON parser as my first Zig project

I built a HOCON conformance suite. It found bugs in the reference implementation.