rantlr-core 0.1.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, and Java — powered by a single Rust binary.

## Why Rantlr?

- **Universal** — Generates clean, idiomatic code for TS, Python, Go, Java, and more.
- **Fast** — Written in Rust. Single binary, minimal host dependencies.
- **Modern Syntax** — `.gr` files are easier to read than EBNF / ANTLR4.
- **Smart** — Built-in linter with auto-suggestions for common grammar mistakes (including left recursion).
- **Zero runtime lock-in** — Generated parsers embed a tiny BaseParser helper; copy the folder and go.

## 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 calculator.gr
```

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

```bash
rantlr diagnose calculator.gr
# or: rantlr parse calculator.gr --json   # AST on success; diagnostics on failure
```

**3. Generate code**

```bash
rantlr gen --target ts --out ./parser calculator.gr
# targets: ts | py | go | java
```

## Project Structure

| Path | Role |
|------|------|
| `crates/rantlr-core` | Rust engine — Lexer, Parser, Linter, in-process runtime |
| `crates/rantlr-cli` | Command-line interface (crate `rantlr`) |
| `crates/rantlr-gen` | Code generation for TS / Python / Go / Java |
| `editors/vscode` | Visual Studio Code extension |
| `playground` | Tauri + React visual debugger |
| `examples/` | Sample `.gr` / `.g4` grammars |
| `docs/` | Language notes (e.g. left recursion) |

## 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` (red squiggles)
- Quick Fix for left recursion → opens [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)

```bash
cd playground
npm install
npm run tauri dev
```

- **Left:** Monaco editor for the `.gr` grammar  
- **Right top:** test input  
- **Right bottom:** live parse tree (or error)  
- Backend command `analyze_grammar` validates the grammar and interprets the test input in Rust

## `.gr` vs ANTLR4

| Concept | ANTLR4 | Rantlr |
|---------|--------|--------|
| Repetition | `*` / `+` | `repeat { … }` |
| Optionality | `?` | `optional { … }` |
| Choice | `a \| b` | `match a \| b` |
| Lexer types | Char classes | `Number`, `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 repository metadata. Author: Roberto de Souza \<rabbittrix@hotmail.com\>