lrama

---

Like a lathe shaping raw metal into precise gears, lrama turns grammar rules into deterministic parser machinery. This Crystal port keeps the engineering intent of Ruby lrama while producing native Crystal output tuned for speed and memory efficiency.

---

Quick Start

shards install
crystal run src/lrama/main.cr -- --help
crystal spec

Features

• Parses .y grammars and builds Crystal-native grammar/state structures.
• Generates Crystal parser output from LR/LALR analysis.
• Includes runtime parser/lexer/location/token components under Lrama::Runtime.
• Supports reporting for grammar/rules/terms/states/conflicts.
• Provides fixture and golden-output based spec coverage.

Status

Early scaffolding: lexer, fixtures, and specs are in place to validate token streams and locations. Parser generation is in active development.

Development

Requirements:

• Crystal 1.9+
• Ameba (dev dependency)

Useful commands:

crystal tool format src spec
ameba src spec
crystal spec

See Development Guide for full setup instructions.

Profiling And Error Recovery

Profiling uses Crystal-native timing and GC stats:

crystal run src/lrama/main.cr -- --profile=memory sample/calc.y -o sample/calc_parser.cr

This prints lines like profile.time total=... and profile.memory.* deltas to STDERR. For call-stack profiling, use an external profiler and enable the flag for a hint:

crystal run src/lrama/main.cr -- --profile=call-stack sample/calc.y -o sample/calc_parser.cr

Error recovery is controlled at codegen time:

crystal run src/lrama/main.cr -- -e sample/calc.y -o sample/calc_parser.cr

Lexer Tuning

By default the generated lexer uses fast tables and a byte-slice loop. For very large DFAs, you can opt into more compact tables or a keyword trie:

crystal run src/lrama/main.cr -- -Dlexer.row_dedup=true sample/calc.y -o sample/calc_parser.cr
crystal run src/lrama/main.cr -- -Dlexer.keyword_trie=true sample/calc.y -o sample/calc_parser.cr

These settings trade a bit of speed for memory savings on large lexers.

For quick comparisons, use the microbench harness:

crystal run --release bench/bench.cr
LRAMA_BENCH_GRAMMAR=path/to/grammar.y crystal run --release bench/bench.cr

Layout

• src/ - Crystal implementation
• spec/ - Crystal specs and fixtures
• docs/ - Architecture and workflow documentation
• lrama/ - Ruby lrama submodule for reference
• racc/ - Ruby racc submodule for reference

Submodules

Update the Ruby submodules via Make targets:

make update_lrama
make update_racc
make update_submodules

Documentation

Document	Purpose
Architecture	System design and data flow
Development	Setup and daily workflow
Coding Guidelines	Code style and conventions
Testing	Test commands and patterns
PR Workflow	Commits, PRs, and review process
Migration	Ruby-to-Crystal migration guidance

Contributing

1. Create an issue: /forge-create-issue
2. Implement: /forge-implement-issue <number>
3. Self-review: /forge-reflect-pr
4. Address feedback: /forge-address-pr-feedback
5. Update changelog: /forge-update-changelog

Examples

• examples/sql.y - SQL SELECT grammar using the lexer DSL and Crystal runtime.