Skip to main content

antlr_rust_codegen/
builder.rs

1// SPDX-License-Identifier: BSD-3-Clause
2// Copyright (c) 2026 Konstantin Vyatkin
3use std::collections::BTreeSet;
4use std::path::{Path, PathBuf};
5
6use clap::ValueEnum;
7
8use crate::artifact::Generation;
9use crate::config::CompilerConfig;
10use crate::driver;
11use crate::error::Error;
12use crate::parser::MAX_FIXED_LOOKAHEAD_FLAG;
13use crate::rust_support::RustSupportOptions;
14use crate::semantics::{
15    SemPatternFile, SemUnknownPolicy, load_sem_patterns, normalize_option_hook,
16};
17
18/// How grammar action and predicate bodies are interpreted.
19#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, ValueEnum)]
20pub enum ActionMode {
21    #[default]
22    Templates,
23    Embedded,
24}
25
26/// Runtime policy for semantic coordinates that cannot be translated.
27#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, ValueEnum)]
28pub enum UnknownSemanticPolicy {
29    #[default]
30    AssumeTrue,
31    AssumeFalse,
32    Hook,
33    Error,
34}
35
36impl UnknownSemanticPolicy {
37    pub(crate) const fn into_internal(self) -> SemUnknownPolicy {
38        match self {
39            Self::AssumeTrue => SemUnknownPolicy::AssumeTrue,
40            Self::AssumeFalse => SemUnknownPolicy::AssumeFalse,
41            Self::Hook => SemUnknownPolicy::Hook,
42            Self::Error => SemUnknownPolicy::Error,
43        }
44    }
45}
46
47/// Configures grammar compilation and Rust source generation.
48#[derive(Clone, Debug, Eq, PartialEq)]
49#[must_use]
50pub struct Builder {
51    roots: Vec<PathBuf>,
52    library_directories: Vec<PathBuf>,
53    output_directory: Option<PathBuf>,
54    require_generated_parser: bool,
55    allow_unsupported_lexer_actions: bool,
56    semantic_policy: UnknownSemanticPolicy,
57    semantic_patterns: Option<PathBuf>,
58    require_full_semantics: bool,
59    option_hooks: BTreeSet<String>,
60    generate_listener: bool,
61    generate_visitor: bool,
62    action_mode: ActionMode,
63    fixed_lookahead: Option<usize>,
64    entry_rules: BTreeSet<String>,
65    prune_unreachable: bool,
66    optimize_precedence_ladders: bool,
67    report_precedence_ladders: bool,
68}
69
70impl Default for Builder {
71    fn default() -> Self {
72        Self {
73            roots: Vec::new(),
74            library_directories: Vec::new(),
75            output_directory: None,
76            require_generated_parser: false,
77            allow_unsupported_lexer_actions: false,
78            semantic_policy: UnknownSemanticPolicy::default(),
79            semantic_patterns: None,
80            require_full_semantics: false,
81            option_hooks: BTreeSet::new(),
82            generate_listener: true,
83            generate_visitor: false,
84            action_mode: ActionMode::default(),
85            fixed_lookahead: None,
86            entry_rules: BTreeSet::new(),
87            prune_unreachable: false,
88            optimize_precedence_ladders: false,
89            report_precedence_ladders: false,
90        }
91    }
92}
93
94impl Builder {
95    pub fn new() -> Self {
96        Self::default()
97    }
98
99    pub fn grammar(mut self, path: impl AsRef<Path>) -> Self {
100        self.roots.push(path.as_ref().to_path_buf());
101        self
102    }
103
104    pub fn grammars(mut self, paths: impl IntoIterator<Item = impl AsRef<Path>>) -> Self {
105        self.roots
106            .extend(paths.into_iter().map(|path| path.as_ref().to_path_buf()));
107        self
108    }
109
110    pub fn library_directory(mut self, path: impl AsRef<Path>) -> Self {
111        self.library_directories.push(path.as_ref().to_path_buf());
112        self
113    }
114
115    pub fn out_dir(mut self, path: impl AsRef<Path>) -> Self {
116        self.output_directory = Some(path.as_ref().to_path_buf());
117        self
118    }
119
120    pub const fn action_mode(mut self, mode: ActionMode) -> Self {
121        self.action_mode = mode;
122        self
123    }
124
125    pub const fn require_generated_parser(mut self, enabled: bool) -> Self {
126        self.require_generated_parser = enabled;
127        self
128    }
129
130    pub const fn allow_unsupported_lexer_actions(mut self, enabled: bool) -> Self {
131        self.allow_unsupported_lexer_actions = enabled;
132        self
133    }
134
135    pub const fn unknown_semantics(mut self, policy: UnknownSemanticPolicy) -> Self {
136        self.semantic_policy = policy;
137        self
138    }
139
140    pub fn semantic_patterns(mut self, path: impl AsRef<Path>) -> Self {
141        self.semantic_patterns = Some(path.as_ref().to_path_buf());
142        self
143    }
144
145    pub const fn require_full_semantics(mut self, enabled: bool) -> Self {
146        self.require_full_semantics = enabled;
147        self
148    }
149
150    pub fn option_hook(mut self, assignment: impl Into<String>) -> Self {
151        self.option_hooks.insert(assignment.into());
152        self
153    }
154
155    pub const fn generate_listener(mut self, enabled: bool) -> Self {
156        self.generate_listener = enabled;
157        self
158    }
159
160    pub const fn generate_visitor(mut self, enabled: bool) -> Self {
161        self.generate_visitor = enabled;
162        self
163    }
164
165    pub const fn fixed_lookahead(mut self, depth: usize) -> Self {
166        self.fixed_lookahead = Some(depth);
167        self
168    }
169
170    pub fn entry_rule(mut self, name: impl Into<String>) -> Self {
171        self.entry_rules.insert(name.into());
172        self
173    }
174
175    pub const fn prune_unreachable(mut self, enabled: bool) -> Self {
176        self.prune_unreachable = enabled;
177        self
178    }
179
180    pub const fn optimize_precedence_ladders(mut self, enabled: bool) -> Self {
181        self.optimize_precedence_ladders = enabled;
182        self
183    }
184
185    pub const fn report_precedence_ladders(mut self, enabled: bool) -> Self {
186        self.report_precedence_ladders = enabled;
187        self
188    }
189
190    pub fn generate(self) -> Result<Generation, Error> {
191        let config = self.into_config()?;
192        driver::generate(&config, |_| Ok(()))
193    }
194
195    fn into_config(self) -> Result<CompilerConfig, Error> {
196        if self.roots.is_empty() {
197            return Err(Error::configuration(
198                "at least one grammar root is required",
199            ));
200        }
201        let output_directory = self
202            .output_directory
203            .ok_or_else(|| Error::configuration("an output directory is required"))?;
204        if self.optimize_precedence_ladders && self.report_precedence_ladders {
205            return Err(Error::configuration(
206                "precedence-ladder optimization and report-only mode are mutually exclusive",
207            ));
208        }
209        if self
210            .fixed_lookahead
211            .is_some_and(|depth| !(1..=usize::from(MAX_FIXED_LOOKAHEAD_FLAG)).contains(&depth))
212        {
213            return Err(Error::configuration(
214                "fixed lookahead must be between 1 and 8",
215            ));
216        }
217        let semantic_patterns_path = self.semantic_patterns;
218        let semantic_patterns = semantic_patterns_path
219            .as_deref()
220            .map_or_else(|| Ok(SemPatternFile::default()), load_sem_patterns)
221            .map_err(Error::generation)?;
222        let mut option_hooks = BTreeSet::new();
223        for assignment in self.option_hooks {
224            option_hooks.insert(normalize_option_hook(&assignment).map_err(Error::configuration)?);
225        }
226        Ok(CompilerConfig {
227            roots: self.roots,
228            library_directories: self.library_directories,
229            out_dir: output_directory,
230            require_generated_parser: self.require_generated_parser,
231            allow_unsupported_lexer_actions: self.allow_unsupported_lexer_actions,
232            sem_unknown: self.semantic_policy.into_internal(),
233            sem_patterns: semantic_patterns,
234            sem_patterns_path: semantic_patterns_path,
235            require_full_semantics: self.require_full_semantics,
236            option_hooks,
237            generate_listener: self.generate_listener,
238            generate_visitor: self.generate_visitor,
239            embedded_actions: self.action_mode == ActionMode::Embedded,
240            fixed_lookahead: self.fixed_lookahead,
241            entry_rules: self.entry_rules,
242            prune_unreachable: self.prune_unreachable,
243            optimize_precedence_ladders: self.optimize_precedence_ladders,
244            report_precedence_ladders: self.report_precedence_ladders,
245            test_rig: None,
246            rust_support: RustSupportOptions::disabled(),
247        })
248    }
249}
250
251#[cfg(test)]
252mod tests {
253    use super::Builder;
254
255    #[test]
256    fn new_matches_default() {
257        assert_eq!(Builder::new(), Builder::default());
258    }
259}