substrait-antlr 0.107.0

Generated Substrait ANTLR Parser Code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# substrait-antlr

Generated Rust [ANTLR](https://www.antlr.org/) parsers for the
[Substrait](https://substrait.io/) grammars, built against the
[`antlr4rust`](https://docs.rs/antlr4rust) runtime.

The grammars from which the code is generated can be found
[here](https://github.com/substrait-io/substrait/tree/main/grammar).

Versions of this crate correspond to Substrait
[releases](https://github.com/substrait-io/substrait/releases). `vx.y.z` of
`substrait-antlr` contains code generated from `vx.y.z` of the
[substrait repository](https://github.com/substrait-io/substrait).

## Usage

```rust
use substrait_antlr::antlr4rust::common_token_stream::CommonTokenStream;
use substrait_antlr::antlr4rust::InputStream;
use substrait_antlr::substrait_type::{SubstraitTypeLexer, SubstraitTypeParser};

let lexer = SubstraitTypeLexer::new(InputStream::new("list?<i32>"));
let tokens = CommonTokenStream::new(lexer);
let mut parser = SubstraitTypeParser::new(tokens);
let tree = parser.startRule().unwrap();
```

- `substrait_type` — lexer/parser/listeners for the Substrait type grammar
  (`SubstraitType.g4`).
- `func_test_case` — lexer/parser/listeners for the function test case grammar
  (`FuncTestCaseParser.g4`).

The generated code only works with the exact `antlr4rust` version it was
generated for, so this crate re-exports that runtime as
`substrait_antlr::antlr4rust`. Use it through the re-export rather than
depending on `antlr4rust` directly, so that the two can never drift apart.

## Generation and Publishing

Code generation and publishing is handled in the
[substrait-packaging](https://github.com/substrait-io/substrait-packaging)
repository.

Unlike the other Substrait Rust crates, the ANTLR parsers are **committed** to
the repository, because regenerating them requires a forked ANTLR build (the
Rust target is not yet part of upstream ANTLR) and Java, neither of which is a
cargo build dependency.

When a new version of the Substrait specification is released, automation
regenerates the parsers for that version and pushes them to GitHub with a tag
formatted like `rust/substrait-antlr/vx.y.z`. The automation then publishes that
crate to [crates.io](https://crates.io/crates/substrait-antlr).

### Local Generation

The `generate_antlr.sh` script can be executed locally to regenerate the
parsers. It downloads the forked ANTLR JAR and requires `java`. Set
`SUBSTRAIT_HOME` to a directory containing the Substrait specification (defaults
to `../../substrait`).