// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

= A2ML Language Bindings
:author: Jonathan D.A. Jewell
:toc: preamble
:icons: font

== Overview

Official language bindings for parsing and rendering
https://github.com/hyperpolymath/standards/tree/main/a2ml[A2ML (Attested Markup Language)]
documents. Each binding provides the same core functionality: parse A2ML source text into a
typed AST and render it back to A2ML surface syntax.

All bindings implement the A2ML v1.0.0 specification and share a common type model:

* **Document** -- top-level container with title, directives, blocks, and attestations
* **Block** -- heading, paragraph, code block, directive, attestation, list, block quote, thematic break
* **Inline** -- text, emphasis, strong, code, link
* **Directive** -- machine-readable `@name value` metadata
* **Attestation** -- provenance record with identity, role, trust level, timestamp
* **TrustLevel** -- `unverified` | `automated` | `reviewed` | `verified`

== Feature Matrix

[cols="2,1,1,1,1,1"]
|===
| Feature | Deno | Rust | Gleam | Elixir | Haskell

| Parse A2ML to AST
| Yes
| Yes
| Yes
| Yes
| Yes

| Render AST to A2ML
| Yes
| Yes
| Yes
| Yes
| Yes

| Round-trip fidelity
| Yes
| Yes
| Yes
| Yes
| Yes

| Attestation types
| Yes
| Yes
| Yes
| Yes
| Yes

| Manifest extraction
| Yes
| Yes
| Yes
| Yes
| Yes

| Serde support
| --
| Yes
| --
| --
| --

| BEAM target
| --
| --
| Yes
| Yes
| --

| JS target
| Yes
| --
| Yes
| --
| --
|===

== Quick Install

=== Deno (ReScript)

Published to https://jsr.io/@hyperpolymath/a2ml[JSR] as `@hyperpolymath/a2ml`.

[source,json]
----
// deno.json
{
  "imports": {
    "@hyperpolymath/a2ml": "jsr:@hyperpolymath/a2ml@0.1.0"
  }
}
----

=== Rust

Published to https://crates.io/crates/a2ml[crates.io] as `a2ml`.

[source,toml]
----
[dependencies]
a2ml = "0.1"
----

=== Gleam

Published to https://hex.pm/packages/a2ml_gleam[Hex.pm] as `a2ml_gleam`.

[source,sh]
----
gleam add a2ml_gleam
----

=== Elixir

Published to https://hex.pm/packages/a2ml_ex[Hex.pm] as `a2ml_ex`.

[source,elixir]
----
# mix.exs
defp deps do
  [{:a2ml_ex, "~> 0.1.0"}]
end
----

=== Haskell

Published to https://hackage.haskell.org/package/a2ml[Hackage] as `a2ml`.

[source,cabal]
----
build-depends: a2ml >= 0.1 && < 0.2
----

== Directory Layout

[source]
----
bindings/
  deno/       -- ReScript binding, published to JSR
  rust/       -- Rust crate, published to crates.io
  gleam/      -- Gleam package, published to Hex.pm
  elixir/     -- Elixir library, published to Hex.pm
  haskell/    -- Haskell library, published to Hackage
----

Each binding directory is self-contained with its own build system, tests, examples,
and documentation. See the individual `README.adoc` files for detailed API documentation.

== Licensing

The Deno binding uses PMPL-1.0-or-later directly. The Rust, Gleam, Elixir, and Haskell
bindings use MPL-2.0 as a required fallback for their respective package registries
(crates.io, Hex.pm, Hackage), which require OSI-approved licenses.

== Part of the A2ML Ecosystem

This directory is part of the link:../README.adoc[A2ML specification and tooling] in the
https://github.com/hyperpolymath/standards[standards monorepo]. See the parent directory
for the full specification, CLI tools, editor integrations, and Pandoc support.
