rust/syn/meta.rs

// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Facility for interpreting structured content inside of an `Attribute`.

use crate::error::{Error, Result};
use crate::ext::IdentExt as _;
use crate::lit::Lit;
use crate::parse::{ParseStream, Parser};
use crate::path::{Path, PathSegment};
use crate::punctuated::Punctuated;
use proc_macro2::Ident;
use std::fmt::Display;

/// Make a parser that is usable with `parse_macro_input!` in a
/// `#[proc_macro_attribute]` macro.
///
/// *Warning:* When parsing attribute args **other than** the
/// `proc_macro::TokenStream` input of a `proc_macro_attribute`, you do **not**
/// need this function. In several cases your callers will get worse error
/// messages if you use this function, because the surrounding delimiter's span
/// is concealed from attribute macros by rustc. Use
/// [`Attribute::parse_nested_meta`] instead.
///
/// [`Attribute::parse_nested_meta`]: crate::Attribute::parse_nested_meta
///
/// # Example
///
/// This example implements an attribute macro whose invocations look like this:
///
/// ```
/// # const IGNORE: &str = stringify! {
/// #[tea(kind = "EarlGrey", hot)]
/// struct Picard {...}
/// # };
/// ```
///
/// The "parameters" supported by the attribute are:
///
/// - `kind = "..."`
/// - `hot`
/// - `with(sugar, milk, ...)`, a comma-separated list of ingredients
///
/// ```
/// # extern crate proc_macro;
/// #
/// use proc_macro::TokenStream;
/// use syn::{parse_macro_input, LitStr, Path};
///
/// # const IGNORE: &str = stringify! {
/// #[proc_macro_attribute]
/// # };
/// pub fn tea(args: TokenStream, input: TokenStream) -> TokenStream {
///     let mut kind: Option<LitStr> = None;
///     let mut hot: bool = false;
///     let mut with: Vec<Path> = Vec::new();
///     let tea_parser = syn::meta::parser(|meta| {
///         if meta.path.is_ident("kind") {
///             kind = Some(meta.value()?.parse()?);
///             Ok(())
///         } else if meta.path.is_ident("hot") {
///             hot = true;
///             Ok(())
///         } else if meta.path.is_ident("with") {
///             meta.parse_nested_meta(|meta| {
///                 with.push(meta.path);
///                 Ok(())
///             })
///         } else {
///             Err(meta.error("unsupported tea property"))
///         }
///     });
///
///     parse_macro_input!(args with tea_parser);
///     eprintln!("kind={kind:?} hot={hot} with={with:?}");
///
///     /* ... */
/// #   TokenStream::new()
/// }
/// ```
///
/// The `syn::meta` library will take care of dealing with the commas including
/// trailing commas, and producing sensible error messages on unexpected input.
///
/// ```console
/// error: expected `,`
///  --> src/main.rs:3:37
///   |
/// 3 | #[tea(kind = "EarlGrey", with(sugar = "lol", milk))]
///   |                                     ^
/// ```
///
/// # Example
///
/// Same as above but we factor out most of the logic into a separate function.
///
/// ```
/// # extern crate proc_macro;
/// #
/// use proc_macro::TokenStream;
/// use syn::meta::ParseNestedMeta;
/// use syn::parse::{Parser, Result};
/// use syn::{parse_macro_input, LitStr, Path};
///
/// # const IGNORE: &str = stringify! {
/// #[proc_macro_attribute]
/// # };
/// pub fn tea(args: TokenStream, input: TokenStream) -> TokenStream {
///     let mut attrs = TeaAttributes::default();
///     let tea_parser = syn::meta::parser(|meta| attrs.parse(meta));
///     parse_macro_input!(args with tea_parser);
///
///     /* ... */
/// #   TokenStream::new()
/// }
///
/// #[derive(Default)]
/// struct TeaAttributes {
///     kind: Option<LitStr>,
///     hot: bool,
///     with: Vec<Path>,
/// }
///
/// impl TeaAttributes {
///     fn parse(&mut self, meta: ParseNestedMeta) -> Result<()> {
///         if meta.path.is_ident("kind") {
///             self.kind = Some(meta.value()?.parse()?);
///             Ok(())
///         } else /* just like in last example */
/// #           { unimplemented!() }
///
///     }
/// }
/// ```
pub fn parser(logic: impl FnMut(ParseNestedMeta) -> Result<()>) -> impl Parser<Output = ()> {
    |input: ParseStream| {
        if input.is_empty() {
            Ok(())
        } else {
            parse_nested_meta(input, logic)
        }
    }
}

