// SPDX-License-Identifier: PMPL-1.0-or-later // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk = k9_gleam :toc: preamble :icons: font :author: Jonathan D.A. Jewell :email: j.d.a.jewell@open.ac.uk

K9 parser and renderer for Gleam — compiles to BEAM and JavaScript.

image:https://img.shields.io/badge/License-PMPL--1.0--or--later-blue.svg[License: PMPL-1.0-or-later] image:https://img.shields.io/badge/language-Gleam-pink.svg[Gleam] image:https://img.shields.io/badge/targets-BEAM%20%2B%20JS-green.svg[BEAM + JS]

== What this is

k9_gleam is the Gleam implementation of the K9 configuration format. K9 is a self-validating component specification format with three graduated security levels: Kennel (data), Yard (contracts), Hunt (execution).

Because Gleam compiles to both Erlang bytecode (BEAM) and JavaScript, this single library works in Elixir/Erlang projects, Deno scripts, and browser applications — from the same source.

== Quick start

Add to gleam.toml:

[source,toml]

[dependencies] k9_gleam = ">= 0.1.0"

Then:

[source,gleam]

import k9

case k9.parse(content) { Ok(doc) -> io.debug(doc) Error(err) -> io.println("Parse error: " <> err.message) }

== Cross-compilation

[source,bash]

Build for BEAM (Erlang/Elixir)

gleam build

Build for JavaScript (Deno, Node, browser)

gleam build --target javascript

Run tests on both targets

gleam test

Both produce identical behaviour — no platform-specific code paths.

== Module layout

[cols="2,3", options="header"] |=== | Module | Purpose

| src/k9/parser.gleam | Recursive descent parser: parse(String) -> Result(Document, ParseError)

| src/k9/types.gleam | K9 type system: Document, Value, Key, Type, Metadata

| src/k9/validation.gleam | Post-parse validation: duplicate keys, type consistency

| src/k9.gleam | Public API: parse/1, render/1, validate/1

| test/ | Test suite exercised on both BEAM and JS targets |===

== K9 security levels

[cols="1,3", options="header"] |=== | Level | What it permits

| Kennel (.k9) | Pure data. Safe to process from any source.

| Yard (.k9.ncl, unevaluated) | Nickel contracts for typed validation. No shell access.

| Hunt (.k9.ncl, signed) | Executable recipes. Requires a valid cryptographic signature. |===

== K9 ecosystem

• https://github.com/hyperpolymath/k9-rs[k9-rs] — Rust (reference implementation)
• https://github.com/hyperpolymath/k9_ex[k9_ex] — Elixir
• https://github.com/hyperpolymath/k9-haskell[k9-haskell] — Haskell
• https://github.com/hyperpolymath/tree-sitter-k9[tree-sitter-k9] — Editor grammar

See link:EXPLAINME.adoc[EXPLAINME.adoc] for implementation evidence and caveats.

== License

PMPL-1.0-or-later. See LICENSE.

== Author

Jonathan D.A. Jewell + j.d.a.jewell@open.ac.uk