dbt_antlr_codegen/optimization/options.rs
1// SPDX-License-Identifier: BSD-3-Clause
2// Copyright (c) 2026 Konstantin Vyatkin
3use std::collections::BTreeSet;
4
5/// Optimization selection for one generation run.
6///
7/// Grammar transforms rewrite the grammar model before ATN construction.
8/// These transforms preserve recognition (that is, the generated parser
9/// accepts the same language). However, they are **NOT tree-preserving**!
10/// When enabled, the generated parse tree can differ from the `.g4` grammar.
11///
12/// Static lexer DFA generation ([`Self::static_lexer_dfa`]) precomputes lexer
13/// DFA tables after ATN construction and preserves both tokens and APIs.
14/// Static parser DFA generation ([`Self::static_parser_dfa`]) precomputes
15/// parser prediction tables after ATN construction and preserves both parse
16/// trees and recognizer APIs.
17///
18/// Static-only DFA generation ([`Self::static_dfa_only`]) selects both static
19/// DFA passes and removes every `adaptive_predict` fallback. As a result, the
20/// generated parser can reject input that the grammar accepts. A part of the
21/// grammar that the static tables cannot decide stops the generation.
22///
23/// Selected optimization passes write their reports to a manifest next to the
24/// generated files. The manifest of `ClickHouseParser.g4` is
25/// `clickhouseparser.optimizations.txt`. For the `static-parser-dfa` pass, the
26/// manifest lists each parser decision (`decisionInventory`) with the counts
27/// that add up to the totals of the pass.
28///
29/// When [`Self::report_only`] is enabled, the generator compiles, analyzes,
30/// and optimizes the input grammars without emitting recognizer files.
31#[derive(Clone, Debug, Default, Eq, PartialEq)]
32pub struct OptimizationOptions {
33 pub(crate) entry_rules: BTreeSet<String>,
34 pub(crate) prune_unreachable: bool,
35 pub(crate) inline_trivial_rules: bool,
36 pub(crate) optimize_precedence_ladders: bool,
37 pub(crate) static_lexer_dfa: bool,
38 pub(crate) static_parser_dfa: bool,
39 pub(crate) static_dfa_only: bool,
40 pub(crate) dump_dfas: Option<String>,
41 pub(crate) profile_decisions: bool,
42 pub(crate) report_only: bool,
43 pub(crate) strict: bool,
44}
45
46impl OptimizationOptions {
47 /// Starts an empty selection.
48 pub fn new() -> Self {
49 Self::default()
50 }
51
52 /// Marks `name` as an explicit parser entry rule. Configured entry rules
53 /// are preserved by every transform and anchor the reachability analysis
54 /// behind [`Self::prune_unreachable_rules`]. Repeatable.
55 pub fn entry_rule(&mut self, name: impl Into<String>) -> &mut Self {
56 self.entry_rules.insert(name.into());
57 self
58 }
59
60 /// Deletes parser rules that are unreachable from the entry rules.
61 /// Default: `false` (unreachable rules only produce a warning).
62 pub const fn prune_unreachable_rules(&mut self, enabled: bool) -> &mut Self {
63 self.prune_unreachable = enabled;
64 self
65 }
66
67 /// Inlines trivial pure parser rules (token sets and single-use pure
68 /// sequences) into their call sites. Default: `false`.
69 pub const fn inline_trivial_rules(&mut self, enabled: bool) -> &mut Self {
70 self.inline_trivial_rules = enabled;
71 self
72 }
73
74 /// Collapses precedence-ladder rule chains (`a: b (op b)*; b: c ...`)
75 /// into a single left-recursive rule. Default: `false`.
76 pub const fn optimize_precedence_ladders(&mut self, enabled: bool) -> &mut Self {
77 self.optimize_precedence_ladders = enabled;
78 self
79 }
80
81 /// Precomputes static lexer DFA tables (`--static-lexer-dfa`, lexer scope
82 /// only). Default: `false`.
83 pub const fn static_lexer_dfa(&mut self, enabled: bool) -> &mut Self {
84 self.static_lexer_dfa = enabled;
85 self
86 }
87
88 /// Precomputes static parser DFA tables (`--static-parser-dfa`, parser
89 /// scope only). Default: `false`.
90 pub const fn static_parser_dfa(&mut self, enabled: bool) -> &mut Self {
91 self.static_parser_dfa = enabled;
92 self
93 }
94
95 /// Generates only fully static lexers and parsers (`--static-dfa-only`).
96 /// Default: `false`.
97 ///
98 /// This option selects [`Self::static_lexer_dfa`] and
99 /// [`Self::static_parser_dfa`]. The generated recognizers never fall back
100 /// to the adaptive ATN simulation:
101 ///
102 /// - If a lexer mode does not compile to a complete static table, the
103 /// generation fails.
104 /// - If a parser decision has no static table, the generation fails.
105 /// - A partial parser table looks further than in the default mode.
106 /// - In a partial parser table, a state with an SLL conflict predicts the
107 /// minimum conflicting alternative. A state where the lookahead budget
108 /// stops predicts its minimum viable alternative. A predicated state
109 /// reports a syntax error.
110 ///
111 /// In report-only mode, these failures are error diagnostics and the
112 /// reports are still rendered.
113 pub const fn static_dfa_only(&mut self, enabled: bool) -> &mut Self {
114 self.static_dfa_only = enabled;
115 self
116 }
117
118 /// Renders the static parser DFA tables matching `spec`
119 /// (`--dump-dfas <SPEC>`) and implies [`Self::report_only`].
120 pub fn dump_dfas(&mut self, spec: impl Into<String>) -> &mut Self {
121 self.dump_dfas = Some(spec.into());
122 self
123 }
124
125 /// Renders the time and the work that the `static-parser-dfa` pass spends
126 /// on each parser decision (`--profile-decisions`) and implies
127 /// [`Self::report_only`]. The times change from run to run.
128 pub const fn profile_decisions(&mut self, enabled: bool) -> &mut Self {
129 self.profile_decisions = enabled;
130 self
131 }
132
133 /// Compiles, analyzes, and optimizes the input grammars without writing
134 /// output files (`--report-only`, `--dry-run`, `-n`). Default: `false`.
135 pub const fn report_only(&mut self, enabled: bool) -> &mut Self {
136 self.report_only = enabled;
137 self
138 }
139
140 /// Reports an implicit token definition in a parser grammar (`G4S030`)
141 /// as an error instead of a warning (`--strict`). Default: `false`.
142 ///
143 /// A parser grammar defines a token implicitly when it refers to a token
144 /// that its token vocabulary (`tokenVocab`) or the lexer rules of its
145 /// combined grammar do not define. The parser gets a token type for this
146 /// token, but the lexer never emits it. Usually, the reference is a
147 /// spelling error or a lexer rule that is missing.
148 ///
149 /// The errors stop the generation. In report-only mode, the errors are
150 /// diagnostics and the reports are still rendered.
151 pub const fn strict(&mut self, enabled: bool) -> &mut Self {
152 self.strict = enabled;
153 self
154 }
155
156 /// Whether the selection prints instead of writing files: `--report-only`
157 /// or a report mode that implies it (`--dump-dfas`,
158 /// `--profile-decisions`).
159 pub(crate) const fn is_report_only(&self) -> bool {
160 self.report_only || self.has_parser_reports()
161 }
162
163 #[cfg(feature = "download")]
164 pub(crate) fn entry_rules(&self) -> impl Iterator<Item = &str> {
165 self.entry_rules.iter().map(String::as_str)
166 }
167
168 #[cfg(feature = "download")]
169 pub(crate) const fn prune_unreachable(&self) -> bool {
170 self.prune_unreachable
171 }
172
173 #[cfg(feature = "download")]
174 pub(crate) const fn inline_trivial(&self) -> bool {
175 self.inline_trivial_rules
176 }
177
178 #[cfg(feature = "download")]
179 pub(crate) const fn optimize_ladders(&self) -> bool {
180 self.optimize_precedence_ladders
181 }
182
183 #[cfg(feature = "download")]
184 pub(crate) const fn static_dfa(&self) -> bool {
185 self.static_lexer_dfa
186 }
187
188 #[cfg(feature = "download")]
189 pub(crate) const fn static_parser_dfa_enabled(&self) -> bool {
190 self.static_parser_dfa
191 }
192
193 #[cfg(feature = "download")]
194 pub(crate) const fn static_dfa_only_enabled(&self) -> bool {
195 self.static_dfa_only
196 }
197
198 #[cfg(feature = "download")]
199 pub(crate) const fn strict_enabled(&self) -> bool {
200 self.strict
201 }
202
203 /// Whether the selection prints parser reports, which only the in-process
204 /// generator can render.
205 pub(crate) const fn has_parser_reports(&self) -> bool {
206 self.dump_dfas.is_some() || self.profile_decisions
207 }
208}