Coda

A compact configuration format designed to be easy to read and write. The name comes from music — a coda is the concluding passage that ties a composition together. A .coda file is the single source of truth for configuration.

The above file in JSON:

---

What is Coda?

• Whitespace-sensitive, line-oriented.
• Every leaf value is a string; interpretation is left to the consumer.
• Quotes are optional unless a value contains whitespace or syntax characters ({}[]"#).
• Comments are preserved and attach to the node that follows them.

Coda has three structural constructs: blocks {}, arrays [], and tables (inferred from array headers). For the full language specification, see docs/SPEC.md.

---

Installation

Python — install the pre-built package from PyPI (includes the compiled native library):

pip install coda-format

import coda

with coda.Doc.parse_file("config.coda") as doc:
    print(doc.root()["key"])

C++ — Coda is a header-only library. Use the generated single header include/coda.hpp from a release artifact, or generate it from a source checkout before copying/symlinking it into your project:

devbox run -- just generate

#include "path/to/coda.hpp"

C FFI / other languages — build the shared library with just build (see Building & testing below).

OCaml — the source tree includes Dune bindings in bindings/ocaml/, backed by the same C FFI implementation:

devbox run -- just test-ocaml

open Coda

match parse_file "config.coda" with
| Ok doc ->
    let root = root doc in
    (match map_get doc root "key" with
     | Some node -> print_endline (string_get doc node)
     | None -> ())
| Error e -> prerr_endline e.message

---

API documentation

API	File
C++ header (include/coda.hpp)	docs/API-CPP.md
Python bindings (bindings/python/coda.py)	docs/API-PYTHON.md
OCaml bindings (bindings/ocaml/)	docs/API-OCAML.md
C FFI (ffi/coda_ffi.h)	docs/API-C-FFI.md

---

Building & testing

This repo is built and tested inside a Devbox environment (which pins zig, just, python3, dune, and ocaml). just recipes are thin wrappers around scripts/tasks.py.

devbox run -- just test         # run all tests (C++, C FFI, Python, OCaml)
devbox run -- just generate     # regenerate include/coda.hpp (requires quom)
devbox run -- just build        # build host shared library (build/libcoda_ffi.so)
devbox run -- just cross-all    # cross-compile for all supported targets
devbox run -- just test-cpp
devbox run -- just test-c-ffi
devbox run -- just test-py-ffi
devbox run -- just test-ocaml

include/coda.hpp is a generated single-header amalgamation (git-ignored); the build recreates it on demand. The source of truth is src/.

All four language test suites are driven by a single catalog, tests/catalog/catalog.coda. To add a test, edit that file. See contributing/.

Cross-compiled FFI artifacts are placed under dist/<target>/.