How ruby/lrama works
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: command.rb Command · states.rb States · grammar.rb Grammar · output.rb Output
Components 19
CLI
Command-line entry and option handling
- lrama · Executable entry point
exe/lrama - Command · CLI orchestration and run flow
lib/lrama/command.rb - Option parser · Parses command-line flags
lib/lrama/option_parser.rb - Options · Normalized command settings
lib/lrama/options.rb
Pipeline
Grammar ingestion, analysis, and state construction
Grammar model
Core grammar data structures and rewrites
- Grammar · Core grammar representation
lib/lrama/grammar.rb - Symbol resolver · Resolves symbol references
lib/lrama/grammar/symbols/resolver.rb - Param resolver · Expands parameterized rules
lib/lrama/grammar/parameterized/resolver.rb - Inline resolver · Inlines referenced rules
lib/lrama/grammar/inline/resolver.rb
Analysis
Warnings, reporting, and tracing
Emission
Code and diagram generation
- Output · Selects and writes generated artifacts
lib/lrama/output.rb - Bison templates · C and header emission templates
template/bison - Diagrams · Syntax diagram rendering
lib/lrama/diagram.rb
Connections 23
- 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