Skip to main content

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}