# ruby/lrama architecture

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

- Interactive diagram: https://gitdiagram.com/ruby/lrama
- Repository: https://github.com/ruby/lrama

## Overview

Lrama is a Ruby-based LALR(1) parser generator, not an application runtime. Its main architecture is a compilation pipeline that reads a Bison-style grammar file and emits parser artifacts such as C source/header files and optional syntax diagrams.

1. **Entry points and orchestration**
   The executable entry point is `exe/lrama`, which dispatches into the library under `lib/lrama`. The top-level `Command`, `OptionParser`, `Options`, `Context`, and `Output` classes form the control layer: they parse CLI flags, load the grammar, run analysis, and decide which outputs to generate.

2. **Grammar-file ingestion**
   Input is a `.y` grammar file. The `lexer` subsystem tokenizes it, and `parser.rb`/`parser.y` parse it into Lrama’s internal representation. The repository keeps `parser.y` as the source and generates `parser.rb` from it, so the parsing front end is itself bootstrapped from a grammar specification.

3. **Core grammar model**
   The `grammar` subtree is the central domain model. It represents symbols, rules, precedence, types, unions, destructors, error tokens, and embedded code blocks. This is where raw grammar text becomes structured compiler data. The model also includes support for parameterized rules and inlining, which are important Lrama-specific extensions.

4. **Grammar rewriting and resolution**
   Several submodules rewrite the grammar before state construction:
   `grammar/symbols/resolver`, `grammar/parameterized/resolver`, and `grammar/inline/resolver` resolve symbol references, expand parameterized definitions, and inline rules. These transformations are crucial because they change the effective grammar before parser tables are built.

5. **State machine construction**
   The `state` and `states` layers build the LR automaton from the resolved grammar. They define items, shifts, reduces, gotos, and conflict objects such as shift/reduce and reduce/reduce conflicts. This is the core parser-generation engine that turns grammar structure into parse tables.

6. **Conflict handling and error tolerance**
   Conflict analysis is not just diagnostic; it feeds Lrama’s error-tolerant parser support. The `counterexamples` package helps explain ambiguities, and `state/*_conflict` plus `warnings/*` classify unresolved or suspicious grammar situations. This reflects Lrama’s focus on CRuby-compatible, error-tolerant parsing.

7. **Warnings and reporting**
   The `warnings` and `reporter` subsystems produce human-readable analysis of the grammar and states. Reports cover conflicts, precedence usage, rules, terminals, and profiling information. This is the layer that explains the generated automaton rather than generating code.

8. **Tracing and profiling**
   The `tracer` and `reporter/profile` modules capture generation behavior such as closure expansion, actions, state construction, duration, and memory. These are development-time observability tools that help diagnose expensive grammars or unexpected generation behavior.

9. **Output generation and templates**
   The `template/bison` directory contains Bison-compatible C/header templates, indicating that code generation is template-driven. Supporting modules like `erb`, `diagram`, and `digraph` are used to render text and HTML artifacts, including syntax diagrams. The `sample` directory demonstrates the generated outputs and expected usage patterns.

10. **Tooling, types, and validation**
    The project is packaged as a Ruby gem (`lrama.gemspec`) and uses RSpec for tests, Steep/RBS for type checking, and GitHub Actions for CI. The `sig/generated` tree mirrors the library structure with type signatures, and the `spec/fixtures` grammars provide targeted coverage for parsing, parameterization, inlining, state generation, and integration behavior.

11. **Repository boundaries**
    The main architectural boundary is between “grammar input and analysis” on one side and “generated artifacts” on the other. The source tree is heavily organized around compiler phases: lex/parse, normalize/resolve, build automaton, report/warn, then emit templates or diagrams. That makes it straightforward to diagram as a staged pipeline rather than a request/response service.

12. **Documentation and development examples**
    The `doc` and `sample` trees are not part of the generation pipeline, but they document and exercise it. They are useful references for understanding what kinds of grammar features the architecture must support, especially parameterized rules, inlining, and syntax-diagram generation.

