Skip to main content

antlr_rust_codegen/
builder.rs

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