kdl-roc

KDL v2 as a pure Roc package: bytes in, a Document out, and a Document back to bytes.

Passes the whole of kdl-org/kdl's tests/test_cases: 243 documents parse and print back to the canonical form recorded there, and 95 malformed ones are refused.

API documentation

Use

app [main!] {
    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.22.0/F1JVZPYfWP71s8vk6tHcV1Qx1Ef6CZkwswGoCn8VHZmL.tar.zst",
    kdl: "https://github.com/grodaus/kdl-roc/releases/download/v0.2.0/FnDzJk4JDN7TstpRX4tk8CimFnGh4E9yCCBoiJ4EsKvJ.tar.zst",
}

import pf.Stdout
import pf.Stderr
import kdl.Canonical
import kdl.Kdl
import kdl.Refusal

main! = |_args| {
    source =
        \\package {
        \\  name "kdl-roc"
        \\  version "0.2.0"
        \\}

    match Kdl.parse(source) {
        Ok(document) => Stdout.write!(Canonical.print(document))?
        Err(Refused(refusal)) => Stderr.line!("not KDL: ${Refusal.to_str(refusal)}")?
    }

    Ok({})
}

Four modules are exposed. Kdl.parse reads a source text. Canonical.print writes the one spelling the KDL test suite records, and Canonical.print_pretty writes the same document with a chosen indent and multi-line strings kept across lines. Document is the model both directions speak in, with Document.node and Document.value for assembling one by hand. Refusal enumerates every way a text is not KDL.

A package cannot reach platform effects, so nothing here reads a file or a socket — whoever holds the bytes decides where they came from.

Develop

The flake pins the Roc nightly that compiles the package and the kdl checkout the test corpus is generated from.

nix develop
roc test lib/main.roc     # the unit expects
roc test test/main.roc    # every case in the kdl-org corpus
nix flake check           # both suites, corpus freshness, and formatting
nix build .#docs          # the API documentation
nix build .#bundle        # the release archive

test/Corpus.roc is generated, never edited. scripts/gen-corpus.nu "$KDL_TEST_CASES" test/Corpus.roc regenerates it, and the corpus check fails when the committed copy disagrees with the pinned checkout.

CONTEXT.md is the vocabulary: every term the modules are named after, and what each one is not.

Release

The archive's file name is the content hash roc resolves the dependency URL by, so the release asset has to keep the name nix build .#bundle produces.

nix build .#bundle
gh release create vX.Y.Z result/*.tar.zst

Then update the URL in this file.

License

Apache-2.0. See LICENSE and NOTICE.