code_ownership 2.1.4 → 2.2.1

data/ext/cargo-vendor/syn-3.0.9/src/lookahead.rs

@@ -0,0 +1,350 @@
+use crate::buffer::Cursor;
+use crate::error::{self, Error};
+use crate::sealed::lookahead::Sealed;
+use crate::span::IntoSpans;
+use crate::token::{CustomToken, Token};
+use alloc::format;
+use alloc::vec::Vec;
+use core::cell::RefCell;
+use core::fmt::{self, Display};
+use proc_macro2::{Delimiter, Span};
+
+/// Support for checking the next token in a stream to decide how to parse.
+///
+/// An important advantage over [`ParseStream::peek`] is that here we
+/// automatically construct an appropriate error message based on the token
+/// alternatives that get peeked. If you are producing your own error message,
+/// go ahead and use `ParseStream::peek` instead.
+///
+/// Use [`ParseStream::lookahead1`] to construct this object.
+///
+/// [`ParseStream::peek`]: crate::parse::ParseBuffer::peek
+/// [`ParseStream::lookahead1`]: crate::parse::ParseBuffer::lookahead1
+///
+/// Consuming tokens from the source stream after constructing a lookahead
+/// object does not also advance the lookahead object.
+///
+/// # Example
+///
+/// ```
+/// use syn::{ConstParam, Ident, Lifetime, LifetimeParam, Result, Token, TypeParam};
+/// use syn::parse::{Parse, ParseStream};
+///
+/// // A generic parameter, a single one of the comma-separated elements inside
+/// // angle brackets in:
+/// //
+/// //     fn f<T: Clone, 'a, 'b: 'a, const N: usize>() { ... }
+/// //
+/// // On invalid input, lookahead gives us a reasonable error message.
+/// //
+/// //     error: expected one of: identifier, lifetime, `const`
+/// //       |
+/// //     5 |     fn f<!Sized>() {}
+/// //       |          ^
+/// enum GenericParam {
+///     Type(TypeParam),
+///     Lifetime(LifetimeParam),
+///     Const(ConstParam),
+/// }
+///
+/// impl Parse for GenericParam {
+///     fn parse(input: ParseStream) -> Result<Self> {
+///         let lookahead = input.lookahead1();
+///         if lookahead.peek(Ident) {
+///             input.parse().map(GenericParam::Type)
+///         } else if lookahead.peek(Lifetime) {
+///             input.parse().map(GenericParam::Lifetime)
+///         } else if lookahead.peek(Token![const]) {
+///             input.parse().map(GenericParam::Const)
+///         } else {
+///             Err(lookahead.error())
+///         }
+///     }
+/// }
+/// ```
+pub struct Lookahead1<'a> {
+    scope: Span,
+    cursor: Cursor<'a>,
+    comparisons: RefCell<Vec<&'static str>>,
+}
+
+pub(crate) fn new(scope: Span, cursor: Cursor) -> Lookahead1 {
+    Lookahead1 {
+        scope,
+        cursor,
+        comparisons: RefCell::new(Vec::new()),
+    }
+}
+
+fn peek_impl(
+    lookahead: &Lookahead1,
+    peek: fn(Cursor) -> bool,
+    display: fn() -> &'static str,
+) -> bool {
+    if peek(lookahead.cursor) {
+        return true;
+    }
+    lookahead.comparisons.borrow_mut().push(display());
+    false
+}
+
+impl<'a> Lookahead1<'a> {
+    /// Looks at the next token in the parse stream to determine whether it
+    /// matches the requested type of token.
+    ///
+    /// # Syntax
+    ///
+    /// Note that this method does not use turbofish syntax. Pass the peek type
+    /// inside of parentheses.
+    ///
+    /// - `input.peek(Token![struct])`
+    /// - `input.peek(Token![==])`
+    /// - `input.peek(Ident)`&emsp;*(does not accept keywords)*
+    /// - `input.peek(Ident::peek_any)`
+    /// - `input.peek(Lifetime)`
+    /// - `input.peek(token::Brace)`
+    pub fn peek<T: Peek>(&self, token: T) -> bool {
+        let _ = token;
+        peek_impl(self, T::Token::peek, T::Token::display)
+    }
+
+    /// Triggers an error at the current position of the parse stream.
+    ///
+    /// The error message will identify all of the expected token types that
+    /// have been peeked against this lookahead instance.
+    pub fn error(self) -> Error {
+        let mut comparisons = self.comparisons.into_inner();
+        comparisons.retain_mut(|display| {
+            if *display == "`)`" {
+                *display = match self.cursor.scope_delimiter() {
+                    Delimiter::Parenthesis => "`)`",
+                    Delimiter::Brace => "`}`",
+                    Delimiter::Bracket => "`]`",
+                    Delimiter::None => return false,
+                }
+            }
+            true
+        });
+        match comparisons.len() {
+            0 => {
+                if self.cursor.eof() {
+                    Error::new(self.scope, "unexpected end of input")
+                } else {
+                    Error::new(self.cursor.span(), "unexpected token")
+                }
+            }
+            1 => {
+                let message = format!("expected {}", comparisons[0]);
+                error::new_at(self.scope, self.cursor, message)
+            }
+            2 => {
+                let message = format!("expected {} or {}", comparisons[0], comparisons[1]);
+                error::new_at(self.scope, self.cursor, message)
+            }
+            _ => {
+                let message = format!("expected one of: {}", CommaSeparated(&comparisons));
+                error::new_at(self.scope, self.cursor, message)
+            }
+        }
+    }
+}
+
+struct CommaSeparated<'a>(&'a [&'a str]);
+
+impl<'a> Display for CommaSeparated<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let mut first = true;
+        for &s in self.0 {
+            if !first {
+                f.write_str(", ")?;
+            }
+            f.write_str(s)?;
+            first = false;
+        }
+        Ok(())
+    }
+}
+
+/// Types that can be parsed by looking at just one token.
+///
+/// Use [`ParseStream::peek`] to peek one of these types in a parse stream
+/// without consuming it from the stream.
+///
+/// This trait is sealed and cannot be implemented for types outside of Syn.
+///
+/// [`ParseStream::peek`]: crate::parse::ParseBuffer::peek
+pub trait Peek: Sealed {
+    // Not public API.
+    #[doc(hidden)]
+    type Token: Token;
+}
+
+/// Pseudo-token used for peeking the end of a parse stream.
+///
+/// This type is only useful as an argument to one of the following functions:
+///
+/// - [`ParseStream::peek`][crate::parse::ParseBuffer::peek]
+/// - [`ParseStream::peek2`][crate::parse::ParseBuffer::peek2]
+/// - [`ParseStream::peek3`][crate::parse::ParseBuffer::peek3]
+/// - [`Lookahead1::peek`]
+///
+/// The peek will return `true` if there are no remaining tokens after that
+/// point in the parse stream.
+///
+/// # Example
+///
+/// Suppose we are parsing attributes containing core::fmt inspired formatting
+/// arguments:
+///
+/// - `#[fmt("simple example")]`
+/// - `#[fmt("interpolation e{}ample", self.x)]`
+/// - `#[fmt("interpolation e{x}ample")]`
+///
+/// and we want to recognize the cases where no interpolation occurs so that
+/// more efficient code can be generated.
+///
+/// The following implementation uses `input.peek(Token![,]) &&
+/// input.peek2(End)` to recognize the case of a trailing comma without
+/// consuming the comma from the parse stream, because if it isn't a trailing
+/// comma, that same comma needs to be parsed as part of `args`.
+///
+/// ```
+/// use proc_macro2::TokenStream;
+/// use quote::quote;
+/// use syn::parse::{End, Parse, ParseStream, Result};
+/// use syn::{parse_quote, Attribute, LitStr, Token};
+///
+/// struct FormatArgs {
+///     template: LitStr,  // "...{}..."
+///     args: TokenStream, // , self.x
+/// }
+///
+/// impl Parse for FormatArgs {
+///     fn parse(input: ParseStream) -> Result<Self> {
+///         let template: LitStr = input.parse()?;
+///
+///         let args = if input.is_empty()
+///             || input.peek(Token![,]) && input.peek2(End)
+///         {
+///             input.parse::<Option<Token![,]>>()?;
+///             TokenStream::new()
+///         } else {
+///             input.parse()?
+///         };
+///
+///         Ok(FormatArgs {
+///             template,
+///             args,
+///         })
+///     }
+/// }
+///
+/// fn main() -> Result<()> {
+///     let attrs: Vec<Attribute> = parse_quote! {
+///         #[fmt("simple example")]
+///         #[fmt("interpolation e{}ample", self.x)]
+///         #[fmt("interpolation e{x}ample")]
+///     };
+///
+///     for attr in &attrs {
+///         let FormatArgs { template, args } = attr.parse_args()?;
+///         let requires_fmt_machinery =
+///             !args.is_empty() || template.value().contains(['{', '}']);
+///         let out = if requires_fmt_machinery {
+///             quote! {
+///                 ::core::write!(__formatter, #template #args)
+///             }
+///         } else {
+///             quote! {
+///                 __formatter.write_str(#template)
+///             }
+///         };
+///         println!("{}", out);
+///     }
+///     Ok(())
+/// }
+/// ```
+///
+/// Implementing this parsing logic without `peek2(End)` is more clumsy because
+/// we'd need a parse stream actually advanced past the comma before being able
+/// to find out whether there is anything after it. It would look something
+/// like:
+///
+/// ```
+/// # use proc_macro2::TokenStream;
+/// # use syn::parse::{ParseStream, Result};
+/// # use syn::Token;
+/// #
+/// # fn parse(input: ParseStream) -> Result<()> {
+/// use syn::parse::discouraged::Speculative as _;
+///
+/// let ahead = input.fork();
+/// ahead.parse::<Option<Token![,]>>()?;
+/// let args = if ahead.is_empty() {
+///     input.advance_to(&ahead);
+///     TokenStream::new()
+/// } else {
+///     input.parse()?
+/// };
+/// # Ok(())
+/// # }
+/// ```
+///
+/// or:
+///
+/// ```
+/// # use proc_macro2::TokenStream;
+/// # use syn::parse::{ParseStream, Result};
+/// # use syn::Token;
+/// #
+/// # fn parse(input: ParseStream) -> Result<()> {
+/// use quote::ToTokens as _;
+///
+/// let comma: Option<Token![,]> = input.parse()?;
+/// let mut args = TokenStream::new();
+/// if !input.is_empty() {
+///     comma.to_tokens(&mut args);
+///     input.parse::<TokenStream>()?.to_tokens(&mut args);
+/// }
+/// # Ok(())
+/// # }
+/// ```
+pub struct End;
+
+impl Copy for End {}
+
+impl Clone for End {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl Peek for End {
+    type Token = Self;
+}
+
+impl CustomToken for End {
+    fn peek(cursor: Cursor) -> bool {
+        cursor.eof()
+    }
+
+    fn display() -> &'static str {
+        "`)`" // Lookahead1 error message will fill in the expected close delimiter
+    }
+}
+
+impl<F: Copy + FnOnce(TokenMarker) -> T, T: Token> Peek for F {
+    type Token = T;
+}
+
+pub enum TokenMarker {}
+
+impl<S> IntoSpans<S> for TokenMarker {
+    fn into_spans(self) -> S {
+        match self {}
+    }
+}
+
+impl<F: Copy + FnOnce(TokenMarker) -> T, T: Token> Sealed for F {}
+
+impl Sealed for End {}