/// Context for parsing a single property in the conventional syntax for
/// structured attributes.
///
/// # Examples
///
/// Refer to usage examples on the following two entry-points:
///
/// - [`Attribute::parse_nested_meta`] if you have an entire `Attribute` to
///   parse. Always use this if possible. Generally this is able to produce
///   better error messages because `Attribute` holds span information for all
///   of the delimiters therein.
///
/// - [`syn::meta::parser`] if you are implementing a `proc_macro_attribute`
///   macro and parsing the arguments to the attribute macro, i.e. the ones
///   written in the same attribute that dispatched the macro invocation. Rustc
///   does not pass span information for the surrounding delimiters into the
///   attribute macro invocation in this situation, so error messages might be
///   less precise.
///
/// [`Attribute::parse_nested_meta`]: crate::Attribute::parse_nested_meta
/// [`syn::meta::parser`]: crate::meta::parser
#[non_exhaustive]
pub struct ParseNestedMeta<'a> {
    pub path: Path,
    pub input: ParseStream<'a>,
}

impl<'a> ParseNestedMeta<'a> {
    /// Used when parsing `key = "value"` syntax.
    ///
    /// All it does is advance `meta.input` past the `=` sign in the input. You
    /// could accomplish the same effect by writing
    /// `meta.parse::<Token![=]>()?`, so at most it is a minor convenience to
    /// use `meta.value()?`.
    ///
    /// # Example
    ///
    /// ```
    /// use syn::{parse_quote, Attribute, LitStr};
    ///
    /// let attr: Attribute = parse_quote! {
    ///     #[tea(kind = "EarlGrey")]
    /// };
    ///                                          // conceptually:
    /// if attr.path().is_ident("tea") {         // this parses the `tea`
    ///     attr.parse_nested_meta(|meta| {      // this parses the `(`
    ///         if meta.path.is_ident("kind") {  // this parses the `kind`
    ///             let value = meta.value()?;   // this parses the `=`
    ///             let s: LitStr = value.parse()?;  // this parses `"EarlGrey"`
    ///             if s.value() == "EarlGrey" {
    ///                 // ...
    ///             }
    ///             Ok(())
    ///         } else {
    ///             Err(meta.error("unsupported attribute"))
    ///         }
    ///     })?;
    /// }
    /// # anyhow::Ok(())
    /// ```
    pub fn value(&self) -> Result<ParseStream<'a>> {
        self.input.parse::<Token![=]>()?;
        Ok(self.input)
    }

    /// Used when parsing `list(...)` syntax **if** the content inside the
    /// nested parentheses is also expected to conform to Rust's structured
    /// attribute convention.
    ///
    /// # Example
    ///
    /// ```
    /// use syn::{parse_quote, Attribute};
    ///
    /// let attr: Attribute = parse_quote! {
    ///     #[tea(with(sugar, milk))]
    /// };
    ///
    /// if attr.path().is_ident("tea") {
    ///     attr.parse_nested_meta(|meta| {
    ///         if meta.path.is_ident("with") {
    ///             meta.parse_nested_meta(|meta| {  // <---
    ///                 if meta.path.is_ident("sugar") {
    ///                     // Here we can go even deeper if needed.
    ///                     Ok(())
    ///                 } else if meta.path.is_ident("milk") {
    ///                     Ok(())
    ///                 } else {
    ///                     Err(meta.error("unsupported ingredient"))
    ///                 }
    ///             })
    ///         } else {
    ///             Err(meta.error("unsupported tea property"))
    ///         }
    ///     })?;
    /// }
    /// # anyhow::Ok(())
    /// ```
    ///
    /// # Counterexample
    ///
    /// If you don't need `parse_nested_meta`'s help in parsing the content
    /// written within the nested parentheses, keep in mind that you can always
    /// just parse it yourself from the exposed ParseStream. Rust syntax permits
    /// arbitrary tokens within those parentheses so for the crazier stuff,
    /// `parse_nested_meta` is not what you want.
    ///
    /// ```
    /// use syn::{parenthesized, parse_quote, Attribute, LitInt};
    ///
    /// let attr: Attribute = parse_quote! {
    ///     #[repr(align(32))]
    /// };
    ///
    /// let mut align: Option<LitInt> = None;
    /// if attr.path().is_ident("repr") {
    ///     attr.parse_nested_meta(|meta| {
    ///         if meta.path.is_ident("align") {
    ///             let content;
    ///             parenthesized!(content in meta.input);
    ///             align = Some(content.parse()?);
    ///             Ok(())
    ///         } else {
    ///             Err(meta.error("unsupported repr"))
    ///         }
    ///     })?;
    /// }
    /// # anyhow::Ok(())
    /// ```
    pub fn parse_nested_meta(
        &self,
        logic: impl FnMut(ParseNestedMeta) -> Result<()>,
    ) -> Result<()> {
        let content;
        parenthesized!(content in self.input);
        parse_nested_meta(&content, logic)
    }

    /// Report that the attribute's content did not conform to expectations.
    ///
    /// The span of the resulting error will cover `meta.path` *and* everything
    /// that has been parsed so far since it.
    ///
    /// There are 2 ways you might call this. First, if `meta.path` is not
    /// something you recognize:
    ///
    /// ```
    /// # use syn::Attribute;
    /// #
    /// # fn example(attr: &Attribute) -> syn::Result<()> {
    /// attr.parse_nested_meta(|meta| {
    ///     if meta.path.is_ident("kind") {
    ///         // ...
    ///         Ok(())
    ///     } else {
    ///         Err(meta.error("unsupported tea property"))
    ///     }
    /// })?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// In this case, it behaves exactly like
    /// `syn::Error::new_spanned(&meta.path, "message...")`.
    ///
    /// ```console
    /// error: unsupported tea property
    ///  --> src/main.rs:3:26
    ///   |
    /// 3 | #[tea(kind = "EarlGrey", wat = "foo")]
    ///   |                          ^^^
    /// ```
    ///
    /// More usefully, the second place is if you've already parsed a value but
    /// have decided not to accept the value:
    ///
    /// ```
    /// # use syn::Attribute;
    /// #
    /// # fn example(attr: &Attribute) -> syn::Result<()> {
    /// use syn::Expr;
    ///
    /// attr.parse_nested_meta(|meta| {
    ///     if meta.path.is_ident("kind") {
    ///         let expr: Expr = meta.value()?.parse()?;
    ///         match expr {
    ///             Expr::Lit(expr) => /* ... */
    /// #               unimplemented!(),
    ///             Expr::Path(expr) => /* ... */
    /// #               unimplemented!(),
    ///             Expr::Macro(expr) => /* ... */
    /// #               unimplemented!(),
    ///             _ => Err(meta.error("tea kind must be a string literal, path, or macro")),
    ///         }
    ///     } else /* as above */
    /// #       { unimplemented!() }
    ///
    /// })?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// ```console
    /// error: tea kind must be a string literal, path, or macro
    ///  --> src/main.rs:3:7
    ///   |
    /// 3 | #[tea(kind = async { replicator.await })]
    ///   |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    /// ```
    ///
    /// Often you may want to use `syn::Error::new_spanned` even in this
    /// situation. In the above code, that would be:
    ///
    /// ```
    /// # use syn::{Error, Expr};
    /// #
    /// # fn example(expr: Expr) -> syn::Result<()> {
    ///     match expr {
    ///         Expr::Lit(expr) => /* ... */
    /// #           unimplemented!(),
    ///         Expr::Path(expr) => /* ... */
    /// #           unimplemented!(),
    ///         Expr::Macro(expr) => /* ... */
    /// #           unimplemented!(),
    ///         _ => Err(Error::new_spanned(expr, "unsupported expression type for `kind`")),
    ///     }
    /// # }
    /// ```
    ///
    /// ```console
    /// error: unsupported expression type for `kind`
    ///  --> src/main.rs:3:14
    ///   |
    /// 3 | #[tea(kind = async { replicator.await })]
    ///   |              ^^^^^^^^^^^^^^^^^^^^^^^^^^
    /// ```
    pub fn error(&self, msg: impl Display) -> Error {
        let start_span = self.path.segments[0].ident.span();
        let end_span = self.input.cursor().prev_span();
        crate::error::new2(start_span, end_span, msg)
    }
}

