Struct Error

pub struct Error { /* private fields */ }

Error returned when a Syn parser cannot parse the input tokens.

Error reporting in proc macros

The correct way to report errors back to the compiler from a procedural macro is by emitting an appropriately spanned invocation of compile_error! in the generated code. This produces a better diagnostic message than simply panicking the macro.

When parsing macro input, the parse_macro_input! macro handles the conversion to compile_error! automatically.

use proc_macro::TokenStream;
use syn::parse::{Parse, ParseStream, Result};
use syn::{parse_macro_input, ItemFn};

#[proc_macro_attribute]
pub fn my_attr(args: TokenStream, input: TokenStream) -> TokenStream {
    let args = parse_macro_input!(args as MyAttrArgs);
    let input = parse_macro_input!(input as ItemFn);

    /* ... */
}

struct MyAttrArgs {
    ...
}

impl Parse for MyAttrArgs {
    fn parse(input: ParseStream) -> Result<Self> {
        ...
    }
}

For errors that arise later than the initial parsing stage, the .to_compile_error() or .into_compile_error() methods can be used to perform an explicit conversion to compile_error!.

#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

    // fn(DeriveInput) -> syn::Result<proc_macro2::TokenStream>
    expand::my_derive(input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

Implementations

impl Error

pub fn new<T: Display>(span: Span, message: T) -> Self

Usually the ParseStream::error method will be used instead, which automatically uses the correct span from the current position of the parse stream.

Use Error::new when the error needs to be triggered on some span other than where the parse stream is currently positioned.

Example

use syn::{Error, Ident, LitStr, Result, Token};
use syn::parse::ParseStream;

// Parses input that looks like `name = "string"` where the key must be
// the identifier `name` and the value may be any string literal.
// Returns the string literal.
fn parse_name(input: ParseStream) -> Result<LitStr> {
    let name_token: Ident = input.parse()?;
    if name_token != "name" {
        // Trigger an error not on the current position of the stream,
        // but on the position of the unexpected identifier.
        return Err(Error::new(name_token.span(), "expected `name`"));
    }
    input.parse::<Token![=]>()?;
    let s: LitStr = input.parse()?;
    Ok(s)
}

pub fn span(&self) -> Span

The source location of the error.

Spans are not thread-safe so this function returns Span::call_site() if called from a different thread than the one on which the Error was originally created.

pub fn to_compile_error(&self) -> TokenStream

Render the error as an invocation of compile_error!.

The parse_macro_input! macro provides a convenient way to invoke this method correctly in a procedural macro.

pub fn into_compile_error(self) -> TokenStream

Render the error as an invocation of compile_error!.

Example

use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput, Error};

#[proc_macro_derive(MyTrait)]
pub fn derive_my_trait(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    my_trait::expand(input)
        .unwrap_or_else(Error::into_compile_error)
        .into()
}

mod my_trait {
    use proc_macro2::TokenStream;
    use syn::{DeriveInput, Result};

    pub(crate) fn expand(input: DeriveInput) -> Result<TokenStream> {
        /* ... */
    }
}

pub fn combine(&mut self, another: Error)

Add another error message to self such that when to_compile_error() is called, both errors will be emitted together.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

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

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

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.

impl Extend<Error> for Error

fn extend<T: IntoIterator<Item = Error>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<LexError> for Error

fn from(err: LexError) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Error

type Item = Error

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Error

type Item = Error

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.