mirror of https://github.com/torvalds/linux.git
430 lines
14 KiB
Rust
430 lines
14 KiB
Rust
// 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
|
|
},
|
|
})
|
|
}
|