pub(crate) fn parse_nested_meta(
    input: ParseStream,
    mut logic: impl FnMut(ParseNestedMeta) -> Result<()>,
) -> Result<()> {
    loop {
        let path = input.call(parse_meta_path)?;
        logic(ParseNestedMeta { path, input })?;
        if input.is_empty() {
            return Ok(());
        }
        input.parse::<Token![,]>()?;
        if input.is_empty() {
            return Ok(());
        }
    }
}

// Like Path::parse_mod_style, but accepts keywords in the path.
fn parse_meta_path(input: ParseStream) -> Result<Path> {
    Ok(Path {
        leading_colon: input.parse()?,
        segments: {
            let mut segments = Punctuated::new();
            if input.peek(Ident::peek_any) {
                let ident = Ident::parse_any(input)?;
                segments.push_value(PathSegment::from(ident));
            } else if input.is_empty() {
                return Err(input.error("expected nested attribute"));
            } else if input.peek(Lit) {
                return Err(input.error("unexpected literal in nested attribute, expected ident"));
            } else {
                return Err(input.error("unexpected token in nested attribute, expected ident"));
            }
            while input.peek(Token![::]) {
                let punct = input.parse()?;
                segments.push_punct(punct);
                let ident = Ident::parse_any(input)?;
                segments.push_value(PathSegment::from(ident));
            }
            segments
        },
    })
}