diff --git a/README.adoc b/README.adoc deleted file mode 100644 index de4b821..0000000 --- a/README.adoc +++ /dev/null @@ -1,234 +0,0 @@ -= a2ml_ex -:toc: preamble -:icons: font - -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices, link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/a2ml_ex"] - -== Overview - -**Elixir implementation of A2ML (Attested Markup Language) parser and renderer.** - -A2ML is a structured markup language with built-in attestation provenance, directive metadata, and trust-level tracking. This library provides a complete parser and renderer for A2ML documents in pure Elixir. - -== Features - -* Parse A2ML documents from strings or files -* Render AST back to A2ML surface syntax (round-trip support) -* Typed AST with structs for blocks, inlines, directives, and attestations -* Trust-level hierarchy: `:unverified`, `:automated`, `:reviewed`, `:verified` -* Directive blocks with key-value attributes -* Attestation provenance chain -* Zero dependencies beyond Elixir standard library - -== Quick Start - -Add to your `mix.exs`: - -[source,elixir] ----- -defp deps do - [{:a2ml_ex, git: "https://github.com/hyperpolymath/a2ml_ex.git"}] -end ----- - -Then run: - -[source,bash] ----- -mix deps.get -mix compile ----- - -== Usage - -[source,elixir] ----- -# Parse A2ML document -{:ok, document} = A2ML.parse("# Hello World\n\nSome **bold** text.") - -# Render back to A2ML -{:ok, rendered} = A2ML.render(document) - -# Handle parse errors -{:error, %A2ML.ParseError{}} = A2ML.parse("invalid syntax") ----- - -== Module Structure - -[cols="1,3"] -|=== -| Module | Purpose - -| `A2ML` -| Main module - re-exports public API - -| `A2ML.Document` -| Document struct and functions - -| `A2ML.Block` -| Block-level elements (headings, paragraphs, lists, etc.) - -| `A2ML.Inline` -| Inline elements (bold, italic, code, links, etc.) - -| `A2ML.Directive` -| Directive blocks with attributes - -| `A2ML.Attestation` -| Attestation provenance and trust levels - -| `A2ML.Parser` -| Parser implementation (string to AST) - -| `A2ML.Renderer` -| Renderer implementation (AST to string) - -| `A2ML.Error` -| Error types and handling -|=== - -== A2ML Syntax Reference - -[source] ----- -# Heading - -Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). - -@directive-name(key=val): single line value - -@multi-line: -Content spanning -multiple lines -@end - -!attest -identity: Jonathan D.A. Jewell -role: author -trust-level: verified -timestamp: 2026-03-16T00:00:00Z -!end - -- Bullet list item -- Another item - -> Block quote text - -```elixir -defmodule Example do - def hello, do: "world" -end -``` ----- - -== Development - -[source,bash] ----- -mix deps.get # Install dependencies -mix compile # Compile project -mix test # Run tests -mix format # Format code -mix creds check # Check credentials ----- - -== Configuration - -Add to `config/config.exs`: - -[source,elixir] ----- -config :a2ml_ex, - default_trust_level: :reviewed, - strict_mode: true ----- - -== Related Libraries - -* link:https://github.com/hyperpolymath/a2ml-deno[a2ml-deno] — Deno/ReScript implementation -* link:https://github.com/hyperpolymath/a2ml-rs[a2ml-rs] — Rust implementation -* link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation -* link:https://github.com/hyperpolymath/a2ml_gleam[a2ml_gleam] — Gleam implementation -* link:https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] — Tree-sitter grammar -* link:https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] — VS Code extension - -== Trust Levels - -A2ML supports four trust levels in a hierarchy: - -[cols="1,3"] -|=== -| Level | Meaning - -| `:unverified` -| Content has not been reviewed or attested - -| `:automated` -| Content generated or verified by automated systems - -| `:reviewed` -| Content reviewed by human but not formally verified - -| `:verified` -| Content formally verified with cryptographic attestation -|=== - -== Directives - -Directives provide metadata and processing instructions: - -[source] ----- -@page-break - -@toc(depth=3): Table of Contents - -@include(file="chapter1.a2ml"): - -@template(name="article"): -# {title} -By {author} - -{content} -@end ----- - -== Attestations - -Attestations provide cryptographic provenance: - -[source] ----- -!attest -identity: Alice Smith -role: Editor -trust-level: verified -timestamp: 2026-03-16T12:00:00Z -signature: 0xabc123... -!end ----- - -== Performance - -The Elixir implementation is optimized for: - -* Fast parsing of large documents -* Memory-efficient AST representation -* Concurrent rendering capabilities -* Stream processing support - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -See link:LICENSE[LICENSE] for full license text. - -== Contributing - -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for contribution guidelines. - -== Roadmap - -See link:ROADMAP.adoc[ROADMAP.adoc] for planned features and enhancements. \ No newline at end of file diff --git a/README.md b/README.md index d184690..1731866 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,58 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + + +[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/a2ml_ex) + +# Overview + +**Elixir implementation of A2ML (Attested Markup Language) parser and +renderer.** -= a2ml_ex -:toc: preamble -:icons: font +A2ML is a structured markup language with built-in attestation +provenance, directive metadata, and trust-level tracking. This library +provides a complete parser and renderer for A2ML documents in pure +Elixir. -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices, link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/a2ml_ex"] +# Features -== Overview +- Parse A2ML documents from strings or files -**Elixir implementation of A2ML (Attested Markup Language) parser and renderer.** +- Render AST back to A2ML surface syntax (round-trip support) -A2ML is a structured markup language with built-in attestation provenance, directive metadata, and trust-level tracking. This library provides a complete parser and renderer for A2ML documents in pure Elixir. +- Typed AST with structs for blocks, inlines, directives, and + attestations -== Features +- Trust-level hierarchy: `:unverified`, `:automated`, `:reviewed`, + `:verified` -* Parse A2ML documents from strings or files -* Render AST back to A2ML surface syntax (round-trip support) -* Typed AST with structs for blocks, inlines, directives, and attestations -* Trust-level hierarchy: `:unverified`, `:automated`, `:reviewed`, `:verified` -* Directive blocks with key-value attributes -* Attestation provenance chain -* Zero dependencies beyond Elixir standard library +- Directive blocks with key-value attributes -== Quick Start +- Attestation provenance chain + +- Zero dependencies beyond Elixir standard library + +# Quick Start Add to your `mix.exs`: -[source,elixir] ----- +```elixir defp deps do [{:a2ml_ex, git: "https://github.com/hyperpolymath/a2ml_ex.git"}] end ----- +``` Then run: -[source,bash] ----- +```bash mix deps.get mix compile ----- +``` -== Usage +# Usage -[source,elixir] ----- +```elixir # Parse A2ML document {:ok, document} = A2ML.parse("# Hello World\n\nSome **bold** text.") @@ -53,184 +61,159 @@ mix compile # Handle parse errors {:error, %A2ML.ParseError{}} = A2ML.parse("invalid syntax") ----- - -== Module Structure - -[cols="1,3"] -|=== -| Module | Purpose - -| `A2ML` -| Main module - re-exports public API - -| `A2ML.Document` -| Document struct and functions - -| `A2ML.Block` -| Block-level elements (headings, paragraphs, lists, etc.) - -| `A2ML.Inline` -| Inline elements (bold, italic, code, links, etc.) - -| `A2ML.Directive` -| Directive blocks with attributes - -| `A2ML.Attestation` -| Attestation provenance and trust levels - -| `A2ML.Parser` -| Parser implementation (string to AST) +``` -| `A2ML.Renderer` -| Renderer implementation (AST to string) +# Module Structure -| `A2ML.Error` -| Error types and handling -|=== +| Module | Purpose | +|----|----| +| `A2ML` | Main module - re-exports public API | +| `A2ML.Document` | Document struct and functions | +| `A2ML.Block` | Block-level elements (headings, paragraphs, lists, etc.) | +| `A2ML.Inline` | Inline elements (bold, italic, code, links, etc.) | +| `A2ML.Directive` | Directive blocks with attributes | +| `A2ML.Attestation` | Attestation provenance and trust levels | +| `A2ML.Parser` | Parser implementation (string to AST) | +| `A2ML.Renderer` | Renderer implementation (AST to string) | +| `A2ML.Error` | Error types and handling | -== A2ML Syntax Reference +# A2ML Syntax Reference -[source] ----- -# Heading + # Heading -Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). + Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). -@directive-name(key=val): single line value + @directive-name(key=val): single line value -@multi-line: -Content spanning -multiple lines -@end + @multi-line: + Content spanning + multiple lines + @end -!attest -identity: Jonathan D.A. Jewell -role: author -trust-level: verified -timestamp: 2026-03-16T00:00:00Z -!end + !attest + identity: Jonathan D.A. Jewell + role: author + trust-level: verified + timestamp: 2026-03-16T00:00:00Z + !end -- Bullet list item -- Another item + - Bullet list item + - Another item -> Block quote text + > Block quote text -```elixir -defmodule Example do - def hello, do: "world" -end -``` ----- + ```elixir + defmodule Example do + def hello, do: "world" + end + ``` -== Development +# Development -[source,bash] ----- +```bash mix deps.get # Install dependencies mix compile # Compile project mix test # Run tests mix format # Format code mix creds check # Check credentials ----- +``` -== Configuration +# Configuration Add to `config/config.exs`: -[source,elixir] ----- +```elixir config :a2ml_ex, default_trust_level: :reviewed, strict_mode: true ----- +``` -== Related Libraries +# Related Libraries -* link:https://github.com/hyperpolymath/a2ml-deno[a2ml-deno] — Deno/ReScript implementation -* link:https://github.com/hyperpolymath/a2ml-rs[a2ml-rs] — Rust implementation -* link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation -* link:https://github.com/hyperpolymath/a2ml_gleam[a2ml_gleam] — Gleam implementation -* link:https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] — Tree-sitter grammar -* link:https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] — VS Code extension +- [a2ml-deno](https://github.com/hyperpolymath/a2ml-deno) — + Deno/ReScript implementation -== Trust Levels +- [a2ml-rs](https://github.com/hyperpolymath/a2ml-rs) — Rust + implementation -A2ML supports four trust levels in a hierarchy: +- [a2ml-haskell](https://github.com/hyperpolymath/a2ml-haskell) — + Haskell implementation + +- [a2ml_gleam](https://github.com/hyperpolymath/a2ml_gleam) — Gleam + implementation -[cols="1,3"] -|=== -| Level | Meaning +- [tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) + — Tree-sitter grammar -| `:unverified` -| Content has not been reviewed or attested +- [vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) — VS Code + extension -| `:automated` -| Content generated or verified by automated systems +# Trust Levels -| `:reviewed` -| Content reviewed by human but not formally verified +A2ML supports four trust levels in a hierarchy: -| `:verified` -| Content formally verified with cryptographic attestation -|=== +| Level | Meaning | +|---------------|----------------------------------------------------------| +| `:unverified` | Content has not been reviewed or attested | +| `:automated` | Content generated or verified by automated systems | +| `:reviewed` | Content reviewed by human but not formally verified | +| `:verified` | Content formally verified with cryptographic attestation | -== Directives +# Directives Directives provide metadata and processing instructions: -[source] ----- -@page-break + @page-break -@toc(depth=3): Table of Contents + @toc(depth=3): Table of Contents -@include(file="chapter1.a2ml"): + @include(file="chapter1.a2ml"): -@template(name="article"): -# {title} -By {author} + @template(name="article"): + # {title} + By {author} -{content} -@end ----- + {content} + @end -== Attestations +# Attestations Attestations provide cryptographic provenance: -[source] ----- -!attest -identity: Alice Smith -role: Editor -trust-level: verified -timestamp: 2026-03-16T12:00:00Z -signature: 0xabc123... -!end ----- + !attest + identity: Alice Smith + role: Editor + trust-level: verified + timestamp: 2026-03-16T12:00:00Z + signature: 0xabc123... + !end -== Performance +# Performance The Elixir implementation is optimized for: -* Fast parsing of large documents -* Memory-efficient AST representation -* Concurrent rendering capabilities -* Stream processing support +- Fast parsing of large documents + +- Memory-efficient AST representation + +- Concurrent rendering capabilities + +- Stream processing support -== License +# License SPDX-License-Identifier: CC-BY-SA-4.0 Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -See link:LICENSE[LICENSE] for full license text. +See [LICENSE](LICENSE) for full license text. -== Contributing +# Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for contribution guidelines. +See CONTRIBUTING for +contribution guidelines. -== Roadmap +# Roadmap -See link:ROADMAP.adoc[ROADMAP.adoc] for planned features and enhancements. \ No newline at end of file +See ROADMAP for planned features +and enhancements.