aboutsummaryrefslogtreecommitdiff
path: root/syn/src/error.rs
diff options
context:
space:
mode:
Diffstat (limited to 'syn/src/error.rs')
-rw-r--r--syn/src/error.rs357
1 files changed, 357 insertions, 0 deletions
diff --git a/syn/src/error.rs b/syn/src/error.rs
new file mode 100644
index 0000000..146d652
--- /dev/null
+++ b/syn/src/error.rs
@@ -0,0 +1,357 @@
+use std;
+use std::fmt::{self, Debug, Display};
+use std::iter::FromIterator;
+use std::slice;
+use std::vec;
+
+use proc_macro2::{
+ Delimiter, Group, Ident, LexError, Literal, Punct, Spacing, Span, TokenStream, TokenTree,
+};
+#[cfg(feature = "printing")]
+use quote::ToTokens;
+
+#[cfg(feature = "parsing")]
+use crate::buffer::Cursor;
+use crate::thread::ThreadBound;
+
+/// The result of a Syn parser.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// 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.
+///
+/// [`compile_error!`]: https://doc.rust-lang.org/std/macro.compile_error.html
+///
+/// When parsing macro input, the [`parse_macro_input!`] macro handles the
+/// conversion to `compile_error!` automatically.
+///
+/// ```
+/// extern crate proc_macro;
+///
+/// use proc_macro::TokenStream;
+/// use syn::{parse_macro_input, AttributeArgs, ItemFn};
+///
+/// # const IGNORE: &str = stringify! {
+/// #[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);
+///
+/// /* ... */
+/// # TokenStream::new()
+/// }
+/// ```
+///
+/// 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!`.
+///
+/// [`.to_compile_error()`]: Error::to_compile_error
+///
+/// ```
+/// # extern crate proc_macro;
+/// #
+/// # use proc_macro::TokenStream;
+/// # use syn::{parse_macro_input, DeriveInput};
+/// #
+/// # const IGNORE: &str = stringify! {
+/// #[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()
+/// }
+/// #
+/// # mod expand {
+/// # use proc_macro2::TokenStream;
+/// # use syn::{DeriveInput, Result};
+/// #
+/// # pub fn my_derive(input: DeriveInput) -> Result<TokenStream> {
+/// # unimplemented!()
+/// # }
+/// # }
+/// ```
+#[derive(Clone)]
+pub struct Error {
+ messages: Vec<ErrorMessage>,
+}
+
+struct ErrorMessage {
+ // Span is implemented as an index into a thread-local interner to keep the
+ // size small. It is not safe to access from a different thread. We want
+ // errors to be Send and Sync to play nicely with the Failure crate, so pin
+ // the span we're given to its original thread and assume it is
+ // Span::call_site if accessed from any other thread.
+ start_span: ThreadBound<Span>,
+ end_span: ThreadBound<Span>,
+ message: String,
+}
+
+#[cfg(test)]
+struct _Test
+where
+ Error: Send + Sync;
+
+impl Error {
+ /// 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.
+ ///
+ /// [`ParseStream::error`]: crate::parse::ParseBuffer::error
+ ///
+ /// # 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 new<T: Display>(span: Span, message: T) -> Self {
+ Error {
+ messages: vec![ErrorMessage {
+ start_span: ThreadBound::new(span),
+ end_span: ThreadBound::new(span),
+ message: message.to_string(),
+ }],
+ }
+ }
+
+ /// 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`)!
+ #[cfg(feature = "printing")]
+ pub fn new_spanned<T: ToTokens, U: Display>(tokens: T, message: U) -> Self {
+ let mut iter = tokens.into_token_stream().into_iter();
+ let start = iter.next().map_or_else(Span::call_site, |t| t.span());
+ let end = iter.last().map_or(start, |t| t.span());
+ Error {
+ messages: vec![ErrorMessage {
+ start_span: ThreadBound::new(start),
+ end_span: ThreadBound::new(end),
+ message: message.to_string(),
+ }],
+ }
+ }
+
+ /// 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 span(&self) -> Span {
+ let start = match self.messages[0].start_span.get() {
+ Some(span) => *span,
+ None => return Span::call_site(),
+ };
+ let end = match self.messages[0].end_span.get() {
+ Some(span) => *span,
+ None => return Span::call_site(),
+ };
+ start.join(end).unwrap_or(start)
+ }
+
+ /// 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.
+ ///
+ /// [`compile_error!`]: https://doc.rust-lang.org/std/macro.compile_error.html
+ pub fn to_compile_error(&self) -> TokenStream {
+ self.messages
+ .iter()
+ .map(ErrorMessage::to_compile_error)
+ .collect()
+ }
+
+ /// Add another error message to self such that when `to_compile_error()` is
+ /// called, both errors will be emitted together.
+ pub fn combine(&mut self, another: Error) {
+ self.messages.extend(another.messages)
+ }
+}
+
+impl ErrorMessage {
+ fn to_compile_error(&self) -> TokenStream {
+ let start = self
+ .start_span
+ .get()
+ .cloned()
+ .unwrap_or_else(Span::call_site);
+ let end = self.end_span.get().cloned().unwrap_or_else(Span::call_site);
+
+ // compile_error!($message)
+ TokenStream::from_iter(vec![
+ TokenTree::Ident(Ident::new("compile_error", start)),
+ TokenTree::Punct({
+ let mut punct = Punct::new('!', Spacing::Alone);
+ punct.set_span(start);
+ punct
+ }),
+ TokenTree::Group({
+ let mut group = Group::new(Delimiter::Brace, {
+ TokenStream::from_iter(vec![TokenTree::Literal({
+ let mut string = Literal::string(&self.message);
+ string.set_span(end);
+ string
+ })])
+ });
+ group.set_span(end);
+ group
+ }),
+ ])
+ }
+}
+
+#[cfg(feature = "parsing")]
+pub fn new_at<T: Display>(scope: Span, cursor: Cursor, message: T) -> Error {
+ if cursor.eof() {
+ Error::new(scope, format!("unexpected end of input, {}", message))
+ } else {
+ let span = crate::buffer::open_span_of_group(cursor);
+ Error::new(span, message)
+ }
+}
+
+impl Debug for Error {
+ fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+ if self.messages.len() == 1 {
+ formatter
+ .debug_tuple("Error")
+ .field(&self.messages[0])
+ .finish()
+ } else {
+ formatter
+ .debug_tuple("Error")
+ .field(&self.messages)
+ .finish()
+ }
+ }
+}
+
+impl Debug for ErrorMessage {
+ fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+ Debug::fmt(&self.message, formatter)
+ }
+}
+
+impl Display for Error {
+ fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+ formatter.write_str(&self.messages[0].message)
+ }
+}
+
+impl Clone for ErrorMessage {
+ fn clone(&self) -> Self {
+ let start = self
+ .start_span
+ .get()
+ .cloned()
+ .unwrap_or_else(Span::call_site);
+ let end = self.end_span.get().cloned().unwrap_or_else(Span::call_site);
+ ErrorMessage {
+ start_span: ThreadBound::new(start),
+ end_span: ThreadBound::new(end),
+ message: self.message.clone(),
+ }
+ }
+}
+
+impl std::error::Error for Error {
+ fn description(&self) -> &str {
+ "parse error"
+ }
+}
+
+impl From<LexError> for Error {
+ fn from(err: LexError) -> Self {
+ Error::new(Span::call_site(), format!("{:?}", err))
+ }
+}
+
+impl IntoIterator for Error {
+ type Item = Error;
+ type IntoIter = IntoIter;
+
+ fn into_iter(self) -> Self::IntoIter {
+ IntoIter {
+ messages: self.messages.into_iter(),
+ }
+ }
+}
+
+pub struct IntoIter {
+ messages: vec::IntoIter<ErrorMessage>,
+}
+
+impl Iterator for IntoIter {
+ type Item = Error;
+
+ fn next(&mut self) -> Option<Self::Item> {
+ Some(Error {
+ messages: vec![self.messages.next()?],
+ })
+ }
+}
+
+impl<'a> IntoIterator for &'a Error {
+ type Item = Error;
+ type IntoIter = Iter<'a>;
+
+ fn into_iter(self) -> Self::IntoIter {
+ Iter {
+ messages: self.messages.iter(),
+ }
+ }
+}
+
+pub struct Iter<'a> {
+ messages: slice::Iter<'a, ErrorMessage>,
+}
+
+impl<'a> Iterator for Iter<'a> {
+ type Item = Error;
+
+ fn next(&mut self) -> Option<Self::Item> {
+ Some(Error {
+ messages: vec![self.messages.next()?.clone()],
+ })
+ }
+}
generated by cgit v1.2.1 (git 2.18.0) at 2024-05-19 00:37:05 +0000