rantlr-core 0.2.0

# Rantlr

<p align="center">
  <img src="assets/rantlr-logo.png" alt="Rantlr logo" width="120" />
</p>

**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

```bash
# 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`:

```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**

```bash
rantlr parse examples/calculator.gr
```

**2. Diagnose (JSON for editors / LSP)**

```bash
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**

```bash
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`](examples/calculator.gr) | Classic precedence grammar |
| [`examples/api_gateway.gr`](examples/api_gateway.gr) | High-concurrency Rails-style API Gateway DSL |
| [`examples/mesh_protocol.gr`](examples/mesh_protocol.gr) | Erlang distributed mesh packets / heartbeats |
| [`examples/erlang_term.gr`](examples/erlang_term.gr) | Erlang-style terms (tuples, lists) |
| [`examples/left_recursive.gr`](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](docs/left-recursion.md)) |

## VS Code Extension

```bash
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](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.

```bash
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](CONTRIBUTING.md) to add new target languages, improve the linter, or extend the playground.

## License

MIT — see [LICENSE](LICENSE). Author: Roberto de Souza \<rabbittrix@hotmail.com\>