Metadata-Version: 2.4
Name: coda-format
Version: 3.1.0
Summary: Python bindings for the Coda configuration format
License-Expression: MIT
Project-URL: Homepage, https://github.com/zane-lang/coda
Project-URL: Repository, https://github.com/zane-lang/coda
Project-URL: Issues, https://github.com/zane-lang/coda/issues
Keywords: coda,configuration,parser,format
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# <img height="80" align="right" src="https://raw.githubusercontent.com/zane-lang/logos/refs/heads/main/coda/coda.svg" /> <br> Coda

<img width="700" alt="imprint_coda_20260403010920" src="images/coda-example.svg" />

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:

<img width="700" alt="imprint_coda_20260403010924" src="https://github.com/user-attachments/assets/fde8d7b5-3dd0-42ac-a640-980de4baf017" />

---

## 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`](docs/SPEC.md).

---

## Installation

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

```bash
pip install coda-format
```

```python
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:

```bash
devbox run -- just generate
```

```cpp
#include "path/to/coda.hpp"
```

**C FFI / other languages** — build the shared library with `just build` (see [Building & testing](#building--testing) below).

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

```bash
devbox run -- just test-ocaml
devbox run -- just test-crystal
```

```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
```

**Crystal** — the source tree includes Crystal bindings in `bindings/crystal/`, linked against a static build of the same C FFI:

```bash
devbox run -- just build-crystal    # build/crystal/libcoda_ffi.a
```

```crystal
require "path/to/coda/bindings/crystal/coda"

Coda::Doc.parse_file("config.coda") do |doc|
  puts doc.root["key"]
end
```

---

## API documentation

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

---

## Building & testing

This repo is built and tested inside a [Devbox](https://www.jetify.com/devbox)
environment (which pins zig, just, python3, dune, ocaml, and crystal). `just` recipes are
thin wrappers around `scripts/tasks.py`.

```bash
devbox run -- just test         # run all tests (C++, C FFI, Python, OCaml, Crystal)
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 five language test suites are driven by a single catalog,
> `tests/catalog/catalog.coda`. To add a test, edit that file. See
> [`contributing/`](contributing/README.md).

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