Rantlr

The Modern, Lightweight Parser Generator.
No Java. No Boilerplate. Just Clean Code.

Rantlr turns readable .gr grammars into idiomatic parsers for TypeScript, Python, Go, Java, Ruby, and Erlang — powered by a single Rust binary.

Why Rantlr?

Universal — Codegen for ts, py, go, java, rb (Rails-friendly), and erl (functional / atoms).
Fast — Written in Rust. Single binary, minimal host dependencies.
Modern Syntax — Keywords over EBNF soup (rule, token, match, repeat, optional).
Built-ins — Number, Identifier, QuotedString, Email, Url, DateTime.
Smart Fix — Linter detects left recursion and returns precise rewrite spans (suggestion + byte offsets) for editors and the playground.
Zero runtime lock-in — Generated parsers embed a tiny micro-runtime (packrat memoization on Ruby / Erlang).

Installation

# From crates.io
cargo install rantlr

# From this repository
cargo install --path crates/rantlr-cli

# Or build locally
cargo build -p rantlr --release
# binary: target/release/rantlr

Quick Start (The `.gr` format)

Create a calculator.gr:

grammar Calculator;

token Num = Number;
token Ws = " " -> skip;

rule expr {
    term
    repeat {
        match "+" | "-"
        term
    }
}

rule term {
    Num
}

example "simple_add" {
    input: `1+2`
    expect: expr
}

Usage

1. Parse and validate

rantlr parse examples/calculator.gr

2. Diagnose (JSON for editors / LSP)

rantlr diagnose examples/calculator.gr
# or: rantlr parse examples/calculator.gr --json

Diagnostics may include a fixHint with before / after / suggestion and absolute byte offsets for apply-fix.

3. Generate code

rantlr gen --target ts --out ./parser examples/calculator.gr
# targets: ts | py | go | java | rb | erl
# aliases: typescript, python, golang, ruby, rails, erlang

Target	Flag	Notes
TypeScript	`ts`	Reference micro-runtime
Python	`py`	Dataclasses + PEP8
Go	`go`	Idiomatic packages
Java	`java`	Classes under `rantlr/generated/`
Ruby	`rb`	Snake_case, `Rantlr::ParseError`, memoized rules
Erlang	`erl`	Single module, `{ok, Ast, Rest}`, tail-recursive `repeat`

Examples

File	Description
`examples/calculator.gr`	Classic precedence grammar
`examples/api_gateway.gr`	High-concurrency Rails-style API Gateway DSL
`examples/mesh_protocol.gr`	Erlang distributed mesh packets / heartbeats
`examples/erlang_term.gr`	Erlang-style terms (tuples, lists)
`examples/left_recursive.gr`	Intentionally invalid — Smart Fix demo

Project Structure

Path	Role
`crates/rantlr-core`	Lexer, parser, linter, rule graph, in-process interpreter
`crates/rantlr-cli`	CLI binary (`rantlr`)
`crates/rantlr-gen`	Multi-language codegen
`editors/vscode`	VS Code extension
`playground`	Neon Tauri + React playground
`examples/`	Sample grammars
`docs/`	Language notes (e.g. left recursion)

VS Code Extension

cd editors/vscode
npm install
npm run compile
# Then: F5 in VS Code, or install the extension from the folder

Features:

TextMate syntax highlighting for .gr
On-save diagnostics via rantlr diagnose
Quick Fix for left recursion → docs/left-recursion.md

Set rantlr.cliPath if the binary is not on PATH (defaults to target/debug/rantlr in the workspace).

Playground (Tauri)

Neon visual debugger with Rule Map, Smart Fix Pro, and complex starter templates.

cd playground
npm install
npm run tauri dev

Restart tauri dev after pulling Rust changes so the backend picks up new builtins (e.g. Identifier).

Area	What you get
Grammar editor	Monaco + folding; hover keywords for Dev Buddy tips
Test input	Sample chips per starter; Ctrl+Enter runs Test
Rule Map	Live call graph (cyan = calls, magenta = recursive); stress packet-flow on complex templates
Result	Parse tree, or Fix It with mini-diff + Monaco `executeEdits`
Neon Console	Status + complexity-cost hints

Starter library

Calculator
[Rails] API Gateway DSL — nested routes, rate limits, RoundRobin / LeastConn, auth chains
[Erlang] Distributed Mesh — headers, actor refs, heartbeats / gossip
[Go] PromQL Clone — aggregations, selectors, ranges
[TS] GraphQL→SQL — operations, fragments, directives
[Python] Data Pipeline — extract / clean / transform / train / load
[Java] Bytecode Meta — class metadata + annotations

`.gr` vs ANTLR4

Concept	ANTLR4	Rantlr
Repetition	`*` / `+`	`repeat { … }`
Optionality	`?`	`optional { … }`
Choice	`a \| b`	`match a \| b`
Lexer types	Char classes	`Number`, `Identifier`, `QuotedString`, …
Tests	External	`example` blocks

Contributing

Rantlr is built for the community. See CONTRIBUTING.md to add new target languages, improve the linter, or extend the playground.

License

MIT — see LICENSE. Author: Roberto de Souza <rabbittrix@hotmail.com>

rantlr-core 0.2.0