//  LIB.rs
//    by Lut99
//
//  Created:
//    10 Dec 2022, 11:37:39
//  Last edited:
//    23 Jul 2024, 00:08:55
//  Auto updated?
//    Yes
//
//  Description:
//!   Simple Rust crate that implements EnumDebug, which can automatically derive a formatter for enum variant names only.
//!   
//!   
//!   # Installation
//!   To use this crate, simply add the following to your `Cargo.toml`:
//!   ```toml
//!   enum-debug = { git = "https://github.com/Lut99/enum-debug" }
//!   ```
//!   
//!   This will use the latest version. You can also commit yourself to a specific version by using:
//!   ```toml
//!   enum-debug = { git = "https://github.com/Lut99/enum-debug", tag="v<VERSION>" }
//!   ```
//!   where you should replace `<VERSION>` with the version of your choice (check the [releases](https://github.com/Lut99/enum-debug/releases) to find possible options).
//!   
//!   
//!   # Usage
//!   This crate makes the `EnumDebug` trait available, which can be implemented on an enum of your choice.
//!   
//!   Custom implementation is done as follows:
//!   ```rust
//!   use enum_debug::EnumDebug;
//!   
//!   enum Jedi {
//!       ObiWanKenobi,
//!       AnakinSkywalker,
//!       MaceWindu,
//!       MasterYoda,
//!   }
//!   impl EnumDebug for Jedi {
//!       // NOTE: Not necessary, but otherwise it will use the Rust internal type name
//!       #[inline]
//!       fn type_name() -> &'static str { "Jedi" }
//!   
//!       #[inline]
//!       fn variant_names() -> &'static [&'static str] {
//!           &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
//!       }
//!   
//!       #[inline]
//!       fn variant_name(&self) -> &'static str {
//!           match self {
//!               Self::ObiWanKenobi => Self::variant_names()[0],
//!               Self::AnakinSkywalker => Self::variant_names()[1],
//!               Self::MaceWindu => Self::variant_names()[2],
//!               Self::MasterYoda => Self::variant_names()[3],
//!           }
//!       }
//!   }
//!   
//!   assert_eq!(format!("{}", Jedi::ObiWanKenobi.variant()), "ObiWanKenobi");
//!   assert_eq!(format!("{:?}", Jedi::AnakinSkywalker.variant()), "Jedi::AnakinSkywalker");
//!   assert_eq!(Jedi::MaceWindu.variant_name(), "MaceWindu");
//!   ```
//!   
//!   However, this is quite tedious. A faster way is to use the `derive` feature and the use the derive macro:
//!   ```toml
//!   # Enable the feature
//!   enum-debug = { git = "https://github.com/Lut99/enum-debug", features = ["derive"] }
//!   ```
//!   ```rust
//!   use enum_debug::EnumDebug;
//!   
//!   // Now it becomes as easy as
//!   #[derive(EnumDebug)]
//!   enum Jedi {
//!       ObiWanKenobi,
//!       AnakinSkywalker,
//!       MaceWindu,
//!       MasterYoda,
//!   }
//!   
//!   assert_eq!(format!("{}", Jedi::ObiWanKenobi.variant()), "ObiWanKenobi");
//!   assert_eq!(format!("{:?}", Jedi::AnakinSkywalker.variant()), "Jedi::AnakinSkywalker");
//!   assert_eq!(Jedi::MaceWindu.variant_name(), "MaceWindu");
//!   ```
//!   
//!   See the documentation on the `derive`-module for more information on the derive-macro.
//!   
//!   
//!   # Contribution
//!   If you have any suggestions, comments, tip or bugs, please create an [issue](https://github.com/Lut99/enum-debug/issues) to let us know! Or go ahead and create a [pull request](https://github.com/Lut99/enum-debug/pulls).
//!   
//!   
//!   # License
//!   This project is licensed under the Apache 2.0 license. See [`LICENSE`](./LICENSE) for more information.
//!   
//

use std::fmt::{Debug, Display, Formatter, Result as FResult};
use std::iter::Copied;

#[cfg(feature = "derive")]
pub use enum_debug_derive::EnumDebug;


/***** MODULES *****/
/// Can be used to bring this library's prelude into scope.
pub mod prelude {
    pub use super::EnumDebug;
}

