pub struct Attribute {
pub pound_token: Pound,
pub style: AttrStyle,
pub bracket_token: Bracket,
pub path: Path,
pub tokens: TokenStream,
}
Expand description
An attribute like #[repr(transparent)]
.
This type is available only if Syn is built with the "derive"
or "full"
feature.
Syntax
Rust has six types of attributes.
- Outer attributes like
#[repr(transparent)]
. These appear outside or in front of the item they describe. - Inner attributes like
#![feature(proc_macro)]
. These appear inside of the item they describe, usually a module. - Outer doc comments like
/// # Example
. - Inner doc comments like
//! Please file an issue
. - Outer block comments
/** # Example */
. - Inner block comments
/*! Please file an issue */
.
The style
field of type AttrStyle
distinguishes whether an attribute
is outer or inner. Doc comments and block comments are promoted to
attributes, as this is how they are processed by the compiler and by
macro_rules!
macros.
The path
field gives the possibly colon-delimited path against which
the attribute is resolved. It is equal to "doc"
for desugared doc
comments. The tokens
field contains the rest of the attribute body as
tokens.
#[derive(Copy)] #[crate::precondition x < 5]
^^^^^^~~~~~~ ^^^^^^^^^^^^^^^^^^^ ~~~~~
path tokens path tokens
Parsing from tokens to Attribute
This type does not implement the Parse
trait and thus cannot be
parsed directly by ParseStream::parse
. Instead use
ParseStream::call
with one of the two parser functions
Attribute::parse_outer
or Attribute::parse_inner
depending on
which you intend to parse.
use syn::{Attribute, Ident, Result, Token};
use syn::parse::{Parse, ParseStream};
// Parses a unit struct with attributes.
//
// #[path = "s.tmpl"]
// struct S;
struct UnitStruct {
attrs: Vec<Attribute>,
struct_token: Token![struct],
name: Ident,
semi_token: Token![;],
}
impl Parse for UnitStruct {
fn parse(input: ParseStream) -> Result<Self> {
Ok(UnitStruct {
attrs: input.call(Attribute::parse_outer)?,
struct_token: input.parse()?,
name: input.parse()?,
semi_token: input.parse()?,
})
}
}
Parsing from Attribute to structured arguments
The grammar of attributes in Rust is very flexible, which makes the
syntax tree not that useful on its own. In particular, arguments of the
attribute are held in an arbitrary tokens: TokenStream
. Macros are
expected to check the path
of the attribute, decide whether they
recognize it, and then parse the remaining tokens according to whatever
grammar they wish to require for that kind of attribute.
If the attribute you are parsing is expected to conform to the
conventional structured form of attribute, use parse_meta()
to
obtain that structured representation. If the attribute follows some
other grammar of its own, use parse_args()
to parse that into the
expected data structure.
Doc comments
The compiler transforms doc comments, such as /// comment
and /*! comment */
, into attributes before macros are expanded. Each comment is
expanded into an attribute of the form #[doc = r"comment"]
.
As an example, the following mod
items are expanded identically:
let doc: ItemMod = parse_quote! {
/// Single line doc comments
/// We write so many!
/**
* Multi-line comments...
* May span many lines
*/
mod example {
//! Of course, they can be inner too
/*! And fit in a single line */
}
};
let attr: ItemMod = parse_quote! {
#[doc = r" Single line doc comments"]
#[doc = r" We write so many!"]
#[doc = r"
* Multi-line comments...
* May span many lines
"]
mod example {
#![doc = r" Of course, they can be inner too"]
#![doc = r" And fit in a single line "]
}
};
assert_eq!(doc, attr);
Fields
pound_token: Pound
style: AttrStyle
bracket_token: Bracket
path: Path
tokens: TokenStream
Implementations
sourceimpl Attribute
impl Attribute
sourcepub fn parse_meta(&self) -> Result<Meta>
pub fn parse_meta(&self) -> Result<Meta>
Parses the content of the attribute, consisting of the path and tokens,
as a Meta
if possible.
This function is available only if Syn is built with the "parsing"
feature.
sourcepub fn parse_args<T: Parse>(&self) -> Result<T>
pub fn parse_args<T: Parse>(&self) -> Result<T>
Parse the arguments to the attribute as a syntax tree.
This is similar to syn::parse2::<T>(attr.tokens)
except that:
- the surrounding delimiters are not included in the input to the parser; and
- the error message has a more useful span when
tokens
is empty.
#[my_attr(value < 5)]
^^^^^^^^^ what gets parsed
This function is available only if Syn is built with the "parsing"
feature.
sourcepub fn parse_args_with<F: Parser>(&self, parser: F) -> Result<F::Output>
pub fn parse_args_with<F: Parser>(&self, parser: F) -> Result<F::Output>
Parse the arguments to the attribute using the given parser.
This function is available only if Syn is built with the "parsing"
feature.
sourcepub fn parse_outer(input: ParseStream<'_>) -> Result<Vec<Self>>
pub fn parse_outer(input: ParseStream<'_>) -> Result<Vec<Self>>
Parses zero or more outer attributes from the stream.
This function is available only if Syn is built with the "parsing"
feature.
sourcepub fn parse_inner(input: ParseStream<'_>) -> Result<Vec<Self>>
pub fn parse_inner(input: ParseStream<'_>) -> Result<Vec<Self>>
Parses zero or more inner attributes from the stream.
This function is available only if Syn is built with the "parsing"
feature.
Trait Implementations
sourceimpl ToTokens for Attribute
impl ToTokens for Attribute
sourcefn to_tokens(&self, tokens: &mut TokenStream)
fn to_tokens(&self, tokens: &mut TokenStream)
Write self
to the given TokenStream
. Read more
sourcefn to_token_stream(&self) -> TokenStream
fn to_token_stream(&self) -> TokenStream
Convert self
directly into a TokenStream
object. Read more
sourcefn into_token_stream(self) -> TokenStream
fn into_token_stream(self) -> TokenStream
Convert self
directly into a TokenStream
object. Read more
impl Eq for Attribute
Auto Trait Implementations
impl RefUnwindSafe for Attribute
impl !Send for Attribute
impl !Sync for Attribute
impl Unpin for Attribute
impl UnwindSafe for Attribute
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Spanned for T where
T: Spanned + ?Sized,
impl<T> Spanned for T where
T: Spanned + ?Sized,
sourcefn span(&self) -> Span
fn span(&self) -> Span
Returns a Span
covering the complete contents of this syntax tree
node, or Span::call_site()
if this node is empty. Read more