data/ext/cargo-vendor/syn-3.0.9/src/mac.rs

@@ -0,0 +1,225 @@
+#[cfg(feature = "parsing")]
+use crate::error::Result;
+#[cfg(feature = "parsing")]
+use crate::parse::{Parse, ParseStream, Parser};
+use crate::path::Path;
+use crate::token::{Brace, Bracket, Paren};
+use proc_macro2::extra::DelimSpan;
+#[cfg(feature = "parsing")]
+use proc_macro2::Delimiter;
+use proc_macro2::TokenStream;
+#[cfg(feature = "parsing")]
+use proc_macro2::TokenTree;
+
+ast_struct! {
+    /// A macro invocation: `println!("{}", mac)`.
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "full", feature = "derive"))))]
+    pub struct Macro {
+        pub path: Path,
+        pub bang_token: Token![!],
+        pub delimiter: MacroDelimiter,
+        pub tokens: TokenStream,
+    }
+}
+
+ast_enum! {
+    /// A grouping token that surrounds a macro body: `m!(...)` or `m!{...}` or `m![...]`.
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "full", feature = "derive"))))]
+    pub enum MacroDelimiter {
+        Paren(Paren),
+        Brace(Brace),
+        Bracket(Bracket),
+    }
+}
+
+impl MacroDelimiter {
+    pub fn span(&self) -> &DelimSpan {
+        match self {
+            MacroDelimiter::Paren(token) => &token.span,
+            MacroDelimiter::Brace(token) => &token.span,
+            MacroDelimiter::Bracket(token) => &token.span,
+        }
+    }
+
+    #[cfg(all(feature = "full", any(feature = "parsing", feature = "printing")))]
+    pub(crate) fn is_brace(&self) -> bool {
+        match self {
+            MacroDelimiter::Brace(_) => true,
+            MacroDelimiter::Paren(_) | MacroDelimiter::Bracket(_) => false,
+        }
+    }
+}
+
+impl Macro {
+    /// Parse the tokens within the macro invocation's delimiters into a syntax
+    /// tree.
+    ///
+    /// This is equivalent to `syn::parse2::<T>(mac.tokens)` except that it
+    /// produces a more useful span when `tokens` is empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use syn::{parse_quote, Expr, ExprLit, Ident, Lit, LitStr, Macro, Token};
+    /// use syn::ext::IdentExt;
+    /// use syn::parse::{Error, Parse, ParseStream, Result};
+    /// use syn::punctuated::Punctuated;
+    ///
+    /// // The arguments expected by libcore's format_args macro, and as a
+    /// // result most other formatting and printing macros like println.
+    /// //
+    /// //     println!("{} is {number:.prec$}", "x", prec=5, number=0.01)
+    /// struct FormatArgs {
+    ///     format_string: Expr,
+    ///     positional_args: Vec<Expr>,
+    ///     named_args: Vec<(Ident, Expr)>,
+    /// }
+    ///
+    /// impl Parse for FormatArgs {
+    ///     fn parse(input: ParseStream) -> Result<Self> {
+    ///         let format_string: Expr;
+    ///         let mut positional_args = Vec::new();
+    ///         let mut named_args = Vec::new();
+    ///
+    ///         format_string = input.parse()?;
+    ///         while !input.is_empty() {
+    ///             input.parse::<Token![,]>()?;
+    ///             if input.is_empty() {
+    ///                 break;
+    ///             }
+    ///             if input.peek(Ident::peek_any) && input.peek2(Token![=]) {
+    ///                 while !input.is_empty() {
+    ///                     let name: Ident = input.call(Ident::parse_any)?;
+    ///                     input.parse::<Token![=]>()?;
+    ///                     let value: Expr = input.parse()?;
+    ///                     named_args.push((name, value));
+    ///                     if input.is_empty() {
+    ///                         break;
+    ///                     }
+    ///                     input.parse::<Token![,]>()?;
+    ///                 }
+    ///                 break;
+    ///             }
+    ///             positional_args.push(input.parse()?);
+    ///         }
+    ///
+    ///         Ok(FormatArgs {
+    ///             format_string,
+    ///             positional_args,
+    ///             named_args,
+    ///         })
+    ///     }
+    /// }
+    ///
+    /// // Extract the first argument, the format string literal, from an
+    /// // invocation of a formatting or printing macro.
+    /// fn get_format_string(m: &Macro) -> Result<LitStr> {
+    ///     let args: FormatArgs = m.parse_body()?;
+    ///     match args.format_string {
+    ///         Expr::Lit(ExprLit { lit: Lit::Str(lit), .. }) => Ok(lit),
+    ///         other => {
+    ///             // First argument was not a string literal expression.
+    ///             // Maybe something like: println!(concat!(...), ...)
+    ///             Err(Error::new_spanned(other, "format string must be a string literal"))
+    ///         }
+    ///     }
+    /// }
+    ///
+    /// fn main() {
+    ///     let invocation = parse_quote! {
+    ///         println!("{:?}", Instant::now())
+    ///     };
+    ///     let lit = get_format_string(&invocation).unwrap();
+    ///     assert_eq!(lit.value(), "{:?}");
+    /// }
+    /// ```
+    #[cfg(feature = "parsing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
+    pub fn parse_body<T: Parse>(&self) -> Result<T> {
+        self.parse_body_with(T::parse)
+    }
+
+    /// Parse the tokens within the macro invocation's delimiters using the
+    /// given parser.
+    #[cfg(feature = "parsing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
+    pub fn parse_body_with<F: Parser>(&self, parser: F) -> Result<F::Output> {
+        let scope = self.delimiter.span().close();
+        crate::parse::parse_scoped(parser, scope, self.tokens.clone())
+    }
+}
+
+#[cfg(feature = "parsing")]
+pub(crate) fn parse_delimiter(input: ParseStream) -> Result<(MacroDelimiter, TokenStream)> {
+    input.step(|cursor| {
+        if let Some((TokenTree::Group(g), rest)) = cursor.token_tree() {
+            let span = g.delim_span();
+            let delimiter = match g.delimiter() {
+                Delimiter::Parenthesis => MacroDelimiter::Paren(Paren(span)),
+                Delimiter::Brace => MacroDelimiter::Brace(Brace(span)),
+                Delimiter::Bracket => MacroDelimiter::Bracket(Bracket(span)),
+                Delimiter::None => {
+                    return Err(cursor.error("expected delimiter"));
+                }
+            };
+            Ok(((delimiter, g.stream()), rest))
+        } else {
+            Err(cursor.error("expected delimiter"))
+        }
+    })
+}
+
+#[cfg(feature = "parsing")]
+pub(crate) mod parsing {
+    use crate::error::Result;
+    use crate::mac::{parse_delimiter, Macro};
+    use crate::parse::{Parse, ParseStream};
+    use crate::path::Path;
+
+    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
+    impl Parse for Macro {
+        fn parse(input: ParseStream) -> Result<Self> {
+            let tokens;
+            Ok(Macro {
+                path: input.call(Path::parse_mod_style)?,
+                bang_token: input.parse()?,
+                delimiter: {
+                    let (delimiter, content) = parse_delimiter(input)?;
+                    tokens = content;
+                    delimiter
+                },
+                tokens,
+            })
+        }
+    }
+}
+
+#[cfg(feature = "printing")]
+mod printing {
+    use crate::mac::{Macro, MacroDelimiter};
+    use crate::path;
+    use crate::path::printing::PathStyle;
+    use crate::token;
+    use proc_macro2::{Delimiter, TokenStream};
+    use quote::ToTokens;
+
+    impl MacroDelimiter {
+        pub(crate) fn surround(&self, tokens: &mut TokenStream, inner: TokenStream) {
+            let (delim, span) = match self {
+                MacroDelimiter::Paren(paren) => (Delimiter::Parenthesis, paren.span),
+                MacroDelimiter::Brace(brace) => (Delimiter::Brace, brace.span),
+                MacroDelimiter::Bracket(bracket) => (Delimiter::Bracket, bracket.span),
+            };
+            token::printing::delim(delim, span.join(), tokens, inner);
+        }
+    }
+
+    #[cfg_attr(docsrs, doc(cfg(feature = "printing")))]
+    impl ToTokens for Macro {
+        fn to_tokens(&self, tokens: &mut TokenStream) {
+            path::printing::print_path(tokens, &self.path, PathStyle::Mod);
+            self.bang_token.to_tokens(tokens);
+            self.delimiter.surround(tokens, self.tokens.clone());
+        }
+    }
+}