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