Trait attribute_derive::Attribute

source · [−]
pub trait Attribute: Sized {
    type Parser: TryExtendOne + Parse + Default;

    const IDENT: Option<&'static str>;

    fn from_attributes<'a>(
        attrs: impl IntoIterator<Item = &'a Attribute>
    ) -> Result<Self> { ... }
    fn remove_attributes(attrs: &mut Vec<Attribute>) -> Result<Self> { ... }
    fn from_args(tokens: TokenStream) -> Result<Self> { ... }
}
Expand description

The trait you actually derive on your attribute struct.

Basic gist is a struct like this:

ⓘ
#[derive(Attribute)]
#[attribute(ident = "collection")]
#[attribute(invalid_field = "Error when an unsupported value is set (e.g. meaning=42")]
struct CollectionAttribute {
    // Options are optional by default (will be set to None if not specified)
    authority: Option<String>,
    #[attribute(missing = "Error when the value is not set")]
    name: String,
    // Any type implementing default can be flagged as default
    // This will be set to Vec::default() when not specified
    #[attribute(default)]
    #[attribute(expected = "Error when an error occured while parsing")]
    views: Vec<Type>,
    // Booleans can be used without assiging a value. as a flag.
    // If omitted they are set to false
    some_flag: bool
}

Will be able to parse an attribute like this:

ⓘ
#[collection(authority="Some String", name = r#"Another string"#, views = [Option, ()], some_flag)]

Required Associated Types

Required Associated Constants

Provided Methods

Parses an IntoIterator of syn::Attributes e.g. Vec<Attribute>.

It can therefore parse fields set over multiple attributes like:

ⓘ
#[collection(authority = "Authority", name = "Name")]
#[collection(views = [A, B])]

and also catch duplicate/conflicting settings over those.

This is best used for derive macros, where you don’t need to remove your attributes.

Panics

The default implementation panics, when IDENT is not set, when using the derive macro, this can be set via #[attribute(ident="some_ident")].

Errors

Fails with a syn::Error so you can conveniently return that as a compiler error in a proc macro in the following cases

  • A necessary parameter is omitted
  • Invalid input is given for a parameter
  • A non aggregating parameter is specified multiple times
  • An attribute called IDENT has invalid syntax (e.g. #attr(a: "a"))

Parses an &mut Vec<syn::Attributes>. Removing matching attributes.

It can therefore parse fields set over multiple attributes like:

ⓘ
#[collection(authority = "Authority", name = "Name")]
#[collection(views = [A, B])]

and also catch duplicate/conflicting settings over those.

Use this if you are implementing an attribute macro, and need to remove your helper attributes.

Panics

The default implementation panics, when IDENT is not set, when using the derive macro, this can be set via #[attribute(ident="some_ident")].

Errors

Fails with a syn::Error so you can conveniently return that as a compiler error in a proc macro in the following cases

  • A necessary parameter is omitted
  • Invalid input is given for a parameter
  • A non aggregating parameter is specified multiple times
  • An attribute called IDENT has invalid syntax (e.g. #attr(a: "a"))

Parses a TokenStream.

Useful for implementing general proc macros to parse the input of your macro.

Due to this only parsing the input for a single attribute it is not able to aggregate input spread over multiple attributes.

Errors

Fails with a syn::Error so you can conveniently return that as a compiler error in a proc macro in the following cases

  • A necessary parameter is omitted
  • Invalid input is given for a parameter
  • A non aggregating parameter is specified multiple times
  • An attribute called IDENT has invalid syntax (e.g. #attr(a: "a"))

Implementors