beerec_variants/

lib.rs

mod ident;
mod nested_meta;
mod rename;
mod string;
mod target;

use darling::FromDeriveInput;
use proc_macro::TokenStream;
use proc_macro2::{Ident, Span, TokenStream as TokenStream2};
use syn::DeriveInput;

use self::target::r#enum::TargetEnum;

/// The actual derive macro implementation.
///
/// This function is introduced in conjunction with `derive_enum_variants`
/// because the `proc_macro_derive` attribute requires its target function
/// signature to be `fn(proc_macro::TokenStream) -> proc_macro::TokenStream`.
///
/// This `impl` function allows to return a `syn::Result`, enabling the `?`
/// operator for fallible function calls. This way, the macro's function
/// can map the error value to a compilation error, providing more precise
/// error messages.
#[rustfmt::skip]
#[allow(clippy::too_many_lines)]
fn derive_enum_variants_impl(input: &DeriveInput) -> syn::Result<TokenStream2> {
    let target_enum = TargetEnum::from_derive_input(input)?;

    let enum_ident = target_enum.ident();

    let variants_count = target_enum.variants_count();
    let variants_idents = target_enum.iter_variant_idents();

    let variants_as_str_match_branches = target_enum.iter_variant_as_str_match_branches();
    let variants_as_str_abbr_match_branches = target_enum.iter_variant_as_str_abbr_match_branches();

    let variants_list_string = target_enum.variants_list_string();
    let variants_list_string_abbr = target_enum.variants_list_string_abbr();

    let iterable_variants_doc = format!(
        "The array of _iterable_ (i.e. non-skipped) [`{enum_ident}`] variants."
    );

    let iterable_variants_count_doc = format!(
        "The number of _iterable_ (i.e. non-skipped) [`{enum_ident}`] variants."
    );

    let as_str_doc = format!(
        r"Returns a string representation of the [`{enum_ident}`] variant.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`]
crate, it applies rename strategies following a priority-based fallback approach:

1. [`InnerRenameStrategy`] (_highest priority_) - uses the string
   produced by the rename strategy from the `#[variants(rename(...))]`
   attribute, if one has been specified for the variant;
1. [`OuterRenameStrategy`] (_fallback_) - uses the string produced by the
   rename strategy from the `#[variants(rename(...))]` attribute, if one has
   been specified for the type;
1. **No renaming** (_default_) - converts the variant identifier to a string
   if neither the type-level nor the variant-level rename attribute has been
   specified.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let as_str_abbr_doc = format!(
        r"Returns an abbreviated string representation of the [`{enum_ident}`] variant.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`]
crate, it applies rename strategies on the string representation of the
variant, following a priority-based fallback approach:

1. [`InnerRenameStrategy`] (_highest priority_) - uses the abbreviated
   string produced by the rename strategy from the `#[variants(rename_abbr(...))]`
   attribute, if one has been specified for the variant;
1. [`OuterRenameStrategy`] (_fallback_) - uses the abbreviated string produced
   by the rename strategy from the `#[variants(rename_abbr(...))]` attribute, if
   one has been specified for the type;
1. **No renaming** (_default_) - abbreviates the full length string representation
   of the variant as is, without applying any renaming strategy.

Likewise, the renaming follows a priority-based fallback approach to
determine the full length string representation before applying the
abbreviation:

1. **Variant-level attribute** (_highest priority_) - uses the string
   produced by the rename strategy from the `#[variants(rename(...))]`
   attribute, if one has been specified for the type;
1. **Type-level attribute** (_fallback_) - uses the string produced by the
   rename strategy from the `#[variants(rename(...))]` attribute, if one has
   been specified for the type;
1. **No renaming** (_default_) - converts the variant identifier to a string
   if neither the type-level nor the variant-level rename attribute has been
   specified.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let iter_variants_doc = format!(
        r"Iterates over _iterable_ (i.e. non-skipped) [`{enum_ident}`] variants.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`] crate,
enum variants marked with the `#[variants(skip)]` attribute are excluded from iteration.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let iter_variants_as_str_doc = format!(
        r"Iterates over _iterable_ (i.e. non-skipped) string representations of [`{enum_ident}`]
variants.

See [`{enum_ident}::as_str`] for further details about yielded values.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`] crate,
enum variants marked with the `#[variants(skip)]` attribute are excluded from iteration.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let iter_variants_as_str_abbr_doc = format!(
        r"Iterates over _iterable_ (i.e. non-skipped) abbreviated string representations of
[`{enum_ident}`] variants.

See [`{enum_ident}::as_str_abbr`] for further details about yielded values.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`] crate,
enum variants marked with the `#[variants(skip)]` attribute are excluded from iteration.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let variants_list_str_doc = format!(
        r"Returns a list of quoted (double-quotes) and comma separated string
representations of _iterable_ (i.e. non-skipped) [`{enum_ident}`] variants.

See [`{enum_ident}::as_str`] for further details about the string representations.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`] crate,
enum variants marked with the `#[variants(skip)]` attribute are excluded from the listing.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let variants_list_str_abbr_doc = format!(
        r"Returns a list of quoted (double-quotes) and comma separated abbreviated string
representations of _iterable_ (i.e. non-skipped) [`{enum_ident}`] variants.

See [`{enum_ident}::as_str_abbr`] for further details about the abbreviated string representations.

# Notes

This method is generated by the [`Variants`] derive macro from the [`beerec-variants`] crate,
enum variants marked with the `#[variants(skip)]` attribute are excluded from the listing.

[`beerec-variants`]: https://docs.rs/beerec-variants
[`Variants`]: https://docs.rs/beerec-variants/latest/beerec_variants/derive.Variants.html"
    );

    let mut generated = quote::quote! {
        impl ::std::marker::Copy for #enum_ident {}

        impl ::std::clone::Clone for #enum_ident {
            fn clone(&self) -> Self {
                *self
            }
        }

        #[automatically_derived]
        impl #enum_ident {
            #[doc = #iterable_variants_doc]
            const ITERABLE_VARIANTS: [Self; #variants_count] = [
                #(Self::#variants_idents,)*
            ];

            #[doc = #iterable_variants_count_doc]
            const ITERABLE_VARIANTS_COUNT: usize = #variants_count;

            #[inline]
            #[must_use]
            #[doc = #as_str_doc]
            pub const fn as_str(self) -> &'static str {
                match self {
                    #(#variants_as_str_match_branches,)*
                }
            }

            #[inline]
            #[must_use]
            #[doc = #as_str_abbr_doc]
            pub const fn as_str_abbr(self) -> &'static str {
                match self {
                    #(#variants_as_str_abbr_match_branches,)*
                }
            }

            #[doc = #iter_variants_doc]
            pub fn iter_variants() -> impl ::std::iter::Iterator<Item = Self> {
                Self::ITERABLE_VARIANTS.into_iter()
            }

            #[doc = #iter_variants_as_str_doc]
            pub fn iter_variants_as_str() -> impl ::std::iter::Iterator<Item = &'static str> {
                Self::iter_variants().map(Self::as_str)
            }

            #[doc = #iter_variants_as_str_abbr_doc]
            pub fn iter_variants_as_str_abbr() -> impl ::std::iter::Iterator<Item = &'static str> {
                Self::iter_variants().map(Self::as_str_abbr)
            }

            #[doc = #variants_list_str_doc]
            pub const fn variants_list_str() -> &'static str {
                #variants_list_string
            }

            #[doc = #variants_list_str_abbr_doc]
            pub const fn variants_list_str_abbr() -> &'static str {
                #variants_list_string_abbr
            }
        }
    };

    if target_enum.implement_display() {
        let generated_display_impl = quote::quote! {
            impl ::std::fmt::Display for #enum_ident {
                fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
                    ::std::fmt::Formatter::write_str(f, self.as_str())
                }
            }
        };

        generated.extend(generated_display_impl);
    }

    if target_enum.implement_from_str() {
        let parse_error_ident = Ident::new(&format!("Parse{enum_ident}Error"), Span::call_site());
        let variants_from_str_match_branches = target_enum.variants_from_str_match_branches();

        let generated_from_str_impl = quote::quote! {
            #[derive(Debug, PartialEq, Eq)]
            pub struct #parse_error_ident;

            impl ::std::fmt::Display for #parse_error_ident {
                fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
                    ::std::fmt::Formatter::write_str(f, "Expected one of ")?;
                    ::std::fmt::Formatter::write_str(f, #enum_ident::variants_list_str())?;
                    ::std::fmt::Formatter::write_str(f, " or one of ")?;
                    ::std::fmt::Formatter::write_str(f, #enum_ident::variants_list_str_abbr())?;

                    Ok(())
                }
            }

            impl ::std::error::Error for #parse_error_ident {}

            impl ::std::str::FromStr for #enum_ident {
                type Err = #parse_error_ident;

                fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
                    match value {
                        #(#variants_from_str_match_branches,)*
                        _ => ::std::result::Result::Err(#parse_error_ident),
                    }
                }
            }
        };

        generated.extend(generated_from_str_impl);
    }

    #[cfg(feature = "serde")]
    if target_enum.implement_deserialize() {
        let visitor_ident = Ident::new(&format!("{enum_ident}Visitor"), Span::call_site());
        let variants_deserialize_match_branches = target_enum.variants_deserialize_match_branches();

        let generated_deserialize_impl = quote::quote! {
            impl<'de> ::serde::de::Deserialize<'de> for #enum_ident {
                fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
                where
                    D: ::serde::de::Deserializer<'de>
                {
                    struct #visitor_ident;

                    impl<'de> ::serde::de::Visitor<'de> for #visitor_ident {
                        type Value = #enum_ident;

                        fn expecting(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
                            ::std::fmt::Formatter::write_str(f, "one of ")?;
                            ::std::fmt::Formatter::write_str(f, #enum_ident::variants_list_str())?;
                            ::std::fmt::Formatter::write_str(f, " or one of ")?;
                            ::std::fmt::Formatter::write_str(f, #enum_ident::variants_list_str_abbr())?;

                            Ok(())
                        }

                        fn visit_str<E>(self, value: &str) -> ::std::result::Result<Self::Value, E>
                        where
                            E: ::serde::de::Error,
                        {
                            match value {
                                #(#variants_deserialize_match_branches,)*
                                _ => {
                                    let unexp = ::serde::de::Unexpected::Str(value);
                                    let error = ::serde::de::Error::invalid_value(unexp, &self);
                                    ::std::result::Result::Err(error)
                                },
                            }
                        }
                    }

                    deserializer.deserialize_str(#visitor_ident)
                }
            }
        };

        generated.extend(generated_deserialize_impl);
    }

    #[cfg(feature = "serde")]
    if target_enum.implement_serialize() {
        let generated_serialize_impl = quote::quote! {
            impl ::serde::ser::Serialize for #enum_ident {
                fn serialize<S>(&self, serializer: S) -> ::std::result::Result<S::Ok, S::Error>
                where
                    S: ::serde::ser::Serializer,
                {
                    serializer.serialize_str(self.as_str())
                }
            }
        };

        generated.extend(generated_serialize_impl);
    }

    Ok(generated)
}

