[−][src]Struct syn::Attribute

pub struct Attribute {
    pub pound_token: Pound,
    pub style: AttrStyle,
    pub bracket_token: Bracket,
    pub path: Path,
    pub tokens: TokenStream,
}

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: Poundstyle: AttrStylebracket_token: Bracketpath: Pathtokens: TokenStream