# elkarouh/adascript architecture

> Architecture diagram of the GitHub repository elkarouh/adascript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elkarouh/adascript
- Repository: https://github.com/elkarouh/adascript

## Overview

1. **Overall shape**
   - This repo is a **source-to-source language toolchain** for Adascript.
   - The primary flow is: **`.ady` source → parse/AST → emit Python 3 or Nim**.
   - The two main compilation targets are split cleanly into separate backends under `TO_PYTHON/` and `TO_NIM/`.

2. **Frontend boundary: tokenization and parsing**
   - The shared frontend is centered on `hek_tokenize.py`, `hek_parsec.py`, and `hek_helpers.py`.
   - `hek_tokenize` is not just lexical analysis; it also performs Adascript-specific preprocessing such as **tick-attribute rewriting** and preserving comment/newline structure.
   - `hek_parsec` provides the parser-combinator engine used to define the language grammar and build the AST.

3. **Language definition layer**
   - `ADASCRIPT_GRAMMAR/` contains the grammar split by language area:
     - expressions
     - simple statements
     - compound statements
     - declarations / type syntax
   - This is the authoritative boundary for Adascript syntax, independent of any output target.

4. **AST-to-target translation is backend-specific**
   - The backend modules attach `to_py()` and `to_nim()` methods to grammar nodes.
   - Python emission lives in `TO_PYTHON/hek_py3_*.py`.
   - Nim emission lives in `TO_NIM/hek_nim_*.py`.
   - This means the repo is organized around a **single parsed representation** with **two code generators**, not around two separate parsers.

5. **Entry points and compilation flow**
   - `TO_PYTHON/py2py.py` is the Python backend CLI.
   - `TO_NIM/py2nim.py` is the Nim backend CLI.
   - Both parse the input file and walk the AST, but they diverge after parsing in their target-specific lowering rules.
   - `py2nim` also has a more involved build pipeline because it can compile, run, cache artifacts, and create source-directory symlinks.

6. **Nim build/runtime boundary**
   - The Nim path is more than transpilation: it includes a **compile-and-run pipeline**.
   - Generated `.nim`, compiled binaries, and nimcache artifacts are stored in a **cache directory under `~/.cache/hparsec/`**, keyed by source path.
   - The backend also inserts a local Nim shim, `TO_NIM/stdlib.nim`, to cover Python-like runtime conveniences that Nim does not provide directly.

7. **Python interoperability and runtime adaptation**
   - The language supports ordinary Python imports, but the backend decides whether they map natively to Nim modules or need **nimpy**.
   - This makes the compiler responsible for **runtime boundary translation**, not just syntax conversion.
   - Shell integration, regex literals, and Python-object coercions are also handled as compile-time rewrites into backend-specific runtime calls.

8. **Adascript features that affect architecture**
   - Several syntax features are first-class in the compiler and require dedicated lowering logic:
     - enum and subrange types
     - variant records / discriminated records
     - `case/when` pattern matching
     - regex literals and substitution
     - shell blocks
     - bash-style variables and file tests
     - tick attributes like `T'First` / `T'Last`
   - These are not library add-ons; they are baked into the parse and emit pipeline.

9. **Example programs as integration tests**
   - `EXAMPLES/` is a major architectural asset, not just documentation.
   - It contains real Adascript programs spanning algorithms, shell processing, timetabling, regex usage, and object-oriented examples.
   - Many examples exist in multiple forms (`.ady`, generated `.nim`, sometimes `.py`) and serve as end-to-end validation of both backends.

10. **Bundled language/runtime libraries**
   - `TO_NIM/STDLIB/` and `TO_NIM/awk.ady` provide bundled support code for the Nim target.
   - These are treated like installable language libraries and can be imported through `nimport`.
   - This creates a boundary between **core compiler output** and **target-side support modules**.

11. **Editor/tooling ecosystem**
   - The repo also ships language tooling for editor integration:
     - `LSP/adascript_ls.py` for language-server behavior
     - Emacs, Sublime, and VS Code support packages
     - indentation helpers in `ADA_INDENT/`
   - These are ancillary to compilation, but they reinforce the fact that Adascript is a real language ecosystem, not just a transpiler script.

