treesitter_lang/error.rs
1//! Why a grammar could not be emitted, or a tree could not be rendered.
2
3use alloc::string::String;
4use core::fmt;
5
6/// Why [`Grammar`](crate::Grammar) refused to emit a grammar, or to render a
7/// tree as an S-expression.
8///
9/// Emitting validates the whole grammar first and reports the first problem,
10/// checking in this order:
11///
12/// 1. names (the grammar's, then each rule's, then each external's), the
13/// start rule, and duplicate rules;
14/// 2. every rule body in definition order, then the extras: symbols resolve
15/// and are not inside tokens, patterns and choices are not empty,
16/// patterns are regular expressions JavaScript accepts, field and alias
17/// names are identifiers;
18/// 3. the names in `word`, `conflicts`, `inline`, and `supertypes` resolve;
19/// 4. the rules reachable from the start rule and the extras: no cycle of
20/// rules that can each be just the next; then, in definition order, no
21/// empty strings, only patterns tree-sitter's regular expression parser
22/// accepts, and nothing that can match the empty string where
23/// tree-sitter needs a token; then the patterns in the extras;
24/// 5. the word token, externals sharing a rule's name, inlined rules, and
25/// supertypes.
26///
27/// Every variant names a mistake that would otherwise surface later, as an
28/// error from `tree-sitter generate` — in two cases as a crash or a hang — or
29/// as a `grammar.js` that does not load. Rules that cannot be reached from the
30/// start rule or the extras are checked only as far as `grammar.js` itself
31/// evaluates them (step 2), because tree-sitter drops them.
32///
33/// What validation does not do is build parse tables. The problems
34/// tree-sitter finds while building them — conflicts, and extras made of
35/// rules whose end it cannot tell — are reported by `tree-sitter generate`.
36///
37/// Where a variant has a `rule` field, it holds the name of the rule the
38/// problem was found in, or — for a problem outside any rule — the name of the
39/// grammar field it was found in: `extras`, `word`, `conflicts`, `inline`, or
40/// `supertypes`.
41///
42/// # Examples
43///
44/// ```
45/// use treesitter_lang::{Error, Grammar, Rule};
46///
47/// let grammar = Grammar::new("demo").rule("source_file", Rule::symbol("item"));
48///
49/// match grammar.to_js() {
50/// Err(Error::UndefinedSymbol { symbol, rule }) => {
51/// assert_eq!(symbol, "item");
52/// assert_eq!(rule, "source_file");
53/// }
54/// other => panic!("unexpected {other:?}"),
55/// }
56/// ```
57#[derive(Clone, Debug, PartialEq, Eq)]
58#[non_exhaustive]
59pub enum Error {
60 /// The grammar name, a rule name, an external, a field name, or an alias
61 /// name is not an identifier. Names must start with an ASCII letter or
62 /// `_` and continue with ASCII letters, digits, or `_`; tree-sitter turns
63 /// them into JavaScript property names and C identifiers. A rule or an
64 /// external may not be called `__proto__`, which JavaScript reserves.
65 ///
66 /// Rename it. Tree-sitter convention is `snake_case`.
67 InvalidName {
68 /// The offending name.
69 name: String,
70 },
71
72 /// The grammar has no rules. Tree-sitter needs at least one: the first
73 /// rule is the start rule.
74 NoRules,
75
76 /// Two rules share a name. The second definition would silently replace
77 /// the first in `grammar.js`, so it is refused instead.
78 ///
79 /// Rename one of them, or merge them with [`Rule::choice`](crate::Rule::choice).
80 DuplicateRule {
81 /// The name defined more than once.
82 name: String,
83 },
84
85 /// The first rule — the start rule, the root of every tree — is hidden
86 /// (its name starts with `_`). Tree-sitter requires it to be visible.
87 ///
88 /// Rename it, or add a visible rule in front of it.
89 HiddenStart {
90 /// The start rule's name.
91 name: String,
92 },
93
94 /// A symbol names neither a rule nor an external token.
95 ///
96 /// Usually a typo; otherwise define the rule with
97 /// [`Grammar::rule`](crate::Grammar::rule) or declare it with
98 /// [`Grammar::external`](crate::Grammar::external).
99 UndefinedSymbol {
100 /// The undefined name.
101 symbol: String,
102 /// Where it was referred to.
103 rule: String,
104 },
105
106 /// A string literal in a reachable rule is empty — tree-sitter refuses
107 /// these outside tokens and in most places inside them, and the rest can
108 /// only match nothing — or a pattern is empty or is not a regular
109 /// expression tree-sitter can use.
110 ///
111 /// A pattern must be a regular expression literal JavaScript accepts,
112 /// wherever it is, because `grammar.js` evaluates every rule; and, in a
113 /// rule reachable from the start rule or in an extra, one tree-sitter's
114 /// own regular expression parser accepts. The accepted forms are listed
115 /// in
116 /// [`docs/API.md`](https://github.com/jamesgober/treesitter-lang/blob/main/docs/API.md#accepted-patterns).
117 ///
118 /// For an empty string or pattern, `rule` is the name of the rule (or
119 /// `extras`). For an invalid pattern — non-empty — `rule` is that name,
120 /// then `: `, then what is wrong, the byte offset in the pattern where it
121 /// is, and the start of the pattern, as in
122 /// `` "number: unterminated character class at byte 0 of `[0-9`" ``.
123 /// Rule names never contain `: `, so the part before the first `: ` is
124 /// always the rule's name. (The error type is frozen at 1.0; this
125 /// variant, the one for a pattern that cannot be written as a regular
126 /// expression literal, carries the report.)
127 ///
128 /// Use [`Rule::blank`](crate::Rule::blank) or
129 /// [`Rule::optional`](crate::Rule::optional) to express "nothing"; fix
130 /// an invalid pattern as the report says.
131 EmptyString {
132 /// Where the empty string or pattern was found, and for an invalid
133 /// pattern, what is wrong with it.
134 rule: String,
135 },
136
137 /// A [`Rule::choice`](crate::Rule::choice) has no alternatives, so it can
138 /// never match. Tree-sitter does not report this; it is always a mistake.
139 EmptyChoice {
140 /// Where the empty choice was found.
141 rule: String,
142 },
143
144 /// A symbol appears inside [`Rule::token`](crate::Rule::token),
145 /// [`Rule::immediate`](crate::Rule::immediate), or an extra that is not a
146 /// lone symbol — all of which are lexed as one token, so their contents
147 /// may only be strings, patterns, and the combinators over them, not
148 /// references to other rules.
149 ///
150 /// Inline the referenced rule's strings and patterns into the token, or
151 /// make the extra a symbol naming a rule.
152 SymbolInToken {
153 /// The symbol found inside the token.
154 symbol: String,
155 /// The rule containing the token, or `extras`.
156 rule: String,
157 },
158
159 /// Something tree-sitter needs to match at least one token can match
160 /// the empty string: a rule that another reachable rule (or an extra)
161 /// refers to, or the contents of a [`Rule::repeat`](crate::Rule::repeat)
162 /// or [`Rule::repeat1`](crate::Rule::repeat1) in a reachable rule. Only a
163 /// rule nothing refers to — in practice the start rule — may match
164 /// nothing.
165 ///
166 /// Move the optionality outward: make the rule (or the repeated part)
167 /// match at least one token, and wrap its uses in
168 /// [`Rule::optional`](crate::Rule::optional), or use
169 /// [`Rule::repeat1`](crate::Rule::repeat1) instead of
170 /// [`Rule::repeat`](crate::Rule::repeat).
171 MatchesEmpty {
172 /// The rule that can match nothing, or that contains the repetition.
173 rule: String,
174 },
175
176 /// Reachable rules form a cycle in which each can be just the next —
177 /// `a` can be `b` alone and `b` can be `a` alone — so one piece of text
178 /// would have endlessly many trees. Tree-sitter refuses this as an
179 /// "indirectly recursive rule". A rule can be another alone when that
180 /// rule is one of its alternatives, through
181 /// [`choice`](crate::Rule::choice), [`optional`](crate::Rule::optional),
182 /// [`prec`](crate::Rule::prec), [`field`](crate::Rule::field), and
183 /// [`alias`](crate::Rule::alias). Also reported: a hidden rule with an
184 /// alternative that is itself under a non-zero `prec`, `prec.left`, or
185 /// `prec.right`, on which tree-sitter loops forever.
186 ///
187 /// Break the cycle: usually one of the rules should require more than
188 /// the other (a delimiter, an operator), or the two should be one rule.
189 IndirectRecursion {
190 /// A rule on the cycle.
191 rule: String,
192 },
193
194 /// The [`word`](crate::Grammar::word) rule is not a token. Tree-sitter
195 /// requires it to be a single terminal: not the start rule, its body a
196 /// string, a pattern, [`Rule::token`](crate::Rule::token), or
197 /// [`Rule::immediate`](crate::Rule::immediate) — with no
198 /// [`prec`](crate::Rule::prec), [`field`](crate::Rule::field), or
199 /// [`alias`](crate::Rule::alias) around it — and that token used nowhere
200 /// else in the reachable rules (tree-sitter would merge the two uses,
201 /// leaving the rule a non-terminal). A hidden rule whose token is only a
202 /// string literal is not a token either: tree-sitter treats it as that
203 /// anonymous string. Or the word may be an external.
204 ///
205 /// Refer to the word rule by symbol wherever its token is needed.
206 WordNotToken {
207 /// The word rule's name.
208 name: String,
209 },
210
211 /// An [external](crate::Grammar::external) shares its name with a rule
212 /// that is not a token. A rule may share an external's name only as the
213 /// fallback lexer for it, so it must meet the same conditions as the
214 /// [word token](Error::WordNotToken).
215 ///
216 /// Rename one of them, or make the rule a token.
217 InvalidExternal {
218 /// The external's name.
219 name: String,
220 },
221
222 /// An [inlined](crate::Grammar::inline) rule cannot be inlined: it is
223 /// the start rule, an external, a rule tree-sitter lexes as a token (by
224 /// the same test as the [word token](Error::WordNotToken)), or it refers
225 /// to itself through inlined rules alone, which tree-sitter would expand
226 /// forever.
227 ///
228 /// Remove it from the inline list, or break the cycle by leaving one of
229 /// the rules in it un-inlined.
230 InvalidInline {
231 /// The rule that cannot be inlined.
232 name: String,
233 },
234
235 /// A [supertype](crate::Grammar::supertype) is an external, or a
236 /// reachable rule tree-sitter cannot use as one: a token with a pattern
237 /// in it, a rule one of whose alternatives is the supertype itself, or a
238 /// rule with an alternative that can produce more than one node. Every
239 /// alternative of a supertype must be a single node, counted through
240 /// hidden and inlined rules, which tree-sitter expands in place.
241 ///
242 /// Make the supertype a choice of single symbols.
243 InvalidSupertype {
244 /// The supertype's name.
245 name: String,
246 },
247
248 /// [`Grammar::sexp`](crate::Grammar::sexp) met a tree node whose name is
249 /// not a rule, external, or alias name of the grammar, so the grammar and
250 /// the parser that built the tree have drifted apart.
251 ///
252 /// Add the rule, or correct the naming function passed to `sexp`.
253 UnknownNode {
254 /// The name the naming function gave the node.
255 name: String,
256 },
257}
258
259impl fmt::Display for Error {
260 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
261 match self {
262 Self::InvalidName { name } => write!(
263 f,
264 "`{name}` is not a valid name: names start with an ASCII letter or `_` \
265 and continue with ASCII letters, digits, or `_`"
266 ),
267 Self::NoRules => {
268 f.write_str("the grammar has no rules; tree-sitter needs at least one")
269 }
270 Self::DuplicateRule { name } => write!(f, "rule `{name}` is defined more than once"),
271 Self::HiddenStart { name } => write!(
272 f,
273 "the start rule `{name}` is hidden; tree-sitter requires the first rule to be visible"
274 ),
275 Self::UndefinedSymbol { symbol, rule } => {
276 write!(f, "`{rule}` refers to undefined symbol `{symbol}`")
277 }
278 // A rule name never contains `: `; an invalid pattern's report
279 // does, after the rule's name.
280 Self::EmptyString { rule } => match rule.split_once(": ") {
281 Some((name, problem)) => {
282 write!(f, "`{name}` contains an invalid pattern: {problem}")
283 }
284 None => write!(f, "`{rule}` contains an empty string or pattern"),
285 },
286 Self::EmptyChoice { rule } => {
287 write!(f, "`{rule}` contains a choice with no alternatives")
288 }
289 Self::SymbolInToken { symbol, rule } => write!(
290 f,
291 "`{rule}` uses symbol `{symbol}` inside a token; token contents must be \
292 strings and patterns"
293 ),
294 Self::MatchesEmpty { rule } => write!(
295 f,
296 "rule `{rule}` can match the empty string where tree-sitter needs a token: \
297 it is referred to by another rule, or it repeats something that can match nothing"
298 ),
299 Self::IndirectRecursion { rule } => write!(
300 f,
301 "rule `{rule}` is part of a cycle of rules that can each be just the next one"
302 ),
303 Self::WordNotToken { name } => write!(
304 f,
305 "word rule `{name}` is not a token: its body must be a string, a pattern, \
306 or a token used nowhere else"
307 ),
308 Self::InvalidExternal { name } => write!(
309 f,
310 "external `{name}` shares its name with a rule that is not a token"
311 ),
312 Self::InvalidInline { name } => write!(f, "rule `{name}` cannot be inlined"),
313 Self::InvalidSupertype { name } => write!(
314 f,
315 "supertype `{name}` must be a rule whose every alternative is a single node"
316 ),
317 Self::UnknownNode { name } => write!(
318 f,
319 "the tree has a node named `{name}`, which is not in the grammar"
320 ),
321 }
322 }
323}
324
325impl core::error::Error for Error {}
326
327#[cfg(test)]
328mod tests {
329 use alloc::string::ToString;
330
331 use super::*;
332
333 #[test]
334 fn test_display_names_the_offending_items() {
335 let e = Error::UndefinedSymbol {
336 symbol: "item".into(),
337 rule: "list".into(),
338 };
339 assert_eq!(e.to_string(), "`list` refers to undefined symbol `item`");
340 let e = Error::MatchesEmpty {
341 rule: "args".into(),
342 };
343 assert!(
344 e.to_string()
345 .starts_with("rule `args` can match the empty string")
346 );
347 assert!(Error::NoRules.to_string().contains("no rules"));
348 }
349
350 #[test]
351 fn test_display_tells_empty_from_invalid_patterns() {
352 let empty = Error::EmptyString { rule: "x".into() };
353 assert_eq!(empty.to_string(), "`x` contains an empty string or pattern");
354 let invalid = Error::EmptyString {
355 rule: "x: unterminated group at byte 0 of `(`".into(),
356 };
357 assert_eq!(
358 invalid.to_string(),
359 "`x` contains an invalid pattern: unterminated group at byte 0 of `(`"
360 );
361 }
362
363 #[test]
364 fn test_every_variant_displays_something() {
365 let s = || String::from("x");
366 let all = [
367 Error::InvalidName { name: s() },
368 Error::NoRules,
369 Error::DuplicateRule { name: s() },
370 Error::HiddenStart { name: s() },
371 Error::UndefinedSymbol {
372 symbol: s(),
373 rule: s(),
374 },
375 Error::EmptyString { rule: s() },
376 Error::EmptyChoice { rule: s() },
377 Error::SymbolInToken {
378 symbol: s(),
379 rule: s(),
380 },
381 Error::MatchesEmpty { rule: s() },
382 Error::IndirectRecursion { rule: s() },
383 Error::WordNotToken { name: s() },
384 Error::InvalidExternal { name: s() },
385 Error::InvalidInline { name: s() },
386 Error::InvalidSupertype { name: s() },
387 Error::UnknownNode { name: s() },
388 ];
389 for e in all {
390 assert!(e.to_string().contains('x') || matches!(e, Error::NoRules));
391 }
392 }
393}