Struct syn::Error [−][src]
pub struct Error { /* fields omitted */ }Expand description
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_macro_input, AttributeArgs, ItemFn};
#[proc_macro_attribute]
pub fn my_attr(args: TokenStream, input: TokenStream) -> TokenStream {
let args = parse_macro_input!(args as AttributeArgs);
let input = parse_macro_input!(input as ItemFn);
/* ... */
}For errors that arise later than the initial parsing stage, the
.to_compile_error() method 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(|err| err.to_compile_error())
.into()
}Implementations
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)
}Creates an error with the specified message spanning the given syntax tree node.
Unlike the Error::new constructor, this constructor takes an argument
tokens which is a syntax tree node. This allows the resulting Error
to attempt to span all tokens inside of tokens. While you would
typically be able to use the Spanned trait with the above Error::new
constructor, implementation limitations today mean that
Error::new_spanned may provide a higher-quality error message on
stable Rust.
When in doubt it’s recommended to stick to Error::new (or
ParseStream::error)!
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.
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.
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> {
/* ... */
}
}Trait Implementations
Extends a collection with the contents of an iterator. Read more
extend_one)Extends a collection with exactly one element.
extend_one)Reserves capacity in a collection for the given number of additional elements. Read more
Auto Trait Implementations
impl RefUnwindSafe for Error
impl UnwindSafe for Error
Blanket Implementations
Mutably borrows from an owned value. Read more