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

ANTLR-generated **Java** 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 Java 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 java`. -->

## 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-java-parser = { git = "https://github.com/ophi-dev/mehen", tag = "vX.Y.Z" }
# …or track the default branch:
# mehen-java-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_java_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 Java

The grammar declares helper methods on a superclass (`superClass=…`); this
crate ships exact Rust ports as typed hooks in [`src/hooks.rs`](src/hooks.rs),
and they **must be installed at construction**. The modules are generated
under `--sem-unknown error`, so a lexer/parser built without its hooks
fails loud (`AntlrError::Unsupported`) the moment an input reaches a hooked
predicate or action — it never silently mis-parses. In particular, skip the
hook-less one-call `java_parser::parse` / `parse_with_parser`
helpers and construct with hooks:

```rust
use mehen_java_parser::hooks::JavaParserBase;
use mehen_java_parser::java_parser::JavaParser;
use mehen_java_parser::java_lexer::JavaLexer;
use mehen_java_parser::antlr4_runtime::{CommonTokenStream, InputStream, Parser};

fn main() -> Result<(), mehen_java_parser::antlr4_runtime::AntlrError> {
    let input = InputStream::new("class C {}\n");
    let lexer = JavaLexer::new(input);
    let tokens = CommonTokenStream::new(lexer);
    let mut parser = JavaParser::with_typed_hooks(tokens, JavaParserBase::default());
    let result = parser.compilation_unit()?;

    // Parser diagnostics, then the owned `ParsedFile` (token store + flat CST).
    let errors = parser.number_of_syntax_errors();
    let parsed = parser.into_parsed_file(result);
    let root = parsed.tree();
    let _ = (errors, root);
    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:** [`antlr/grammars-v4`](https://github.com/antlr/grammars-v4)
- **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.
