# Attribute in syn - Rust
An attribute, like `#[repr(transparent)]`.

syn

# Struct Attribute

Source

    pub struct Attribute {
        pub pound_token: Pound,
        pub style: AttrStyle,
        pub bracket_token: Bracket,
        pub meta: Meta,
    }

Expand description

An attribute, like `#[repr(transparent)]`.

## §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 one-line doc comments like `/// Example`.

- Inner one-line doc comments like `//! Please file an issue`.

- Outer documentation blocks `/** Example */`.

- Inner documentation blocks `/*! Please file an issue */`.

The `style` field of type `AttrStyle` distinguishes whether an attribute is outer or inner.

Every attribute has a `path` that indicates the intended interpretation of the rest of the attribute’s contents. The path and the optional additional contents are represented together in the `meta` field of the attribute in three possible varieties:

- Meta::Path — attributes whose information content conveys just a path, for example the `#[test]` attribute.

- Meta::List — attributes that carry arbitrary tokens after the path, surrounded by a delimiter (parenthesis, bracket, or brace). For example `#[derive(Copy)]` or `#[precondition(x < 5)]`.

- Meta::NameValue — attributes with an `=` sign after the path, followed by a Rust expression. For example `#[path = "sys/windows.rs"]`.

All doc comments are represented in the NameValue style with a path of “doc”, as this is how they are processed by the compiler and by `macro_rules!` macros.

    #[derive(Copy, Clone)]
      ~~~~~~Path
      ^^^^^^^^^^^^^^^^^^^Meta::List

    #[path = "sys/windows.rs"]
      ~~~~Path
      ^^^^^^^^^^^^^^^^^^^^^^^Meta::NameValue

    #[test]
      ^^^^Meta::Path

## §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 `Meta::List` variety of 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. Use `parse_args()` to parse those tokens 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` § `meta: Meta`

## Implementations§

Source §

### impl Attribute

Source

#### pub fn path(&self) -> &Path

Returns the path that identifies the interpretation of this attribute.

For example this would return the `test` in `#[test]`, the `derive` in `#[derive(Copy)]`, and the `path` in `#[path = "sys/windows.rs"]`.

Source

#### pub fn parse_args<T: Parse>(&self) -> Result<T>

Parse the arguments to the attribute as a syntax tree.

This is similar to pulling out the `TokenStream` from `Meta::List` and doing `syn::parse2::<T>(meta_list.tokens)`, except that using `parse_args` the error message has a more useful span when `tokens` is empty.

The surrounding delimiters are not included in the input to the parser.

    #[my_attr(value < 5)]
              ^^^^^^^^^ what gets parsed

##### §Example

    use syn::{parse_quote, Attribute, Expr};

    let attr: Attribute = parse_quote! {
        #[precondition(value < 5)]
    };

    if attr.path().is_ident("precondition") {
        let precondition: Expr = attr.parse_args()?;
        // ...
    }

Source

#### pub fn parse_args_with<F: Parser>(&self, parser: F) -> Result<F::Output>

Parse the arguments to the attribute using the given parser.

##### §Example

    use syn::{parse_quote, Attribute};

    let attr: Attribute = parse_quote! {
        #[inception { #[brrrrrrraaaaawwwwrwrrrmrmrmmrmrmmmmm] }]
    };

    let bwom = attr.parse_args_with(Attribute::parse_outer)?;

    // Attribute does not have a Parse impl, so we couldn't directly do:
    // let bwom: Attribute = attr.parse_args()?;

Source

#### pub fn parse_nested_meta( &self, logic: impl FnMut(ParseNestedMeta<'_>) -> Result<()>, ) -> Result<()>

Parse the arguments to the attribute, expecting it to follow the conventional structure used by most of Rust’s built-in attributes.

The Meta Item Attribute Syntax section in the Rust reference explains the convention in more detail. Not all attributes follow this convention, so `parse_args()` is available if you need to parse arbitrarily goofy attribute syntax.

##### §Example