/// Derive macro to generate boilerplate on unit variants `enum` types.
///
/// The macro generates the following methods:
///
/// - `as_str` - returns a string representation of the target `enum` variant;
/// - `as_str_abbr` - returns an abbreviated string representation of the target
///   `enum` variant;
/// - `iter_variants` - returns an iterator over target `enum` variants (owned
///   values);
/// - `iter_variants_as_str` - returns an iterator over string representations
///   of the target `enum` variants (`&'static str` values);
/// - `iter_variants_as_str_abbr` - returns an iterator over abbreviated string
///   representations of the `enum` variants (`&'static str` values);
/// - `variants_list_str` - returns a list of quoted (double-quotes) and comma
///   separated string representations of the `enum` variants;
/// - `variants_list_str_abbr` - returns a list of of quoted (double-quotes) and
///   comma separated abbreviated string representation of the `enum` variants.
///
/// # Enum level attributes
///
/// The macro exposes the following `enum` outer attributes (i.e. attributes to
/// be applied to the `enum` type the macro is being derived on):
///
/// - `rename` - customizes the string representation of each variant;
/// - `rename_abbr` - customizes the abbreviated string representation of each
///   variant;
/// - `display` - generates a [`Display`] trait implementation based on the
///   string representation provided by the generated `as_str` method;
/// - `from_str` - generates a [`FromStr`] trait implementation based on the
///   string or abbreviated string representation provided by the generated
///   `as_str` and `as_str_abbr` methods respectively.
///
/// Valid `rename` and `rename_abbr` customization strategies are:
///
/// - `uppercase` - makes the (abbreviated) string representation uppercase;
/// - `lowercase` - makes the (abbreviated) string representation lowercase.
///
/// ## Examples
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Variants)]
/// #[variants(rename(uppercase))]
/// enum CardinalDirection {
///     North,
///     East,
///     South,
///     West,
/// }
///
/// # fn main() {
/// assert_eq!("NORTH", CardinalDirection::North.as_str());
/// assert_eq!("EAST", CardinalDirection::East.as_str());
/// assert_eq!("SOUTH", CardinalDirection::South.as_str());
/// assert_eq!("WEST", CardinalDirection::West.as_str());
///
/// assert_eq!("NOR", CardinalDirection::North.as_str_abbr());
/// assert_eq!("EAS", CardinalDirection::East.as_str_abbr());
/// assert_eq!("SOU", CardinalDirection::South.as_str_abbr());
/// assert_eq!("WES", CardinalDirection::West.as_str_abbr());
/// # }
/// ```
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Variants)]
/// #[variants(rename(lowercase), rename_abbr(uppercase))]
/// enum State {
///     Active,
///     Inactive,
///     Disabled,
/// }
///
/// # fn main() {
/// assert_eq!("active", State::Active.as_str());
/// assert_eq!("inactive", State::Inactive.as_str());
/// assert_eq!("disabled", State::Disabled.as_str());
///
/// assert_eq!("ACT", State::Active.as_str_abbr());
/// assert_eq!("INA", State::Inactive.as_str_abbr());
/// assert_eq!("DIS", State::Disabled.as_str_abbr());
/// # }
/// ```
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Variants)]
/// #[variants(display)]
/// enum Season {
///     Spring,
///     Summer,
///     Autumn,
///     Winter,
/// }
///
/// # fn main() {
/// assert_eq!(String::from("Spring"), Season::Spring.to_string());
/// assert_eq!(String::from("Summer"), Season::Summer.to_string());
/// assert_eq!(String::from("Autumn"), Season::Autumn.to_string());
/// assert_eq!(String::from("Winter"), Season::Winter.to_string());
///
/// assert_eq!(String::from("Spring"), format!("{}", Season::Spring));
/// assert_eq!(String::from("Summer"), format!("{}", Season::Summer));
/// assert_eq!(String::from("Autumn"), format!("{}", Season::Autumn));
/// assert_eq!(String::from("Winter"), format!("{}", Season::Winter));
/// # }
/// ```
///
/// ```rust
/// # use std::str::FromStr;
/// #
/// # use beerec_variants::Variants;
/// #
/// #[derive(Debug, Variants, PartialEq, Eq)]
/// #[variants(from_str)]
/// enum Priority {
///     Low,
///     Medium,
///     High,
///     Critical,
/// }
///
/// # fn main() {
/// assert_eq!(Ok(Priority::Low), <Priority as FromStr>::from_str("Low"));
/// assert_eq!(Ok(Priority::Medium), <Priority as FromStr>::from_str("Medium"));
/// assert_eq!(Ok(Priority::High), <Priority as FromStr>::from_str("High"));
/// assert_eq!(Ok(Priority::Critical), <Priority as FromStr>::from_str("Critical"));
///
/// assert_eq!(Ok(Priority::Low), <Priority as FromStr>::from_str("Low"));
/// assert_eq!(Ok(Priority::Medium), <Priority as FromStr>::from_str("Med"));
/// assert_eq!(Ok(Priority::High), <Priority as FromStr>::from_str("Hig"));
/// assert_eq!(Ok(Priority::Critical), <Priority as FromStr>::from_str("Cri"));
///
/// assert_eq!(Err(ParsePriorityError), <Priority as FromStr>::from_str("invalid"));
/// # }
/// ```
///
/// ## Feature-gated attributes
///
/// ### [Serde](https://crates.io/crates/serde)
///
/// The following `enum` outer attributes are exposed when the `serde` feature is
/// enabled:
/// 
/// - `deserialize` - generates a [`Deserialize`] trait implementation based on
///   the string or abbreviated string representation provided by the generated
///   `as_str` and `as_str_abbr` respectively;
/// - `serialize` - generates a [`Serialize`] trait implementation based on the
///   string representation provided by the generated `as_str` method.
/// 
/// #### Examples
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Debug, Variants, PartialEq, Eq)]
/// # #[cfg(feature = "serde")]
/// #[variants(deserialize)]
/// enum Theme {
///     Auto,
///     Dark,
///     Light,
/// }
///
/// #[derive(Debug, PartialEq, Eq)]
/// # #[cfg(feature = "serde")]
/// #[derive(serde::Deserialize)]
/// struct Config {
///     theme: Theme,
/// }
///
/// # fn main() {
/// # #[cfg(feature = "serde")]
/// # {
/// // Deserialize from variant string representation.
/// assert_eq!(
///     Ok(Config { theme: Theme::Auto }),
///     toml::from_str::<'_, Config>("theme = \"Auto\"\n"),
/// );
///
/// assert_eq!(
///     Ok(Config { theme: Theme::Dark }),
///     toml::from_str::<'_, Config>("theme = \"Dark\"\n"),
/// );
///
/// assert_eq!(
///     Ok(Config { theme: Theme::Light }),
///     toml::from_str::<'_, Config>("theme = \"Light\"\n"),
/// );
///
/// // Deserialize from variant abbreviated string representation.
/// assert_eq!(
///     Ok(Config { theme: Theme::Auto }),
///     toml::from_str::<'_, Config>("theme = \"Aut\"\n"),
/// );
///
/// assert_eq!(
///     Ok(Config { theme: Theme::Dark }),
///     toml::from_str::<'_, Config>("theme = \"Dar\"\n"),
/// );
///
/// assert_eq!(
///     Ok(Config { theme: Theme::Light }),
///     toml::from_str::<'_, Config>("theme = \"Lig\"\n"),
/// );
/// # }
/// # }
/// ```
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Debug, Variants, PartialEq, Eq)]
/// # #[cfg(feature = "serde")]
/// #[variants(serialize)]
/// enum Codec {
///     H264,
///     H265,
///     AV1,
/// }
///
/// #[derive(Debug, PartialEq, Eq)]
/// # #[cfg(feature = "serde")]
/// #[derive(serde::Serialize)]
/// struct Config {
///     codec: Codec,
/// }
///
/// # fn main() {
/// # #[cfg(feature = "serde")]
/// # {
/// assert_eq!(
///     Ok(String::from("codec = \"H264\"\n")),
///     toml::to_string(&Config { codec: Codec::H264 }),
/// );
///
/// assert_eq!(
///     Ok(String::from("codec = \"H265\"\n")),
///     toml::to_string(&Config { codec: Codec::H265 }),
/// );
///
/// assert_eq!(
///     Ok(String::from("codec = \"AV1\"\n")),
///     toml::to_string(&Config { codec: Codec::AV1 }),
/// );
/// # }
/// # }
/// ```
///
/// # Variant level attributes
///
/// The macro exposes the following variant attributes:
///
/// - `skip` - excludes the marked variant from iteration and listing;
/// - `rename` - customizes the string representation of the marked variant;
/// - `rename_abbr` - customizes the abbreviated string representation of the
///   marked variant.
///
/// Valid `rename` and `rename_abbr` customization strategies are:
///
/// - `"..."` (string literal) - overrides the string representation with a
///   custom string;
/// - `uppercase` - makes the (abbreviated) string representation uppercase;
/// - `lowercase` - makes the (abbreviated) string representation lowercase.
///
/// For custom string overrides:
///
/// - `#[variants(rename = "...")]` is equivalent to
///   `#[variants(rename("..."))]`;
/// - `#[variants(rename_abbr = "...")]` is equivalent to
///   `#[variants(rename_abbr("..."))]`;
///
/// both are valid, supported formats.
///
/// ## Examples
///
/// ```rust
/// # use beerec_variants::Variants;
/// #
/// #[derive(Variants)]
/// enum Format {
///     Xml,
///     Csv,
///     #[variants(rename("plain-text"), rename_abbr = "txt")]
///     PlainText,
/// }
///
/// # fn main() {
/// assert_eq!("Xml", Format::Xml.as_str());
/// assert_eq!("Csv", Format::Csv.as_str());
/// assert_eq!("plain-text", Format::PlainText.as_str());
///
/// assert_eq!("Xml", Format::Xml.as_str_abbr());
/// assert_eq!("Csv", Format::Csv.as_str_abbr());
/// assert_eq!("txt", Format::PlainText.as_str_abbr());
/// # }
/// ```
///
/// # String representation renaming priority
///
/// To produce _string representations_ of enum variants, renaming can be
/// applied at both the type level and variant level. The string representation
/// of each variant is obtained by applying rename strategies following a
/// priority-based fallback approach:
///
/// 1. **Variant-level attribute** (_highest priority_) - usese the string
///    produced by the rename strategy from the `#[variants(rename(...))]`
///    attribute, if one has been specified for the variant;
/// 1. **Type-level attribute** (_fallback_) - uses the string produced by the
///    rename strategy from the `#[variants(rename(...))]` attribute, if one has
///    been specified for the type;
/// 1. **No renaming** (_default_) - converts the variant identifier to a string
///    if neither the type-level nor the variant-level rename attribute has been
///    specified.
///
/// # Abbreviated string representation renaming priority
///
/// To produce _abbreviated string representations_ of the enum variants,
/// renaming can be applied at both the type level and the variant level. The
/// abbreviated string representation of each variant is obtained by applying
/// rename strategies following a priority-based fallback approach:
///
/// 1. **Variant-level attribute** (_highest priority_) - uses the abbreviated
///    string produced by the rename strategy from the
///    `#[variants(rename_abbr(...))]` attribute, if one has been specified for
///    the variant;
/// 1. **Type-level attribute** (_fallback_) - uses the string produced by the
///    rename strategy from the `#[variants(rename(...))]` attribute, if one has
///    been specified for the type;
/// 1. **No renaming** (_default_) - abbreviates the full length string
///    representation of the variant as is, without applying any renaming
///    strategy.
///
/// Likewise, the renaming follows a priority-based fallback approach to
/// determine the full length string representation before applying the
/// abbreviation:
///
/// 1. **Variant-level attribute** (_highest priority_) - uses the string
///    produced by the rename strategy from the `#[variants(rename(...))]`
///    attribute, if one has been specified for the type;
/// 1. **Type-level attribute** (_fallback_) - uses the string produced by the
///    rename strategy from the `#[variants(rename(...))]` attribute, if one has
///    been specified for the type;
/// 1. **No renaming** (_default_) - converts the variant identifier to a string
///    if neither the type-level nor the variant-level rename attribute has been
///    specified.
///
/// # Errors
///
/// The macro will produce a compile error if:
///
/// - derived on `struct` types;
/// - derived on `union` types;
/// - derived on `enum` types with any named field variants;
/// - derived on `enum` types with any unnamed field (i.e. tuple) variants;
/// - derived on `enum` types with any newtype variants;
/// - the `rename` variant-level attribute is passed any other value than a
///   string literal, `uppercase` or `lowercase`;
/// - the `rename_abbr` variant-level attribute is passed any other value than a
///   string literal, `uppercase` or `lowercase`;
/// - the `rename` type-level attribute is passed any other value than
///   `uppercase` or `lowercase`;
/// - the `rename_abbr` type-level attribute is passed any other value than
///   `uppercase` or `lowercase`.
///
/// # Notes
///
/// Deriving [`Variants`] on type automatically implements [`Clone`] and
/// [`Copy`] for such type. This means that deriving either trait on a type that
/// also derives [`Variants`] will result in a "conflicting implementations"
/// compilation error.
///
/// # Examples
///
/// ```rust
/// # use std::str::FromStr;
/// #
/// # use beerec_variants::Variants;
/// #
/// #[derive(Variants, Debug, PartialEq, Eq)]
/// #[cfg_attr(feature = "serde", variants(deserialize, serialize))]
/// #[variants(display, from_str)]
/// enum Weekday {
///     #[variants(skip)]
///     Monday,
///     #[variants(rename = "DayAfterMonday", rename_abbr = "tue")]
///     Tuesday,
///     #[variants(rename_abbr = "wed")]
///     Wednesday,
///     #[variants(rename = "Giovedì", rename_abbr(lowercase))]
///     Thursday,
///     Friday,
///     Saturday,
///     Sunday,
/// }
///
/// #[derive(Debug, PartialEq, Eq)]
/// #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
/// struct Schedule {
///     weekday: Weekday,
/// }
///
/// # fn main() {
/// // Monday has been marked as `skip`, iterator will yield 6 values.
/// assert_eq!(6, Weekday::iter_variants().count());
///
/// assert_eq!("Monday", Weekday::Monday.as_str());
/// assert_eq!("DayAfterMonday", Weekday::Tuesday.as_str());
/// assert_eq!("Wednesday", Weekday::Wednesday.as_str());
/// assert_eq!("Giovedì", Weekday::Thursday.as_str());
/// assert_eq!("Friday", Weekday::Friday.as_str());
/// assert_eq!("Saturday", Weekday::Saturday.as_str());
/// assert_eq!("Sunday", Weekday::Sunday.as_str());
///
/// assert_eq!("Mon", Weekday::Monday.as_str_abbr());
/// assert_eq!("tue", Weekday::Tuesday.as_str_abbr());
/// assert_eq!("wed", Weekday::Wednesday.as_str_abbr());
/// assert_eq!("gio", Weekday::Thursday.as_str_abbr());
/// assert_eq!("Fri", Weekday::Friday.as_str_abbr());
/// assert_eq!("Sat", Weekday::Saturday.as_str_abbr());
/// assert_eq!("Sun", Weekday::Sunday.as_str_abbr());
///
/// // The enum has been marked as `display`, so `std::fmt::Display` implementation is available.
/// assert_eq!(String::from("Monday"), Weekday::Monday.to_string());
/// assert_eq!(String::from("DayAfterMonday"), Weekday::Tuesday.to_string());
/// assert_eq!(String::from("Wednesday"), Weekday::Wednesday.to_string());
/// assert_eq!(String::from("Giovedì"), Weekday::Thursday.to_string());
/// assert_eq!(String::from("Friday"), Weekday::Friday.to_string());
/// assert_eq!(String::from("Saturday"), Weekday::Saturday.to_string());
/// assert_eq!(String::from("Sunday"), Weekday::Sunday.to_string());
///
/// assert_eq!(String::from("Monday"), format!("{}", Weekday::Monday));
/// assert_eq!(String::from("DayAfterMonday"), format!("{}", Weekday::Tuesday));
/// assert_eq!(String::from("Wednesday"), format!("{}", Weekday::Wednesday));
/// assert_eq!(String::from("Giovedì"), format!("{}", Weekday::Thursday));
/// assert_eq!(String::from("Friday"), format!("{}", Weekday::Friday));
/// assert_eq!(String::from("Saturday"), format!("{}", Weekday::Saturday));
/// assert_eq!(String::from("Sunday"), format!("{}", Weekday::Sunday));
///
/// let mut weekdays = Weekday::iter_variants();
/// assert_eq!(Some(Weekday::Tuesday), weekdays.next());
/// assert_eq!(Some(Weekday::Wednesday), weekdays.next());
/// assert_eq!(Some(Weekday::Thursday), weekdays.next());
/// assert_eq!(Some(Weekday::Friday), weekdays.next());
/// assert_eq!(Some(Weekday::Saturday), weekdays.next());
/// assert_eq!(Some(Weekday::Sunday), weekdays.next());
/// assert_eq!(None, weekdays.next());
///
/// let mut weekdays_as_str = Weekday::iter_variants_as_str();
/// assert_eq!(Some("DayAfterMonday"), weekdays_as_str.next());
/// assert_eq!(Some("Wednesday"), weekdays_as_str.next());
/// assert_eq!(Some("Giovedì"), weekdays_as_str.next());
/// assert_eq!(Some("Friday"), weekdays_as_str.next());
/// assert_eq!(Some("Saturday"), weekdays_as_str.next());
/// assert_eq!(Some("Sunday"), weekdays_as_str.next());
/// assert_eq!(None, weekdays.next());
///
/// let mut weekdays_as_str_abbr = Weekday::iter_variants_as_str_abbr();
/// assert_eq!(Some("tue"), weekdays_as_str_abbr.next());
/// assert_eq!(Some("wed"), weekdays_as_str_abbr.next());
/// assert_eq!(Some("gio"), weekdays_as_str_abbr.next());
/// assert_eq!(Some("Fri"), weekdays_as_str_abbr.next());
/// assert_eq!(Some("Sat"), weekdays_as_str_abbr.next());
/// assert_eq!(Some("Sun"), weekdays_as_str_abbr.next());
/// assert_eq!(None, weekdays.next());
///
/// assert_eq!(
///     "\"DayAfterMonday\", \"Wednesday\", \"Giovedì\", \"Friday\", \"Saturday\", \"Sunday\"",
///     Weekday::variants_list_str(),
/// );
///
/// assert_eq!(
///     "\"tue\", \"wed\", \"gio\", \"Fri\", \"Sat\", \"Sun\"",
///     Weekday::variants_list_str_abbr(),
/// );
///
/// // The enum has been marked as `from_str`, so `std::str::FromStr` implementation is available.
/// assert_eq!(Ok(Weekday::Monday), <Weekday as FromStr>::from_str("Monday"));
/// assert_eq!(Ok(Weekday::Tuesday), <Weekday as FromStr>::from_str("DayAfterMonday"));
/// assert_eq!(Ok(Weekday::Wednesday), <Weekday as FromStr>::from_str("Wednesday"));
/// assert_eq!(Ok(Weekday::Thursday), <Weekday as FromStr>::from_str("Giovedì"));
/// assert_eq!(Ok(Weekday::Friday), <Weekday as FromStr>::from_str("Friday"));
/// assert_eq!(Ok(Weekday::Saturday), <Weekday as FromStr>::from_str("Saturday"));
/// assert_eq!(Ok(Weekday::Sunday), <Weekday as FromStr>::from_str("Sunday"));
///
/// assert_eq!(Ok(Weekday::Monday), <Weekday as FromStr>::from_str("Mon"));
/// assert_eq!(Ok(Weekday::Tuesday), <Weekday as FromStr>::from_str("tue"));
/// assert_eq!(Ok(Weekday::Wednesday), <Weekday as FromStr>::from_str("wed"));
/// assert_eq!(Ok(Weekday::Thursday), <Weekday as FromStr>::from_str("gio"));
/// assert_eq!(Ok(Weekday::Friday), <Weekday as FromStr>::from_str("Fri"));
/// assert_eq!(Ok(Weekday::Saturday), <Weekday as FromStr>::from_str("Sat"));
/// assert_eq!(Ok(Weekday::Sunday), <Weekday as FromStr>::from_str("Sun"));
///
/// assert_eq!(Err(ParseWeekdayError), <Weekday as FromStr>::from_str("invalid"));
///
/// // The enum has been marked as `deserialize`, so `serde::Deserialize` implementation is available.
/// #[cfg(feature = "serde")]
/// {
///     // Deserialize from variant string representation.
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Monday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Monday\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Tuesday }),
///         toml::from_str::<'_, Schedule>("weekday = \"DayAfterMonday\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Wednesday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Wednesday\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Thursday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Giovedì\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Friday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Friday\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Saturday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Saturday\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Sunday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Sunday\"\n"),
///     );
///
///     // Deserialize from variant abbreviated string representation.
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Monday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Mon\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Tuesday }),
///         toml::from_str::<'_, Schedule>("weekday = \"tue\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Wednesday }),
///         toml::from_str::<'_, Schedule>("weekday = \"wed\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Thursday }),
///         toml::from_str::<'_, Schedule>("weekday = \"gio\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Friday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Fri\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Saturday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Sat\"\n"),
///     );
///
///     assert_eq!(
///         Ok(Schedule { weekday: Weekday::Sunday }),
///         toml::from_str::<'_, Schedule>("weekday = \"Sun\"\n"),
///     );
/// }
/// 
/// // The enum has been marked as `serialize`, so `serde::Serialize` implementation is available.
/// #[cfg(feature = "serde")]
/// {
///     assert_eq!(
///         Ok(String::from("weekday = \"Monday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Monday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"DayAfterMonday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Tuesday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"Wednesday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Wednesday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"Giovedì\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Thursday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"Friday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Friday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"Saturday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Saturday }),
///     );
///
///     assert_eq!(
///         Ok(String::from("weekday = \"Sunday\"\n")),
///         toml::to_string(&Schedule { weekday: Weekday::Sunday }),
///     );
/// }
/// # }
/// 
/// ```
///
/// [`Clone`]: https://doc.rust-lang.org/std/clone/trait.Clone.html
/// [`Copy`]: https://doc.rust-lang.org/std/marker/trait.Copy.html
/// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
/// [`FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
/// [`Deserialize`]: https://docs.rs/serde/latest/serde/trait.Deserialize.html
/// [`Serialize`]: https://docs.rs/serde/latest/serde/trait.Serialize.html
#[proc_macro_derive(Variants, attributes(variants))]
pub fn derive_enum_variants(input: TokenStream) -> TokenStream {
    let input = syn::parse_macro_input!(input as DeriveInput);

    derive_enum_variants_impl(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

#[cfg(test)]
mod test {
    #[test]
    fn expand() {
        macrotest::expand("tests/expand/*.rs");
    }

    #[test]
    fn expand_serde() {
        macrotest::expand_args("tests/expand/serde/*.rs", &["--features", "serde"]);
    }

    #[test]
    fn error() {
        let test = trybuild::TestCases::new();
        test.compile_fail("tests/fail/*.rs");
    }
}