/// The [`EnumDebug`]-trait is most powerful when combined with the
/// [`EnumDebug`](derive@EnumDebug)-derive macro. This macro is only available when the `derive`-
/// feature is used.
///
/// To use it, simply derive [`EnumDebug`]:
/// ```rust
/// use enum_debug::EnumDebug;
///
/// #[derive(EnumDebug)]
/// enum Jedi {
///     ObiWanKenobi,
///     AnakinSkywalker,
///     MaceWindu,
///     MasterYoda,
/// }
///
/// assert_eq!(format!("{}", Jedi::ObiWanKenobi.variant()), "ObiWanKenobi");
/// assert_eq!(format!("{:?}", Jedi::AnakinSkywalker.variant()), "Jedi::AnakinSkywalker");
/// assert_eq!(Jedi::MaceWindu.variant().to_string(), "MaceWindu");
/// ```
///
/// You can also give it a different type name:
/// ```
/// use enum_debug::EnumDebug;
///
/// #[derive(EnumDebug)]
/// #[enum_debug(name = "ForceWielder")]
/// enum Jedi {
///     ObiWanKenobi,
///     AnakinSkywalker,
///     MaceWindu,
///     MasterYoda,
/// }
///
/// assert_eq!(&format!("{:?}", Jedi::ObiWanKenobi.variant()), "ForceWielder::ObiWanKenobi");
/// ```
///
/// Or use the full path name as generated by Rust:
/// ```
/// use enum_debug::EnumDebug;
///
/// #[derive(EnumDebug)]
/// #[enum_debug(path)]
/// enum Jedi {
///     ObiWanKenobi,
///     AnakinSkywalker,
///     MaceWindu,
///     MasterYoda,
/// }
///
/// assert_eq!(
///     &format!("{:?}", Jedi::ObiWanKenobi.variant()),
///     "rust_out::main::_doctest_main_src_lib_rs_152_0::Jedi::ObiWanKenobi"
/// );
/// ```
#[cfg(feature = "derive")]
pub mod derive {
    pub use enum_debug_derive::EnumDebug;
}





/***** AUXILLARY *****/
/// Implements a formatter that can write the variant name of an enum.
///
/// The [`Debug`]-formatter writes the enum name and its current variant name, as given by the [`EnumDebug`] trait.
///
/// The [`Display`]-formatter just writes its name.
///
/// This formatter is returned by [`EnumDebug::variant()`].
///
/// # Examples
/// See [`EnumDebug`] for some examples.
pub struct EnumDebugFormatter<'a, T: ?Sized> {
    /// The enum to format.
    e: &'a T,
}
impl<'a, T: EnumDebug> Debug for EnumDebugFormatter<'a, T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> FResult { write!(f, "{}::{}", T::type_name(), self.e.variant_name()) }
}
impl<'a, T: EnumDebug> Display for EnumDebugFormatter<'a, T> {
    #[inline]
    fn fmt(&self, f: &mut Formatter<'_>) -> FResult { write!(f, "{}", self.e.variant_name()) }
}





/***** LIBRARY *****/
/// Exposes the names of the variants in an enum.
///
/// By itself, this enum doesn't add a lot over just defining your own functions. However, if you
/// use the `derive`-feature, you can automatically generate it based on your normal enum
/// definition.
///
/// See [`derive`] for more information on the macro itself.
///
/// # Examples
/// ```rust
/// use enum_debug::EnumDebug;
///
/// enum Jedi {
///     ObiWanKenobi,
///     AnakinSkywalker,
///     MaceWindu,
///     MasterYoda,
/// }
/// impl EnumDebug for Jedi {
///     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
///     #[inline]
///     fn type_name() -> &'static str { "Jedi" }
///
///     #[inline]
///     fn variant_names() -> &'static [&'static str] {
///         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
///     }
///
///     #[inline]
///     fn variant_name(&self) -> &'static str {
///         match self {
///             Self::ObiWanKenobi => Self::variant_names()[0],
///             Self::AnakinSkywalker => Self::variant_names()[1],
///             Self::MaceWindu => Self::variant_names()[2],
///             Self::MasterYoda => Self::variant_names()[3],
///         }
///     }
/// }
///
/// assert_eq!(format!("{}", Jedi::ObiWanKenobi.variant()), "ObiWanKenobi");
/// assert_eq!(format!("{:?}", Jedi::AnakinSkywalker.variant()), "Jedi::AnakinSkywalker");
/// assert_eq!(Jedi::MaceWindu.variant_name(), "MaceWindu");
/// ```
pub trait EnumDebug {
    /// Returns the static name of the type used for EnumDebug-printing.
    ///
    /// # Returns
    /// A [`&'static str`](str) with the name of the current type.
    ///
    /// If you have derived this automatically, then this equals the name of the enum.
    /// See [`derive`] for some alternative ways of deriving type names.
    ///
    /// # Example
    /// ```rust
    /// use enum_debug::EnumDebug;
    ///
    /// enum Jedi {
    ///     ObiWanKenobi,
    ///     AnakinSkywalker,
    ///     MaceWindu,
    ///     MasterYoda,
    /// }
    /// impl EnumDebug for Jedi {
    ///     // e.g. derived
    /// #     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
    /// #     #[inline]
    /// #     fn type_name() -> &'static str { "Jedi" }
    /// #
    /// #     #[inline]
    /// #     fn variant_names() -> &'static [&'static str] {
    /// #         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
    /// #     }
    /// #
    /// #     #[inline]
    /// #     fn variant_name(&self) -> &'static str {
    /// #         match self {
    /// #             Self::ObiWanKenobi => Self::variant_names()[0],
    /// #             Self::AnakinSkywalker => Self::variant_names()[1],
    /// #             Self::MaceWindu => Self::variant_names()[2],
    /// #             Self::MasterYoda => Self::variant_names()[3],
    /// #         }
    /// #     }
    /// }
    ///
    /// assert_eq!(Jedi::type_name(), "Jedi");
    /// ```
    #[inline]
    fn type_name() -> &'static str { std::any::type_name::<Self>() }