We’ll parse a struct, and then parse some of Rust’s `#[repr]` attribute syntax.

    use syn::{parenthesized, parse_quote, token, ItemStruct, LitInt};

    let input: ItemStruct = parse_quote! {
        #[repr(C, align(4))]
        pub struct MyStruct(u16, u32);
    };

    let mut repr_c = false;
    let mut repr_transparent = false;
    let mut repr_align = None::<usize>;
    let mut repr_packed = None::<usize>;
    for attr in &input.attrs {
        if attr.path().is_ident("repr") {
            attr.parse_nested_meta(|meta| {
                // #[repr(C)]
                if meta.path.is_ident("C") {
                    repr_c = true;
                    return Ok(());
                }

                // #[repr(transparent)]
                if meta.path.is_ident("transparent") {
                    repr_transparent = true;
                    return Ok(());
                }

                // #[repr(align(N))]
                if meta.path.is_ident("align") {
                    let content;
                    parenthesized!(content in meta.input);
                    let lit: LitInt = content.parse()?;
                    let n: usize = lit.base10_parse()?;
                    repr_align = Some(n);
                    return Ok(());
                }

                // #[repr(packed)] or #[repr(packed(N))], omitted N means 1
                if meta.path.is_ident("packed") {
                    if meta.input.peek(token::Paren) {
                        let content;
                        parenthesized!(content in meta.input);
                        let lit: LitInt = content.parse()?;
                        let n: usize = lit.base10_parse()?;
                        repr_packed = Some(n);
                    } else {
                        repr_packed = Some(1);
                    }
                    return Ok(());
                }

                Err(meta.error("unrecognized repr"))
            })?;
        }
    }

##### §Alternatives

In some cases, for attributes which have nested layers of structured content, the following less flexible approach might be more convenient:

    use syn::punctuated::Punctuated;
    use syn::{parenthesized, token, Error, LitInt, Meta, Token};

    let mut repr_c = false;
    let mut repr_transparent = false;
    let mut repr_align = None::<usize>;
    let mut repr_packed = None::<usize>;
    for attr in &input.attrs {
        if attr.path().is_ident("repr") {
            let nested = attr.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
            for meta in nested {
                match meta {
                    // #[repr(C)]
                    Meta::Path(path) if path.is_ident("C") => {
                        repr_c = true;
                    }

                    // #[repr(align(N))]
                    Meta::List(meta) if meta.path.is_ident("align") => {
                        let lit: LitInt = meta.parse_args()?;
                        let n: usize = lit.base10_parse()?;
                        repr_align = Some(n);
                    }

                    /* ... */

                    _ => {
                        return Err(Error::new_spanned(meta, "unrecognized repr"));
                    }
                }
            }
        }
    }

Source

#### pub fn parse_outer(input: ParseStream<'_>) -> Result<Vec<Self>>

Parses zero or more outer attributes from the stream.

##### §Example

See Parsing from tokens to Attribute.

Source

#### pub fn parse_inner(input: ParseStream<'_>) -> Result<Vec<Self>>

Parses zero or more inner attributes from the stream.

##### §Example

See Parsing from tokens to Attribute.

## Trait Implementations§

Source §

### impl Clone for Attribute

Source §

#### fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · Source §

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
Source §

### impl Debug for Attribute

Source §

#### fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source §

### impl Hash for Attribute

Source §

#### fn hash<H>(&self, state: &mut H)
where H: Hasher,

Feeds this value into the given `Hasher`. Read more
1.3.0 · Source §

#### fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given `Hasher`. Read more
Source §

### impl PartialEq for Attribute

Source §

#### fn eq(&self, other: &Self) -> bool

Tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · Source §

#### fn ne(&self, other: &Rhs) -> bool

Tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source §

### impl ToTokens for Attribute

Source §

#### fn to_tokens(&self, tokens: &mut TokenStream)

Write `self` to the given `TokenStream`. Read more
Source §

#### fn to_token_stream(&self) -> TokenStream

Convert `self` directly into a `TokenStream` object. Read more
Source §

#### fn into_token_stream(self) -> TokenStream
where Self: Sized,

Convert `self` directly into a `TokenStream` object. Read more
Source §

### impl Eq for Attribute

## Auto Trait Implementations§

§

### impl Freeze for Attribute

§

### impl RefUnwindSafe for Attribute

§

### impl !Send for Attribute

§

### impl !Sync for Attribute

§

### impl Unpin for Attribute

§

### impl UnwindSafe for Attribute

## Blanket Implementations§

Source §

### impl<T> Any for T
where T: 'static + ?Sized,

Source §

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source §

### impl<T> Borrow<T> for T
where T: ?Sized,

Source §

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source §

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source §

### impl<T> CloneToUninit for T
where T: Clone,

Source §

#### unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (`clone_to_uninit`)
Performs copy-assignment from `self` to `dst`. Read more
Source §

### impl<T> From<T> for T

Source §

#### fn from(t: T) -> T

Returns the argument unchanged.

Source §

### impl<T, U> Into<U> for T
where U: From<T>,

Source §

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source §

### impl<T> Spanned for T
where T: Spanned + ?Sized,

Source §

#### 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.
Source §

### impl<T> ToOwned for T
where T: Clone,

Source §

#### type Owned = T

The resulting type after obtaining ownership.
Source §

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source §

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source §

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source §

#### type Error = Infallible

The type returned in the event of a conversion error.
Source §

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source §

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source §

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source §

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.