Skip to main content

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}