#[non_exhaustive]pub enum Error {
Show 15 variants
InvalidName {
name: String,
},
NoRules,
DuplicateRule {
name: String,
},
HiddenStart {
name: String,
},
UndefinedSymbol {
symbol: String,
rule: String,
},
EmptyString {
rule: String,
},
EmptyChoice {
rule: String,
},
SymbolInToken {
symbol: String,
rule: String,
},
MatchesEmpty {
rule: String,
},
IndirectRecursion {
rule: String,
},
WordNotToken {
name: String,
},
InvalidExternal {
name: String,
},
InvalidInline {
name: String,
},
InvalidSupertype {
name: String,
},
UnknownNode {
name: String,
},
}Expand description
Why Grammar refused to emit a grammar, or to render a
tree as an S-expression.
Emitting validates the whole grammar first and reports the first problem, checking in this order:
- names (the grammar’s, then each rule’s, then each external’s), the start rule, and duplicate rules;
- every rule body in definition order, then the extras: symbols resolve and are not inside tokens, patterns and choices are not empty, patterns are regular expressions JavaScript accepts, field and alias names are identifiers;
- the names in
word,conflicts,inline, andsupertypesresolve; - the rules reachable from the start rule and the extras: no cycle of rules that can each be just the next; then, in definition order, no empty strings, only patterns tree-sitter’s regular expression parser accepts, and nothing that can match the empty string where tree-sitter needs a token; then the patterns in the extras;
- the word token, externals sharing a rule’s name, inlined rules, and supertypes.
Every variant names a mistake that would otherwise surface later, as an
error from tree-sitter generate — in two cases as a crash or a hang — or
as a grammar.js that does not load. Rules that cannot be reached from the
start rule or the extras are checked only as far as grammar.js itself
evaluates them (step 2), because tree-sitter drops them.
What validation does not do is build parse tables. The problems
tree-sitter finds while building them — conflicts, and extras made of
rules whose end it cannot tell — are reported by tree-sitter generate.
Where a variant has a rule field, it holds the name of the rule the
problem was found in, or — for a problem outside any rule — the name of the
grammar field it was found in: extras, word, conflicts, inline, or
supertypes.
§Examples
use treesitter_lang::{Error, Grammar, Rule};
let grammar = Grammar::new("demo").rule("source_file", Rule::symbol("item"));
match grammar.to_js() {
Err(Error::UndefinedSymbol { symbol, rule }) => {
assert_eq!(symbol, "item");
assert_eq!(rule, "source_file");
}
other => panic!("unexpected {other:?}"),
}Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
InvalidName
The grammar name, a rule name, an external, a field name, or an alias
name is not an identifier. Names must start with an ASCII letter or
_ and continue with ASCII letters, digits, or _; tree-sitter turns
them into JavaScript property names and C identifiers. A rule or an
external may not be called __proto__, which JavaScript reserves.
Rename it. Tree-sitter convention is snake_case.
NoRules
The grammar has no rules. Tree-sitter needs at least one: the first rule is the start rule.
DuplicateRule
Two rules share a name. The second definition would silently replace
the first in grammar.js, so it is refused instead.
Rename one of them, or merge them with Rule::choice.
HiddenStart
The first rule — the start rule, the root of every tree — is hidden
(its name starts with _). Tree-sitter requires it to be visible.
Rename it, or add a visible rule in front of it.
UndefinedSymbol
A symbol names neither a rule nor an external token.
Usually a typo; otherwise define the rule with
Grammar::rule or declare it with
Grammar::external.
EmptyString
A string literal in a reachable rule is empty — tree-sitter refuses these outside tokens and in most places inside them, and the rest can only match nothing — or a pattern is empty or is not a regular expression tree-sitter can use.
A pattern must be a regular expression literal JavaScript accepts,
wherever it is, because grammar.js evaluates every rule; and, in a
rule reachable from the start rule or in an extra, one tree-sitter’s
own regular expression parser accepts. The accepted forms are listed
in
docs/API.md.
For an empty string or pattern, rule is the name of the rule (or
extras). For an invalid pattern — non-empty — rule is that name,
then : , then what is wrong, the byte offset in the pattern where it
is, and the start of the pattern, as in
"number: unterminated character class at byte 0 of `[0-9`".
Rule names never contain : , so the part before the first : is
always the rule’s name. (The error type is frozen at 1.0; this
variant, the one for a pattern that cannot be written as a regular
expression literal, carries the report.)
Use Rule::blank or
Rule::optional to express “nothing”; fix
an invalid pattern as the report says.
Fields
EmptyChoice
A Rule::choice has no alternatives, so it can
never match. Tree-sitter does not report this; it is always a mistake.
SymbolInToken
A symbol appears inside Rule::token,
Rule::immediate, or an extra that is not a
lone symbol — all of which are lexed as one token, so their contents
may only be strings, patterns, and the combinators over them, not
references to other rules.
Inline the referenced rule’s strings and patterns into the token, or make the extra a symbol naming a rule.
Fields
MatchesEmpty
Something tree-sitter needs to match at least one token can match
the empty string: a rule that another reachable rule (or an extra)
refers to, or the contents of a Rule::repeat
or Rule::repeat1 in a reachable rule. Only a
rule nothing refers to — in practice the start rule — may match
nothing.
Move the optionality outward: make the rule (or the repeated part)
match at least one token, and wrap its uses in
Rule::optional, or use
Rule::repeat1 instead of
Rule::repeat.
IndirectRecursion
Reachable rules form a cycle in which each can be just the next —
a can be b alone and b can be a alone — so one piece of text
would have endlessly many trees. Tree-sitter refuses this as an
“indirectly recursive rule”. A rule can be another alone when that
rule is one of its alternatives, through
choice, optional,
prec, field, and
alias. Also reported: a hidden rule with an
alternative that is itself under a non-zero prec, prec.left, or
prec.right, on which tree-sitter loops forever.
Break the cycle: usually one of the rules should require more than the other (a delimiter, an operator), or the two should be one rule.
WordNotToken
The word rule is not a token. Tree-sitter
requires it to be a single terminal: not the start rule, its body a
string, a pattern, Rule::token, or
Rule::immediate — with no
prec, field, or
alias around it — and that token used nowhere
else in the reachable rules (tree-sitter would merge the two uses,
leaving the rule a non-terminal). A hidden rule whose token is only a
string literal is not a token either: tree-sitter treats it as that
anonymous string. Or the word may be an external.
Refer to the word rule by symbol wherever its token is needed.
InvalidExternal
An external shares its name with a rule that is not a token. A rule may share an external’s name only as the fallback lexer for it, so it must meet the same conditions as the word token.
Rename one of them, or make the rule a token.
InvalidInline
An inlined rule cannot be inlined: it is the start rule, an external, a rule tree-sitter lexes as a token (by the same test as the word token), or it refers to itself through inlined rules alone, which tree-sitter would expand forever.
Remove it from the inline list, or break the cycle by leaving one of the rules in it un-inlined.
InvalidSupertype
A supertype is an external, or a reachable rule tree-sitter cannot use as one: a token with a pattern in it, a rule one of whose alternatives is the supertype itself, or a rule with an alternative that can produce more than one node. Every alternative of a supertype must be a single node, counted through hidden and inlined rules, which tree-sitter expands in place.
Make the supertype a choice of single symbols.
UnknownNode
Grammar::sexp met a tree node whose name is
not a rule, external, or alias name of the grammar, so the grammar and
the parser that built the tree have drifted apart.
Add the rule, or correct the naming function passed to sexp.
Trait Implementations§
impl Eq for Error
Source§impl Error for Error
impl Error for Error
1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()