12. **Documentation and spec surface**
   - The README, `TUTORIAL.md`, `TUTORIAL_FOR_LLM.md`, `OPTIONAL_TYPES.md`, and `PATTERN_MATCHING.md` collectively describe the language contract.
   - From an architecture-diagram perspective, these documents sit outside the runtime flow but define the intended semantics that the parser and backends implement.

13. **Operational constraints**
   - The parser state is effectively global, so parsing is **not thread-safe** across concurrent runs.
   - Incremental rebuild logic in `py2nim` means the compiler is stateful across invocations through its cache, which matters if you are diagramming execution and artifact flow.

14. **Mental model for a diagram**
   - A useful diagram would show:
     - Adascript source files at the left
     - shared tokenizer/parser/grammar in the center
     - two target emitters on the right
     - Nim-specific compile/cache/runtime support as a separate branch
     - examples, tests, and editor tooling as surrounding ecosystem components
   - The key architectural idea is **one language frontend, two target-specific lowering pipelines, plus target runtime shims and tooling**.

Main entry points: [`TO_NIM/py2nim.py`](https://github.com/elkarouh/adascript/blob/master/TO_NIM/py2nim.py) (py2nim), [`TO_PYTHON/py2py.py`](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/py2py.py) (py2py), [`HPARSEC`](https://github.com/elkarouh/adascript/tree/master/HPARSEC) (Parser core), [`README.md`](https://github.com/elkarouh/adascript/blob/master/README.md) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Frontend"]
  node_n_source["Ady source<br/>inputs"]
  node_n_tokenize["Tokenizer<br/>preprocess+lex<br/>[hek_py3_parser.py]"]
  node_n_parsec["Parser core<br/>parser-combinators"]
  node_n_grammar["Grammar<br/>syntax rules"]
  node_n_ast(("AST<br/>intermediate tree"))
end

subgraph group_g_backends["Backends"]
  node_n_py_cli["py2py<br/>Python CLI<br/>[py2py.py]"]
  node_n_py_emit_expr["Py expr<br/>python emitter<br/>[hek_py3_expr.py]"]
  node_n_py_emit_stmt["Py stmt<br/>python emitter<br/>[hek_py3_stmt.py]"]
  node_n_py_emit_decl["Py decls<br/>python emitter"]
  node_n_nim_cli["py2nim<br/>Nim CLI<br/>[py2nim.py]"]
  node_n_nim_emit_expr["Nim expr<br/>nim emitter<br/>[hek_nim_expr.py]"]
  node_n_nim_emit_stmt["Nim stmt<br/>nim emitter<br/>[hek_nim_stmt.py]"]
  node_n_nim_emit_decl["Nim decls<br/>nim emitter"]
end

subgraph group_g_nim["Nim support"]
  node_n_nim_stdlib["Nim shim<br/>runtime support<br/>[stdlib.nim]"]
  node_n_nim_bundled["Bundled libs<br/>nimport libs"]
end

subgraph group_g_ecosystem["Ecosystem"]
  node_n_examples["Examples<br/>integration corpus"]
  node_n_lsp["LSP<br/>editor tooling"]
  node_n_indent["Indent tools<br/>editor helpers"]
  node_n_docs["Docs<br/>specification<br/>[README.md]"]
end

node_n_source -->|"lexes"| node_n_tokenize
node_n_tokenize -->|"feeds"| node_n_parsec
node_n_parsec -->|"uses"| node_n_grammar
node_n_parsec -->|"builds"| node_n_ast
node_n_ast -->|"routes"| node_n_py_cli
node_n_ast -->|"routes"| node_n_nim_cli
node_n_py_cli -->|"lowers"| node_n_py_emit_expr
node_n_py_cli -->|"lowers"| node_n_py_emit_stmt
node_n_py_cli -->|"lowers"| node_n_py_emit_decl
node_n_nim_cli -->|"lowers"| node_n_nim_emit_expr
node_n_nim_cli -->|"lowers"| node_n_nim_emit_stmt
node_n_nim_cli -->|"lowers"| node_n_nim_emit_decl
node_n_nim_cli -->|"shims"| node_n_nim_stdlib
node_n_nim_cli -->|"imports"| node_n_nim_bundled
node_n_examples -.->|"exercises"| node_n_source
node_n_lsp -.->|"supports"| node_n_docs
node_n_indent -.->|"supports"| node_n_docs
node_n_docs -.->|"specifies"| node_n_grammar
node_n_examples -.->|"validates"| node_n_nim_cli

click node_n_tokenize "https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_parser.py"
click node_n_parsec "https://github.com/elkarouh/adascript/tree/master/HPARSEC"
click node_n_grammar "https://github.com/elkarouh/adascript/tree/master/ADASCRIPT_GRAMMAR"
click node_n_py_cli "https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/py2py.py"
click node_n_py_emit_expr "https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_expr.py"
click node_n_py_emit_stmt "https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_stmt.py"
click node_n_py_emit_decl "https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py_declarations.py"
click node_n_nim_cli "https://github.com/elkarouh/adascript/blob/master/TO_NIM/py2nim.py"
click node_n_nim_emit_expr "https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_expr.py"
click node_n_nim_emit_stmt "https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_stmt.py"
click node_n_nim_emit_decl "https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_declarations.py"
click node_n_nim_stdlib "https://github.com/elkarouh/adascript/blob/master/TO_NIM/STDLIB/stdlib.nim"
click node_n_nim_bundled "https://github.com/elkarouh/adascript/tree/master/TO_NIM/STDLIB"
click node_n_examples "https://github.com/elkarouh/adascript/tree/master/EXAMPLES"
click node_n_lsp "https://github.com/elkarouh/adascript/tree/master/LSP"
click node_n_indent "https://github.com/elkarouh/adascript/tree/master/ADA_INDENT"
click node_n_docs "https://github.com/elkarouh/adascript/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_source,node_n_tokenize,node_n_parsec,node_n_grammar,node_n_ast toneBlue
class node_n_py_cli,node_n_py_emit_expr,node_n_py_emit_stmt,node_n_py_emit_decl,node_n_nim_cli,node_n_nim_emit_expr,node_n_nim_emit_stmt,node_n_nim_emit_decl toneAmber
class node_n_nim_stdlib,node_n_nim_bundled toneMint
class node_n_examples,node_n_lsp,node_n_indent,node_n_docs toneRose
```

## Components

### Frontend

Shared tokenization, parsing, and grammar definition for Adascript.

- **Ady source**: inputs · Adascript source files that enter the compiler pipeline.
- [Tokenizer](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_parser.py): preprocess+lex · Shared lexer and Adascript-specific preprocessing such as tick-attribute rewriting and comment/newline preservation. · `TO_PYTHON/hek_py3_parser.py`
- [Parser core](https://github.com/elkarouh/adascript/tree/master/HPARSEC): parser-combinators · Grammar engine and parser-combinator machinery used to build the AST. · `HPARSEC`
- [Grammar](https://github.com/elkarouh/adascript/tree/master/ADASCRIPT_GRAMMAR): syntax rules · Authoritative Adascript syntax split across expressions, statements, compound statements, and declarations. · `ADASCRIPT_GRAMMAR`
- **AST**: intermediate tree · Single parsed representation shared by both code generators.

### Backends

Target-specific emitters and entry points for Python and Nim.

- [py2py](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/py2py.py): Python CLI · Python backend entry point that parses input and emits Python 3. · `TO_PYTHON/py2py.py`
- [Py expr](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_expr.py): python emitter · Expression lowering for Python output. · `TO_PYTHON/hek_py3_expr.py`
- [Py stmt](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py3_stmt.py): python emitter · Statement lowering for Python output. · `TO_PYTHON/hek_py3_stmt.py`
- [Py decls](https://github.com/elkarouh/adascript/blob/master/TO_PYTHON/hek_py_declarations.py): python emitter · Declaration and type lowering for Python output. · `TO_PYTHON/hek_py_declarations.py`
- [py2nim](https://github.com/elkarouh/adascript/blob/master/TO_NIM/py2nim.py): Nim CLI · Nim backend entry point with compile, run, cache, and artifact management. · `TO_NIM/py2nim.py`
- [Nim expr](https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_expr.py): nim emitter · Expression lowering for Nim output. · `TO_NIM/hek_nim_expr.py`
- [Nim stmt](https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_stmt.py): nim emitter · Statement lowering for Nim output. · `TO_NIM/hek_nim_stmt.py`
- [Nim decls](https://github.com/elkarouh/adascript/blob/master/TO_NIM/hek_nim_declarations.py): nim emitter · Declaration and type lowering for Nim output. · `TO_NIM/hek_nim_declarations.py`

### Nim support

Compile, cache, and runtime support used by the Nim pipeline.

- [Nim shim](https://github.com/elkarouh/adascript/blob/master/TO_NIM/STDLIB/stdlib.nim): runtime support · Local Nim runtime shim for Python-like conveniences missing from Nim. · `TO_NIM/STDLIB/stdlib.nim`
- [Bundled libs](https://github.com/elkarouh/adascript/tree/master/TO_NIM/STDLIB): nimport libs · Bundled target-side support modules and importable libraries for Nim output. · `TO_NIM/STDLIB`

### Ecosystem

Examples, editor tooling, and documentation around the compiler.

- [Examples](https://github.com/elkarouh/adascript/tree/master/EXAMPLES): integration corpus · Real Adascript programs and generated artifacts used as end-to-end validation. · `EXAMPLES`
- [LSP](https://github.com/elkarouh/adascript/tree/master/LSP): editor tooling · Language-server and editor integrations for Adascript. · `LSP`
- [Indent tools](https://github.com/elkarouh/adascript/tree/master/ADA_INDENT): editor helpers · Indentation and syntax-support helpers for editor integration. · `ADA_INDENT`
- [Docs](https://github.com/elkarouh/adascript/blob/master/README.md): specification · Tutorials, language notes, and feature documentation that define the language contract. · `README.md`

## Connections

- Ady source → Tokenizer: lexes · Source files are preprocessed and tokenized before parsing.
- Tokenizer → Parser core: feeds · Token stream enters the parser-combinator engine.
- Parser core → Grammar: uses · Grammar rules define the language accepted by the parser.
- Parser core → AST: builds · Parser constructs the shared AST representation.
- AST → py2py: routes · Parsed programs can be lowered through the Python backend.
- AST → py2nim: routes · Parsed programs can be lowered through the Nim backend.
- py2py → Py expr: lowers · Python CLI delegates expression emission to target-specific modules.
- py2py → Py stmt: lowers · Python CLI delegates statement emission to target-specific modules.
- py2py → Py decls: lowers · Python CLI delegates declarations and type lowering to target-specific modules.
- py2nim → Nim expr: lowers · Nim CLI delegates expression emission to target-specific modules.
- py2nim → Nim stmt: lowers · Nim CLI delegates statement emission to target-specific modules.
- py2nim → Nim decls: lowers · Nim CLI delegates declarations and type lowering to target-specific modules.
- py2nim → Nim shim: shims · Generated Nim code relies on bundled runtime shims for Python-like behavior.
- py2nim → Bundled libs: imports · Nim pipeline can import bundled support libraries through nimport.
- Examples → Ady source: exercises · Examples provide end-to-end input programs for the compiler.
- LSP → Docs: supports · Editor tooling follows the documented language contract.
- Indent tools → Docs: supports · Indentation helpers align with the documented syntax and formatting rules.
- Docs → Grammar: specifies · Documentation describes the intended syntax and semantics implemented by the grammar.
- Examples → py2nim: validates · Some examples are compiled through the Nim pipeline and cached artifacts.