    /// Returns all variants in the trait as a list of names.
    ///
    /// # Returns
    /// A static slice of [`&'static str`](str)s with the names of all variants.
    ///
    /// If you have derived this automatically, then the order is the same as defined.
    ///
    /// # Example
    /// ```rust
    /// use enum_debug::EnumDebug;
    ///
    /// enum Jedi {
    ///     ObiWanKenobi,
    ///     AnakinSkywalker,
    ///     MaceWindu,
    ///     MasterYoda,
    /// }
    /// impl EnumDebug for Jedi {
    ///     // e.g. derived
    /// #     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
    /// #     #[inline]
    /// #     fn type_name() -> &'static str { "Jedi" }
    /// #
    /// #     #[inline]
    /// #     fn variant_names() -> &'static [&'static str] {
    /// #         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
    /// #     }
    /// #
    /// #     #[inline]
    /// #     fn variant_name(&self) -> &'static str {
    /// #         match self {
    /// #             Self::ObiWanKenobi => Self::variant_names()[0],
    /// #             Self::AnakinSkywalker => Self::variant_names()[1],
    /// #             Self::MaceWindu => Self::variant_names()[2],
    /// #             Self::MasterYoda => Self::variant_names()[3],
    /// #         }
    /// #     }
    /// }
    ///
    /// assert_eq!(Jedi::variant_names(), &[
    ///     "ObiWanKenobi",
    ///     "AnakinSkywalker",
    ///     "MaceWindu",
    ///     "MasterYoda"
    /// ]);
    /// ```
    fn variant_names() -> &'static [&'static str];

    /// Returns the static name of the variant.
    ///
    /// # Returns
    /// A [`&'static str`](str) with the name of the current variant.
    ///
    /// # Example
    /// ```rust
    /// use enum_debug::EnumDebug;
    ///
    /// enum Jedi {
    ///     ObiWanKenobi,
    ///     AnakinSkywalker,
    ///     MaceWindu,
    ///     MasterYoda,
    /// }
    /// impl EnumDebug for Jedi {
    ///     // e.g. derived
    /// #     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
    /// #     #[inline]
    /// #     fn type_name() -> &'static str { "Jedi" }
    /// #
    /// #     #[inline]
    /// #     fn variant_names() -> &'static [&'static str] {
    /// #         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
    /// #     }
    /// #
    /// #     #[inline]
    /// #     fn variant_name(&self) -> &'static str {
    /// #         match self {
    /// #             Self::ObiWanKenobi => Self::variant_names()[0],
    /// #             Self::AnakinSkywalker => Self::variant_names()[1],
    /// #             Self::MaceWindu => Self::variant_names()[2],
    /// #             Self::MasterYoda => Self::variant_names()[3],
    /// #         }
    /// #     }
    /// }
    ///
    /// assert_eq!(Jedi::ObiWanKenobi.variant_name(), "ObiWanKenobi");
    /// assert_eq!(Jedi::AnakinSkywalker.variant_name(), "AnakinSkywalker");
    /// ```
    fn variant_name(&self) -> &'static str;



