# ashqqy/formal architecture

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

- Interactive diagram: https://gitdiagram.com/ashqqy/formal
- Repository: https://github.com/ashqqy/formal

## Overview

formal is a C++23 regular-expression parsing and presentation library. Its main workflow takes a pattern through lexing and recursive-descent parsing into an expression tree, then exposes canonical text and Graphviz DOT output. The README also documents an example CLI that prints these representations. The graph focuses on runtime library behavior; automata files exist, but no documented or excerpted workflow connects them to the public regex API. Edges are limited to calls or references visible in excerpts, the source index, or README.

Main entry points: [`src/regex/lexer.hpp`](https://github.com/ashqqy/formal/blob/main/src/regex/lexer.hpp) (Lexer), [`src/regex.hpp`](https://github.com/ashqqy/formal/blob/main/src/regex.hpp) (Regex API), [`src/regex/parser.hpp`](https://github.com/ashqqy/formal/blob/main/src/regex/parser.hpp) (Parser), [`src/regex/node.hpp`](https://github.com/ashqqy/formal/blob/main/src/regex/node.hpp) (Regex tree nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_regex_api["Regex API<br/>[regex.hpp]"]
end

subgraph group_syntax["Regex Syntax"]
  node_lexer["Lexer<br/>[lexer.hpp]"]
  node_parser["Parser<br/>[parser.hpp]"]
  node_errors["Syntax errors<br/>[error.hpp]"]
  node_tokens["Tokens<br/>[token.hpp]"]
  node_positions["Source positions<br/>[position.hpp]"]
end

subgraph group_tree["Expression Tree"]
  node_tree_nodes["Regex tree nodes<br/>[node.hpp]"]
  node_visitor["Tree visitor<br/>[visitor.hpp]"]
  node_nfa["NFA state model<br/>[nfa.hpp]"]
  node_state["Automaton state<br/>[state.hpp]"]
end

subgraph group_presentation["Output Formatting"]
  node_text_printer["Canonical printer<br/>[printer.hpp]"]
  node_dot_printer["DOT printer<br/>[dot.hpp]"]
  node_dot_helpers["DOT helpers<br/>[dot.hpp]"]
end

subgraph group_utilities["Symbol Utilities"]
  node_alphabet["Allowed alphabet<br/>[alphabet.hpp]"]
  node_ascii["ASCII utilities<br/>[ascii.hpp]"]
  node_symbols["Symbol type<br/>[symbol.hpp]"]
  node_symbol_print["Symbol escaping<br/>[symbol_print.hpp]"]
end

node_user(("Library user"))
node_example["formal_print CLI<br/>[print.cpp]"]

node_user -->|"constructs regex"| node_regex_api
node_regex_api -->|"parses pattern"| node_parser
node_parser -->|"requests tokens"| node_lexer
node_parser -->|"builds tree"| node_tree_nodes
node_lexer -->|"emits tokens"| node_tokens
node_lexer -->|"throws errors"| node_errors
node_parser -->|"throws errors"| node_errors
node_lexer -->|"checks symbols"| node_alphabet
node_lexer -->|"tracks offsets"| node_positions
node_tokens -->|"stores position"| node_positions
node_regex_api -->|"formats text"| node_text_printer
node_regex_api -->|"formats DOT"| node_dot_printer
node_text_printer -->|"visits tree"| node_tree_nodes
node_dot_printer -->|"visits tree"| node_tree_nodes
node_dot_printer -->|"uses helpers"| node_dot_helpers
node_tree_nodes -->|"dispatches visits"| node_visitor
node_lexer -->|"skips whitespace"| node_ascii
node_lexer -->|"escapes errors"| node_symbol_print
node_symbol_print -->|"checks printability"| node_ascii
node_alphabet -->|"stores symbols"| node_symbols
node_example -->|"prints representations"| node_regex_api
node_nfa -->|"uses states"| node_state

click node_regex_api "https://github.com/ashqqy/formal/blob/main/src/regex.hpp"
click node_lexer "https://github.com/ashqqy/formal/blob/main/src/regex/lexer.hpp"
click node_parser "https://github.com/ashqqy/formal/blob/main/src/regex/parser.hpp"
click node_errors "https://github.com/ashqqy/formal/blob/main/src/regex/error.hpp"
click node_tokens "https://github.com/ashqqy/formal/blob/main/src/regex/token.hpp"
click node_positions "https://github.com/ashqqy/formal/blob/main/src/regex/position.hpp"
click node_tree_nodes "https://github.com/ashqqy/formal/blob/main/src/regex/node.hpp"
click node_visitor "https://github.com/ashqqy/formal/blob/main/src/regex/visitor.hpp"
click node_text_printer "https://github.com/ashqqy/formal/blob/main/src/regex/printer.hpp"
click node_dot_printer "https://github.com/ashqqy/formal/blob/main/src/regex/dot.hpp"
click node_dot_helpers "https://github.com/ashqqy/formal/blob/main/src/util/dot.hpp"
click node_alphabet "https://github.com/ashqqy/formal/blob/main/src/util/alphabet.hpp"
click node_ascii "https://github.com/ashqqy/formal/blob/main/src/util/ascii.hpp"
click node_symbols "https://github.com/ashqqy/formal/blob/main/src/util/symbol.hpp"
click node_symbol_print "https://github.com/ashqqy/formal/blob/main/src/util/symbol_print.hpp"
click node_nfa "https://github.com/ashqqy/formal/blob/main/src/automata/nfa.hpp"
click node_state "https://github.com/ashqqy/formal/blob/main/src/automata/state.hpp"
click node_example "https://github.com/ashqqy/formal/blob/main/examples/print.cpp"

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_regex_api,node_user toneBlue
class node_lexer,node_parser,node_errors,node_tokens,node_positions toneAmber
class node_tree_nodes,node_visitor,node_nfa,node_state toneMint
class node_text_printer,node_dot_printer,node_dot_helpers toneRose
class node_alphabet,node_ascii,node_symbols,node_symbol_print toneIndigo
class node_example toneTeal
```

## Components

### Public API

- [Regex API](https://github.com/ashqqy/formal/blob/main/src/regex.hpp): `src/regex.hpp`

### Regex Syntax

- [Lexer](https://github.com/ashqqy/formal/blob/main/src/regex/lexer.hpp): `src/regex/lexer.hpp`
- [Parser](https://github.com/ashqqy/formal/blob/main/src/regex/parser.hpp): `src/regex/parser.hpp`
- [Syntax errors](https://github.com/ashqqy/formal/blob/main/src/regex/error.hpp): `src/regex/error.hpp`
- [Tokens](https://github.com/ashqqy/formal/blob/main/src/regex/token.hpp): `src/regex/token.hpp`
- [Source positions](https://github.com/ashqqy/formal/blob/main/src/regex/position.hpp): `src/regex/position.hpp`

### Expression Tree

- [Regex tree nodes](https://github.com/ashqqy/formal/blob/main/src/regex/node.hpp): `src/regex/node.hpp`
- [Tree visitor](https://github.com/ashqqy/formal/blob/main/src/regex/visitor.hpp): `src/regex/visitor.hpp`
- [NFA state model](https://github.com/ashqqy/formal/blob/main/src/automata/nfa.hpp): `src/automata/nfa.hpp`
- [Automaton state](https://github.com/ashqqy/formal/blob/main/src/automata/state.hpp): `src/automata/state.hpp`

### Output Formatting

- [Canonical printer](https://github.com/ashqqy/formal/blob/main/src/regex/printer.hpp): `src/regex/printer.hpp`
- [DOT printer](https://github.com/ashqqy/formal/blob/main/src/regex/dot.hpp): `src/regex/dot.hpp`
- [DOT helpers](https://github.com/ashqqy/formal/blob/main/src/util/dot.hpp): `src/util/dot.hpp`

### Symbol Utilities

- [Allowed alphabet](https://github.com/ashqqy/formal/blob/main/src/util/alphabet.hpp): `src/util/alphabet.hpp`
- [ASCII utilities](https://github.com/ashqqy/formal/blob/main/src/util/ascii.hpp): `src/util/ascii.hpp`
- [Symbol type](https://github.com/ashqqy/formal/blob/main/src/util/symbol.hpp): `src/util/symbol.hpp`
- [Symbol escaping](https://github.com/ashqqy/formal/blob/main/src/util/symbol_print.hpp): `src/util/symbol_print.hpp`

### Other components

- **Library user**
- [formal_print CLI](https://github.com/ashqqy/formal/blob/main/examples/print.cpp): `examples/print.cpp`

## Connections

- Library user → Regex API: constructs regex (evidence: `README.md`)
- Regex API → Parser: parses pattern (evidence: `src/regex.hpp`)
- Parser → Lexer: requests tokens (evidence: `src/regex/parser.hpp`)
- Parser → Regex tree nodes: builds tree (evidence: `src/regex/parser.hpp`)
- Lexer → Tokens: emits tokens (evidence: `src/regex/lexer.hpp`)
- Lexer → Syntax errors: throws errors (evidence: `src/regex/lexer.hpp`)
- Parser → Syntax errors: throws errors (evidence: `src/regex/parser.hpp`)
- Lexer → Allowed alphabet: checks symbols (evidence: `src/regex/lexer.hpp`)
- Lexer → Source positions: tracks offsets (evidence: `src/regex/lexer.hpp`)
- Tokens → Source positions: stores position (evidence: `src/regex/token.hpp`)
- Regex API → Canonical printer: formats text (evidence: `src/regex.hpp`)
- Regex API → DOT printer: formats DOT (evidence: `src/regex.hpp`)
- Canonical printer → Regex tree nodes: visits tree (evidence: `src/regex/printer.hpp`)
- DOT printer → Regex tree nodes: visits tree (evidence: `src/regex/dot.hpp`)
- DOT printer → DOT helpers: uses helpers (evidence: `src/regex/dot.hpp`)
- Regex tree nodes → Tree visitor: dispatches visits (evidence: `src/regex/node.hpp`)
- Lexer → ASCII utilities: skips whitespace (evidence: `src/regex/lexer.hpp`)
- Lexer → Symbol escaping: escapes errors (evidence: `src/regex/lexer.hpp`)
- Symbol escaping → ASCII utilities: checks printability (evidence: `src/util/symbol_print.hpp`)
- Allowed alphabet → Symbol type: stores symbols (evidence: `src/util/alphabet.hpp`)
- formal_print CLI → Regex API: prints representations (evidence: `README.md`)
- NFA state model → Automaton state: uses states (evidence: `src/automata/nfa.hpp`)
