Enum Error

#[non_exhaustive]
pub enum Error<Span> {
    ParsingFailed {
        what: Vec<MacroRuleNode>,
        where_: Span,
    },
    UnexpectedEnd {
        last_token: Option<Span>,
    },
    InvalidProducedAst {
        span: Span,
        expected: Vec<TokenDescription>,
        counter_example: Vec<(TokenDescription, Span)>,
    },
    UnboundMetavariable {
        name: String,
        where_: Span,
    },
    InvalidRepetitionNesting {
        metavariable_name: String,
        decl_span: Span,
        usage_span: Span,
        expected_nesting: Vec<RepetitionQuantifierKind>,
        got_nesting: Vec<RepetitionQuantifierKind>,
    },
}

An error that is generated when checking an incorrect macro.

This enum allows crate users to handle and report errors detected by check_macro.

Everything in this enum in marked as non_exhaustive, in order to partially mitigate future variant additions.

Variants (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.

ParsingFailed

Generated when the macro definition itself doesn’t parse correctly.

The Rust compiler is likely to emit an error anyway. Below is an example of code that triggers this error:

macro_rules! blatant_error {
    () => =>;
    //    |
    //    error: macro rhs must be delimited.
}

This prevents us from doing any analyses.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

what: Vec<MacroRuleNode>

What was expected.

where_: Span

Where it was expected.

UnexpectedEnd

An EOF was reached when it was not expected.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

last_token: Option<Span>

The position the parser was at when it reached EOF.

InvalidProducedAst

The macro may expand to invalid AST.

This variant is very minimal for now. We may add more information to it in the future. Please open an issue if you have opinions on what to add!

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

span: Span

Where the error happens.

expected: Vec<TokenDescription>

What tokens are expected here.

counter_example: Vec<(TokenDescription, Span)>

A possible expansion of the macro that exhibits a parsing error.

The expansion may contain fragments.

UnboundMetavariable

A macro expansion refers to a metavariable that is not defined in the macro match arm.

If you ever hit this error on a macro that works, then please file an issue.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

name: String

The name of the metavariable that was used.

where_: Span

Where it was used.

InvalidRepetitionNesting

A variable is being repeated with a sequence of operator that does not match the one used when the variable was declared.

Example

macro_rules! subtraction {
    ( $( $first:literal $( - $then:literal )* )? ) => {
        $first $( - $then )*
    };
}

subtraction!(101 - 42);

In this example, the repetition nesting of the matched metavariable then is ?*, while the nesting of the metavariable indication then is *.

This variant represents both the case where the amount of repetitions does not match (which is an error) and the case where the repetition operators used do not match (which is allowed, but can lead to confusing errors).

Fields

metavariable_name: String

The name of the metavariable.

decl_span: Span

Where the metavariable was declared.

usage_span: Span

Where the metavariable was used with an incorrect nesting.

expected_nesting: Vec<RepetitionQuantifierKind>

The nesting used when the metavariable was declared.

got_nesting: Vec<RepetitionQuantifierKind>

The nesting encountered when the metavariable was used.

Trait Implementations

impl<Span: Debug> Debug for Error<Span>

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

Formats the value using the given formatter.