<!-- Generated by `cargo xtask antlr generate kotlin` from xtask/templates/parser-readme.md. Do not edit by hand. -->
# mehen-kotlin-parser

ANTLR-generated **Kotlin** lexer and parser, running on the
[`antlr-rust-runtime`](https://github.com/ophi-dev/antlr-rust-runtime) Rust
runtime.

This crate is produced by the [`mehen`](https://github.com/ophi-dev/mehen) code-metrics tool but
carries **no mehen-specific logic** and **no dependency on `mehen-core`**: it
ships only the machine-generated lexer/parser plus the vendored `.g4` grammar.
That makes it usable on its own — the same way `mehen` itself consumes the
ruff / oxc / sqruff parser crates — so you can parse Kotlin in your
own tool without pulling in an analyzer.

<!-- Both the modules under `src/generated/` and this README are generated and
     checked in verbatim; regenerate with `cargo xtask antlr generate kotlin`. -->

## Add the dependency

The crate is published from a git tag on the [`mehen` repository](https://github.com/ophi-dev/mehen),
not to crates.io. Depend on it by tag or branch:

```toml
[dependencies]
# Pin a release tag (recommended) — see the repository's Releases page:
mehen-kotlin-parser = { git = "https://github.com/ophi-dev/mehen", tag = "vX.Y.Z" }
# …or track the default branch:
# mehen-kotlin-parser = { git = "https://github.com/ophi-dev/mehen", branch = "main" }
```

You do **not** need to depend on `antlr-rust-runtime` yourself: this crate
re-exports the exact runtime revision the modules were generated against as
`mehen_kotlin_parser::antlr4_runtime`. Reach the runtime types (`ParsedFile`,
`Node`, `TokenView`, …) through that path so your version can never drift from
the generated code.

## Parse some Kotlin

`kotlin_parser::parse` wires up the lexer, token stream, parser, and a
chosen entry rule in one call, returning an owned `ParsedFile` that holds the
token store and the flat CST:

```rust
use mehen_kotlin_parser::kotlin_parser::{self, KotlinParser};
use mehen_kotlin_parser::kotlin_lexer::KotlinLexer;

fn main() -> Result<(), mehen_kotlin_parser::antlr4_runtime::AntlrError> {
    let parsed = kotlin_parser::parse(
        "fun main() {}\n",
        KotlinLexer::new,
        KotlinParser::kotlin_file,
    )?;

    // Walk the CST from the entry-rule root, or read the buffered tokens.
    let root = parsed.tree();
    let _ = root;
    Ok(())
}
```

Need parser diagnostics (e.g. the syntax-error count) after the entry rule
runs? Use `parse_with_parser`, which hands the parser back:

```rust
use mehen_kotlin_parser::kotlin_parser::{self, KotlinParser};
use mehen_kotlin_parser::kotlin_lexer::KotlinLexer;
// `number_of_syntax_errors` is a `Parser`-trait method, so the trait must be
// in scope to call it.
use mehen_kotlin_parser::antlr4_runtime::Parser;

fn main() -> Result<(), mehen_kotlin_parser::antlr4_runtime::AntlrError> {
    let out = kotlin_parser::parse_with_parser(
        "fun main() {}\n",
        KotlinLexer::new,
        KotlinParser::kotlin_file,
    )?;
    let errors = out.parser.number_of_syntax_errors();
    let parsed = out.parser.into_parsed_file(out.result);
    let _ = (errors, parsed.tree());
    Ok(())
}
```

The parse tree has **no parent pointers** (the runtime stores `Node` views in a
flat arena), so thread any parent-dependent context top-down as you walk.

## Grammar & provenance

- **Upstream grammar:** [`Kotlin/kotlin-spec`](https://github.com/Kotlin/kotlin-spec)
- **Vendored `.g4` files + any local patches:** [`grammar/`](grammar/) — see [`grammar/PROVENANCE.md`](grammar/PROVENANCE.md) for the exact commit
- **ANTLR Rust runtime + codegen:** [`antlr-rust-runtime`](https://crates.io/crates/antlr-rust-runtime) / [`antlr-rust-codegen`](https://crates.io/crates/antlr-rust-codegen) `v0.29.0`

## License

`AGPL-3.0-only`, same as the `mehen` workspace.