Main entry points: [`lib/lrama/command.rb`](https://github.com/ruby/lrama/blob/master/lib/lrama/command.rb) (Command), [`lib/lrama/states.rb`](https://github.com/ruby/lrama/blob/master/lib/lrama/states.rb) (States), [`lib/lrama/grammar.rb`](https://github.com/ruby/lrama/blob/master/lib/lrama/grammar.rb) (Grammar), [`lib/lrama/output.rb`](https://github.com/ruby/lrama/blob/master/lib/lrama/output.rb) (Output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_exe_lrama["lrama<br/>entrypoint"]
  node_command["Command<br/>orchestrator<br/>[command.rb]"]
  node_option_parser["Option parser<br/>cli parser<br/>[option_parser.rb]"]
  node_options["Options<br/>config object<br/>[options.rb]"]
end

subgraph group_pipeline["Pipeline"]
  node_context["Context<br/>[context.rb]"]
  node_lexer["Lexer<br/>[lexer.rb]"]
  node_parser["Parser<br/>[parser.rb]"]
  node_states["States<br/>lr automaton<br/>[states.rb]"]
  node_state["State<br/>[state.rb]"]
end

subgraph group_model["Grammar model"]
  node_grammar["Grammar<br/>domain model<br/>[grammar.rb]"]
  node_symbols_resolver["Symbol resolver<br/>rewrite pass<br/>[resolver.rb]"]
  node_param_resolver["Param resolver<br/>rewrite pass<br/>[resolver.rb]"]
  node_inline_resolver["Inline resolver<br/>rewrite pass<br/>[resolver.rb]"]
end

subgraph group_reporting["Analysis"]
  node_warnings["Warnings<br/>diagnostics<br/>[warnings.rb]"]
  node_reporter["Reporter<br/>analysis report<br/>[reporter.rb]"]
  node_tracer["Tracer<br/>profiling trace<br/>[tracer.rb]"]
end

subgraph group_emit["Emission"]
  node_output["Output<br/>emitter<br/>[output.rb]"]
  node_templates["Bison templates<br/>template set"]
  node_diagram["Diagrams<br/>renderer<br/>[diagram.rb]"]
end

node_exe_lrama -->|"dispatches"| node_command
node_command -->|"parses"| node_option_parser
node_command -->|"builds"| node_options
node_command -->|"initializes"| node_context
node_context -->|"uses"| node_lexer
node_context -->|"uses"| node_parser
node_lexer -->|"feeds"| node_parser
node_parser -->|"constructs"| node_grammar
node_grammar -->|"normalizes"| node_symbols_resolver
node_grammar -->|"expands"| node_param_resolver
node_grammar -->|"inlines"| node_inline_resolver
node_symbols_resolver -->|"prepares"| node_states
node_param_resolver -->|"prepares"| node_states
node_inline_resolver -->|"prepares"| node_states
node_states -->|"builds"| node_state
node_state -->|"surfaces"| node_warnings
node_state -->|"summarizes"| node_reporter
node_warnings -->|"reports"| node_reporter
node_states -->|"traces"| node_tracer
node_command -->|"emits"| node_output
node_output -->|"renders"| node_templates
node_output -->|"optionally renders"| node_diagram
node_reporter -->|"informs"| node_output

click node_exe_lrama "https://github.com/ruby/lrama/tree/master/exe/lrama"
click node_command "https://github.com/ruby/lrama/blob/master/lib/lrama/command.rb"
click node_option_parser "https://github.com/ruby/lrama/blob/master/lib/lrama/option_parser.rb"
click node_options "https://github.com/ruby/lrama/blob/master/lib/lrama/options.rb"
click node_context "https://github.com/ruby/lrama/blob/master/lib/lrama/context.rb"
click node_lexer "https://github.com/ruby/lrama/blob/master/lib/lrama/lexer.rb"
click node_parser "https://github.com/ruby/lrama/blob/master/lib/lrama/parser.rb"
click node_grammar "https://github.com/ruby/lrama/blob/master/lib/lrama/grammar.rb"
click node_symbols_resolver "https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/symbols/resolver.rb"
click node_param_resolver "https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/parameterized/resolver.rb"
click node_inline_resolver "https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/inline/resolver.rb"
click node_states "https://github.com/ruby/lrama/blob/master/lib/lrama/states.rb"
click node_state "https://github.com/ruby/lrama/blob/master/lib/lrama/state.rb"
click node_warnings "https://github.com/ruby/lrama/blob/master/lib/lrama/warnings.rb"
click node_reporter "https://github.com/ruby/lrama/blob/master/lib/lrama/reporter.rb"
click node_tracer "https://github.com/ruby/lrama/blob/master/lib/lrama/tracer.rb"
click node_output "https://github.com/ruby/lrama/blob/master/lib/lrama/output.rb"
click node_templates "https://github.com/ruby/lrama/tree/master/template/bison"
click node_diagram "https://github.com/ruby/lrama/blob/master/lib/lrama/diagram.rb"

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_exe_lrama,node_command,node_option_parser,node_options toneBlue
class node_context,node_lexer,node_parser,node_states,node_state toneAmber
class node_grammar,node_symbols_resolver,node_param_resolver,node_inline_resolver toneMint
class node_warnings,node_reporter,node_tracer toneRose
class node_output,node_templates,node_diagram toneIndigo
```

## Components

### CLI

Command-line entry and option handling

- [lrama](https://github.com/ruby/lrama/tree/master/exe/lrama): entrypoint · Executable entry point · `exe/lrama`
- [Command](https://github.com/ruby/lrama/blob/master/lib/lrama/command.rb): orchestrator · CLI orchestration and run flow · `lib/lrama/command.rb`
- [Option parser](https://github.com/ruby/lrama/blob/master/lib/lrama/option_parser.rb): cli parser · Parses command-line flags · `lib/lrama/option_parser.rb`
- [Options](https://github.com/ruby/lrama/blob/master/lib/lrama/options.rb): config object · Normalized command settings · `lib/lrama/options.rb`

### Pipeline

Grammar ingestion, analysis, and state construction

- [Context](https://github.com/ruby/lrama/blob/master/lib/lrama/context.rb): build context · Shared compilation context · `lib/lrama/context.rb`
- [Lexer](https://github.com/ruby/lrama/blob/master/lib/lrama/lexer.rb): grammar lexer · Tokenizes Bison-style grammar files · `lib/lrama/lexer.rb`
- [Parser](https://github.com/ruby/lrama/blob/master/lib/lrama/parser.rb): grammar parser · Parses grammar input into internal form · `lib/lrama/parser.rb`
- [States](https://github.com/ruby/lrama/blob/master/lib/lrama/states.rb): lr automaton · Builds the LR state machine · `lib/lrama/states.rb`
- [State](https://github.com/ruby/lrama/blob/master/lib/lrama/state.rb): state machinery · Items, actions, and conflicts · `lib/lrama/state.rb`

### Grammar model

Core grammar data structures and rewrites

- [Grammar](https://github.com/ruby/lrama/blob/master/lib/lrama/grammar.rb): domain model · Core grammar representation · `lib/lrama/grammar.rb`
- [Symbol resolver](https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/symbols/resolver.rb): rewrite pass · Resolves symbol references · `lib/lrama/grammar/symbols/resolver.rb`
- [Param resolver](https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/parameterized/resolver.rb): rewrite pass · Expands parameterized rules · `lib/lrama/grammar/parameterized/resolver.rb`
- [Inline resolver](https://github.com/ruby/lrama/blob/master/lib/lrama/grammar/inline/resolver.rb): rewrite pass · Inlines referenced rules · `lib/lrama/grammar/inline/resolver.rb`

### Analysis

Warnings, reporting, and tracing

- [Warnings](https://github.com/ruby/lrama/blob/master/lib/lrama/warnings.rb): diagnostics · Grammar and conflict warnings · `lib/lrama/warnings.rb`
- [Reporter](https://github.com/ruby/lrama/blob/master/lib/lrama/reporter.rb): analysis report · Human-readable analysis output · `lib/lrama/reporter.rb`
- [Tracer](https://github.com/ruby/lrama/blob/master/lib/lrama/tracer.rb): profiling trace · Generation tracing and timing · `lib/lrama/tracer.rb`

### Emission

Code and diagram generation

- [Output](https://github.com/ruby/lrama/blob/master/lib/lrama/output.rb): emitter · Selects and writes generated artifacts · `lib/lrama/output.rb`
- [Bison templates](https://github.com/ruby/lrama/tree/master/template/bison): template set · C and header emission templates · `template/bison`
- [Diagrams](https://github.com/ruby/lrama/blob/master/lib/lrama/diagram.rb): renderer · Syntax diagram rendering · `lib/lrama/diagram.rb`

## Connections

- lrama → Command: dispatches · Executable hands off to command orchestration
- Command → Option parser: parses · Reads CLI flags and modes
- Command → Options: builds · Produces normalized options
- Command → Context: initializes · Creates run context
- Context → Lexer: uses · Lexes the grammar file
- Context → Parser: uses · Parses token stream into grammar
- Lexer → Parser: feeds · Token stream into parser
- Parser → Grammar: constructs · Builds core grammar model
- Grammar → Symbol resolver: normalizes · Resolves symbol references
- Grammar → Param resolver: expands · Materializes parameterized rules
- Grammar → Inline resolver: inlines · Expands inline rules
- Symbol resolver → States: prepares · Resolved symbols before automaton build
- Param resolver → States: prepares · Expanded parameters before automaton build
- Inline resolver → States: prepares · Inlined grammar before automaton build
- States → State: builds · Constructs items and transitions
- State → Warnings: surfaces · Conflict and grammar issues
- State → Reporter: summarizes · Provides state details for reporting
- Warnings → Reporter: reports · Feeds diagnostic reporting
- States → Tracer: traces · Captures build behavior and cost
- Command → Output: emits · Selects output artifacts
- Output → Bison templates: renders · Generates parser source and headers
- Output → Diagrams: optionally renders · Generates syntax diagrams
- Reporter → Output: informs · Analysis can accompany generated artifacts