    /// Returns a formatter for this enum that writes its variant name.
    ///
    /// # Returns
    /// A new instance of an [`EnumDebugFormatter`] that implements [`Debug`] and [`Display`].
    ///
    /// In the former, it also includes the name of the type itself (as given by
    /// [`Self::type_name()`](EnumDebug::type_name())).
    ///
    /// # Example
    /// ```rust
    /// use enum_debug::EnumDebug;
    ///
    /// enum Jedi {
    ///     ObiWanKenobi,
    ///     AnakinSkywalker,
    ///     MaceWindu,
    ///     MasterYoda,
    /// }
    /// impl EnumDebug for Jedi {
    ///     // e.g. derived
    /// #     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
    /// #     #[inline]
    /// #     fn type_name() -> &'static str { "Jedi" }
    /// #
    /// #     #[inline]
    /// #     fn variant_names() -> &'static [&'static str] {
    /// #         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
    /// #     }
    /// #
    /// #     #[inline]
    /// #     fn variant_name(&self) -> &'static str {
    /// #         match self {
    /// #             Self::ObiWanKenobi => Self::variant_names()[0],
    /// #             Self::AnakinSkywalker => Self::variant_names()[1],
    /// #             Self::MaceWindu => Self::variant_names()[2],
    /// #             Self::MasterYoda => Self::variant_names()[3],
    /// #         }
    /// #     }
    /// }
    ///
    /// assert_eq!(format!("{}", Jedi::ObiWanKenobi.variant()), "ObiWanKenobi");
    /// assert_eq!(format!("{:?}", Jedi::AnakinSkywalker.variant()), "Jedi::AnakinSkywalker");
    /// ```
    #[inline]
    fn variant(&self) -> EnumDebugFormatter<'_, Self> { EnumDebugFormatter { e: self } }

    /// Returns an iterator over all variants in this enum.
    ///
    /// # Returns
    /// An [`Iter`](std::slice::Iter) that generates the name of the variants as defined by
    /// [`Self::variant_names()`].
    ///
    /// If you have derived this automatically, then the order is the same as defined.
    ///
    /// # Example
    /// ```rust
    /// use enum_debug::EnumDebug;
    ///
    /// enum Jedi {
    ///     ObiWanKenobi,
    ///     AnakinSkywalker,
    ///     MaceWindu,
    ///     MasterYoda,
    /// }
    /// impl EnumDebug for Jedi {
    ///     // e.g. derived
    /// #     // NOTE: Not necessary, but otherwise it will use the Rust internal type name
    /// #     #[inline]
    /// #     fn type_name() -> &'static str { "Jedi" }
    /// #
    /// #     #[inline]
    /// #     fn variant_names() -> &'static [&'static str] {
    /// #         &["ObiWanKenobi", "AnakinSkywalker", "MaceWindu", "MasterYoda"]
    /// #     }
    /// #
    /// #     #[inline]
    /// #     fn variant_name(&self) -> &'static str {
    /// #         match self {
    /// #             Self::ObiWanKenobi => Self::variant_names()[0],
    /// #             Self::AnakinSkywalker => Self::variant_names()[1],
    /// #             Self::MaceWindu => Self::variant_names()[2],
    /// #             Self::MasterYoda => Self::variant_names()[3],
    /// #         }
    /// #     }
    /// }
    ///
    /// assert_eq!(Jedi::variants().collect::<Vec<&'static str>>(), vec![
    ///     "ObiWanKenobi",
    ///     "AnakinSkywalker",
    ///     "MaceWindu",
    ///     "MasterYoda"
    /// ]);
    /// ```
    #[inline]
    fn variants() -> Copied<std::slice::Iter<'static, &'static str>> { Self::variant_names().into_iter().copied() }
}