The README makes claims. This file backs them up.
Claim 1: "Parse A2ML documents from strings or files… Render AST back to A2ML surface syntax (round-trip support)" (README, Features section)
The parser in lib/a2ml/parser.ex reads A2ML-formatted text and emits a typed AST via A2ML.Parser.parse/1, which returns {:ok, Document.t()} or {:error, reason}. The parser extracts:
-
Title from H1 heading (
# Title) -
Blocks (paragraphs, headings, code blocks, directives, attestations)
-
Directives starting with
@(e.g.,@include(file="chapter1.a2ml")) -
Attestation provenances blocks starting with
!attest
The renderer in lib/a2ml/renderer.ex reconstructs the surface syntax from the AST via A2ML.Renderer.render/1, returning {:ok, rendered_string}. This enables round-trip: parse → modify AST → render produces valid A2ML again.
How it works: The parser splits input by newlines, identifies block boundaries, and classifies each line. The Attestation struct stores identity, role, trust level, and timestamp. Directives are key-value pairs in @name(key=val): value syntax. The renderer walks the AST and reconstructs each element. Caveat: Whitespace normalization and comment stripping mean the rendered output may not be byte-for-byte identical to the input, though semantic content is preserved.
Claim 2: "Trust-level hierarchy: :unverified, :automated, :reviewed, :verified" (README, Trust Levels section)
The A2ML.Types.TrustLevel enum in lib/a2ml/types.ex defines a four-tier hierarchy. The parser extracts trust level from attestation blocks (trust-level: verified) and stores it on the Attestation struct. The types module enforces the hierarchy: :unverified < :automated < :reviewed < :verified. Document-wide trust is derived from the minimum trust level of all attestations.
How it works: Attestation blocks declare trust-level: <level>. When rendering, the renderer includes the trust level in the output. Clients can filter documents by minimum trust requirement. Caveat: Trust levels are advisory metadata—the library does not cryptographically verify signatures. Signature verification (mentioned in the README’s example) is a future feature; currently signature: field is stored as a string literal without validation.
a2ml_ex is part of the A2ML ecosystem, which includes:
-
a2ml-deno — Deno/ReScript implementation (primary)
-
tree-sitter-a2ml — Tree-sitter grammar for syntax highlighting
-
a2ml-haskell — Haskell implementation
-
standards — A2ML spec (K9 service specification)
The Elixir implementation enables A2ML parsing in BEAM-based systems (Elixir, Erlang). It follows the same type structure as the Deno version.
| Technology | Learn More | Why |
|---|---|---|
Elixir |
BEAM runtime, immutable data structures, pattern matching for AST |
|
ExUnit |
Testing framework (no external test dependency) |
|
Hex.pm |
Package distribution (MPL-2.0 requirement for Hex ecosystem) |
| Path | What’s There | Key Details |
|---|---|---|
|
A2ML text parser |
Reads lines, extracts title, parses blocks, directives, attestations |
|
AST-to-text renderer |
Reconstructs A2ML surface syntax from |
|
Type definitions |
|
|
Public API |
Re-exports parser and renderer functions |
|
Parser tests |
Round-trip tests, edge cases, error handling |
|
Build configuration |
Elixir version, Hex metadata, dependencies |