antlr-rust-codegen
Rust library and antlr4-rust-gen command for compiling ANTLR v4 grammars
into source compatible with antlr-rust-runtime.
Use it from a build script:
# x-release-please-start-version
[]
= "0.30.0"
[]
= "0.30.0"
# x-release-please-end
Successful generations expose structured compiler warnings through
Generation::diagnostics(), including the diagnostic code, severity, source
path, and exact UTF-8 byte span. Generation::warnings() retains the rendered
CLI messages.
Or install the command:
The package also provides antlr4-rust-testrig for running a grammar directly
against UTF-8 files or stdin. A grammar-only project needs no Cargo.toml,
generated Rust sources, or runtime dependency; only a Rust toolchain is
required because TestRig invokes Cargo internally:
Use tokens as the start rule for a lexer grammar. For split grammars, pass
the parser grammar first and pair it with --lexer-grammar:
The command generates and compiles a temporary grammar-specific runner with the
matching runtime because Rust cannot reflectively load recognizer types or call
a rule by name. It removes the temporary package afterward while retaining
Cargo build artifacts in the current user's cache for subsequent invocations;
set ANTLR4_RUST_TESTRIG_TARGET_DIR to override that location. --trace,
--diagnostics, and --sll expose the corresponding parser modes;
exact-ambiguity diagnostics and SLL prediction are mutually exclusive. The
command processes every input and exits non-zero if generation, compilation,
input reading, lexing, or parsing reports an error, so the same command can be
used as a test runner.
The runtime, codegen, and internal parser packages are released in lockstep.
Internal module ownership
src/grammar/semantics.rs is the documented exception to the 2,000-line
production-module guideline. Its semantic pass deliberately keeps vocabulary
numbering, symbol diagnostics, action binding, and the resulting
SemanticBindings mutation in one owner because they share source-coordinate
and declaration-order invariants. The independently mutable grammar
integration, validation, transform registry, transform analyses, and transform
passes are separate modules; splitting this remaining pass would expose its
partially built vocabulary and binding state as a wider internal contract
without creating an independent optimization or rendering boundary.