| title | fig |
|---|---|
| author | adammharris |
| created | 2026-05-08 |
| updated | 2026-05-13 23:34:56 -0700 |
fig is a Zig library for parsing and editing config files.
It intends to support editing frontmatter in markdown files, as well as other kinds of embedded metadata.
It is currently in early alpha. Most features are not implemented yet.
- Design token, parser, document architecture
- Design cross-config interface (public Zig API)
- Embedded config (i.e. markdown frontmatter)
- Command-line interface
- C ABI
- Quality check
- Publish
Other planned features:
- JSONC, JSON5, YAML (1.2.2), TOML (1.1)
- Rust bindings + publish as crate
- Richer parse errors across the C ABI: the parse entry point currently returns only a status code (no message, line, or column). Consumers like Diaryx surface YAML errors to users, so the ABI should be extended to return parse diagnostics (message + source location).
- Round-trip byte matching
- Edit in place + sorting, both in files and in other plain text files
- Conversion between different config formats
Out of scope:
- Many advanced config language features, like anchors and multi-documents
Contibutions
Contributions are welcome, subject to my approval.
AI Use
fig, like many deceptively simple systems-level codebases, require careful thought and intention. AI tools can generate code rapidly, often at the cost of this important design thinking. Therefore, I have chosen to limit the use of AI code generation in this codebase.
I started writing this library by hand (no AI) for my own education, and for use in my larger project, Diaryx. After writing a JSON tokenizer and parser by hand, and designing the Document, Token, and Language abstractions, I have decided to make use of the Codex AI tool to generate specific portions of the code that would otherwise require hours of tedious, repetitive work. So far, this includes:
- Portions of
src/yaml/tokenizer.zig. (GPT-5.5-medium, commit 776ca93) - Most of
src/yaml/parser.zig. (GPT-5.5-medium, commit a6dceb2, commit 963bfb3) - The Rust bindings (GPT-5.5-medium, commit fbf4c82).
This code was carefully reviewed and edited according to my taste before being accepted.
License
Not licensed for now. Please contact me at amh421@icloud.com if you would like to use this code in your work!
Credits
I took the JSON test suite at testdata/json from Nicolas Seriot's JSONTestSuite repository. I'm grateful that it is licensed under the MIT license, so I am allowed to use it for fig. A copy of the license is included in this repository at testdata/json/LICENSE.