Skip to main content

Error

Enum Error 

Source
#[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:

  1. names (the grammar’s, then each rule’s, then each external’s), the start rule, and duplicate rules;
  2. 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;
  3. the names in word, conflicts, inline, and supertypes resolve;
  4. 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;
  5. 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
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

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.

Fields

§name: String

The offending name.

§

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.

Fields

§name: String

The name defined more than once.

§

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.

Fields

§name: String

The start rule’s name.

§

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.

Fields

§symbol: String

The undefined name.

§rule: String

Where it was referred to.

§

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

§rule: String

Where the empty string or pattern was found, and for an invalid pattern, what is wrong with it.

§

EmptyChoice

A Rule::choice has no alternatives, so it can never match. Tree-sitter does not report this; it is always a mistake.

Fields

§rule: String

Where the empty choice was found.

§

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

§symbol: String

The symbol found inside the token.

§rule: String

The rule containing the token, or extras.

§

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.

Fields

§rule: String

The rule that can match nothing, or that contains the repetition.

§

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.

Fields

§rule: String

A rule on the cycle.

§

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.

Fields

§name: String

The word rule’s name.

§

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.

Fields

§name: String

The external’s name.

§

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.

Fields

§name: String

The rule that cannot be 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.

Fields

§name: String

The supertype’s name.

§

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.

Fields

§name: String

The name the naming function gave the node.

Trait Implementations§

Source§

impl Clone for Error

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Error

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Display for Error

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Eq for Error

Source§

impl Error for Error

1.30.0 · Source§

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more
Source§

impl PartialEq for Error

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Error

Auto Trait Implementations§

§

impl Freeze for Error

§

impl RefUnwindSafe for Error

§

impl Send for Error

§

impl Sync for Error

§

impl Unpin for Error

§

impl UnsafeUnpin for Error

§

impl UnwindSafe for Error

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.