Skip to main content

antlr_rust_codegen/
builder.rs

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