//! # MMM 😋
//!
//! Export tokens to other crates. Now with 100% less proc macros!
//!
//! This crate provides the [`export`] macro which allows exporting tokens.
//! The concept is similar to that used by the inspiration for this crate [macro_magic](https://docs.rs/macro_magic/latest/macro_magic/).
//! Namely, a macro_rules is generated alongside the tokens to be exported. This macro_rules will invoke a passed macro with the tokens exported. Simple as that. 
//!
//! The difference to macro_magic is that this
//! crate does it all with one `macro_rules!` macro. No more need to poll in a set of proc macros
//! if you don't need the full power of macro_magic. Instead use [`export`] to generate a 
//! macro you or a dependant can use. Also, a dependant doesn't need to know about
//! `mini_macro_magic` to use the generated macro_rules. They are fully self contained.
//!
//! ## no_std
//! `mini_macro_magic` is fully `no_std` compatible.

#![no_std]

/// Export tokens for use by other macros.
///
/// Creates a macro that injects the tokens the macro was originally invoked with.
///
/// Invoked with the following form.
/// ```ignore
/// export! {
///     <@only_export>
///
///     /// Extra docs for the generated macro can be added here.
///     <visibility> name_for_the_macro$
///
///     any rust tokens here
/// }
/// ```
///
/// Note, the `$` after the macro name must be there.
///
/// * `<@only_export>` - Modifier to disable emitting the given tokens into the local scope. Don't
/// use this if you want the exported tokens to be real code as well as exporting them.
/// * `<visibility>` - Visibility modifier. Can be nothing, `pub`, or `pub crate`. Nothing
/// will result in a macro with a `pub(crate) use` to make it visible to the local crate.
/// `pub` will make the macro visible outside of the crate usinge `#[macro_export]`. `pub crate` is
/// like `pub` but for macros defined in the root of a crate.
///
/// The generated macro_rules will have a section of docs showing the tokens it expands to (See
/// [`example::inspect_demo`]). Additionally, the macro_rules will have a doc test generated for
/// it (see [`example::inspect_demo`](example::inspect_demo#examples)).
///
/// # Examples
/// 
/// ## No `#[macro_export]`
///
/// ```
/// mod inner {
///     use mini_macro_magic::export;
///
///     export! {
///         /// Inspect demo struct.
///         inspect_demo$
///
///         /// Demo struct for inspection.
///         pub struct Demo {
///             pub x: i32,
///             pub y: i32,
///         }
///     }
/// }
///
/// macro_rules! first_token {
///     ($first:tt $($t:tt)*) => {
///         stringify!($first)
///     }
/// }
///
/// type Demo = inner::Demo;
///
/// let first = inner::inspect_demo!(first_token);
///
/// assert_eq!(first, "#");
/// ```
///
/// ## With `#[macro_export]` at crate root
///
/// ```
/// use mini_macro_magic::export;
///
/// export! {
///     /// Inspect demo struct.
///     pub crate inspect_demo$
///
///     /// Demo struct for inspection.
///     pub struct Demo {
///         pub x: i32,
///         pub y: i32,
///     }
/// }
///
/// macro_rules! first_token {
///     ($first:tt $($t:tt)*) => {
///         stringify!($first)
///     }
/// }
///
/// type OtherDemo = Demo;
///
/// let first = inspect_demo!(first_token);
///
/// assert_eq!(first, "#");
/// ```
///
/// ## With `#[macro_export]` in module
///
/// ```
/// mod inner {
///     use mini_macro_magic::export;
///
///     export! {
///         /// Inspect demo struct.
///         pub inspect_demo$
///
///         /// Demo struct for inspection.
///         pub struct Demo {
///             pub x: i32,
///             pub y: i32,
///         }
///     }
/// }
///
/// macro_rules! first_token {
///     ($first:tt $($t:tt)*) => {
///         stringify!($first)
///     }
/// }
///
/// type Demo = inner::Demo;
///
/// let first = inner::inspect_demo!(first_token);
///
/// assert_eq!(first, "#");
/// ```
///
/// ## Just export
///
/// ```
/// use mini_macro_magic::export;
///
/// export! {
///     @only_export
///
///     /// Inspect demo struct.
///     pub crate inspect_tokens$
///
///     just some tokens to export
/// }
///
/// macro_rules! first_token {
///     ($first:tt $($t:tt)*) => {
///         stringify!($first)
///     }
/// }
///
/// let first = inspect_tokens!(first_token);
///
/// assert_eq!(first, "just");
/// ```
///
#[macro_export]
macro_rules! export {
    ($(#[$($a:tt)*])* pub crate $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            #[macro_export]
            $name $dollar

            {}

            {$($t)*}
            {$($t)*}
        );
    };
    ($(#[$($a:tt)*])* pub $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            #[doc(hidden)]
            #[macro_export]
            $name $dollar

            {
                #[doc(inline)]
                pub use $name;
            }

            {$($t)*}
            {$($t)*}
        );
    };
    ($(#[$($a:tt)*])* $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            $name $dollar

            {
                pub(crate) use $name;
            }

            {$($t)*}
            {$($t)*}
        );
    };
    (@only_export $(#[$($a:tt)*])* pub crate $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            #[macro_export]
            $name $dollar

            {}

            {$($t)*}
            {}
        );
    };
    (@only_export $(#[$($a:tt)*])* pub $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            #[doc(hidden)]
            #[macro_export]
            $name $dollar

            {
                #[doc(inline)]
                pub use $name;
            }

            {$($t)*}
            {}
        );
    };
    (@only_export $(#[$($a:tt)*])* $name:ident $dollar:tt $($t:tt)*) => {
        $crate::export!(
            @helper

            $(#[$($a)*])*
            $name $dollar

            {
                pub(crate) use $name;
            }

            {$($t)*}
            {}
        );
    };
    (@helper $(#[$($a:tt)*])* $name:ident $dollar:tt {$($e:tt)*} {$first:tt $($t:tt)*} {$($i:tt)*}) => {
        $(#[$($a)*])*
        ///
        /// Calls the provided macro with the exported tokens.
        ///
        /// <details>
        /// <summary>Expand to show exported tokens</summary>
        ///
        /// ```
        #[doc = stringify!($first $($t)*)]
        /// ```
        ///
        /// </details>
        ///
        /// # Examples
        ///
        /// ```
        #[doc = concat!("use ", module_path!(), "::", stringify!($name), ";")]
        ///
        /// macro_rules! first_token {
        ///     ($first:tt $($t:tt)*) => {
        ///         stringify!($first)
        ///     }
        /// }
        ///
        #[doc = concat!("let first = ", stringify!($name), "!(first_token);")]
        ///
        #[doc = concat!("assert_eq!(first, \"", stringify!($first), "\");")]
        /// ```
        macro_rules! $name {
            ($dollar ($dollar m:tt)*) => {
                $dollar ($dollar m)*!($first $($t)*)
            }
        }

        $($e)*
        
        $($i)*
    };
}

/// Example of using [`export`]. (This module is not part of the crate's public API)
///
/// Code used for this module:
/// ```
/// pub mod example {
///     use mini_macro_magic::export;
///     
///     export! {
///         /// Inspect demo struct.
///         pub inspect_demo$
///
///         /// Demo struct for inspection.
///         pub struct Demo {
///             /// The X value.
///             pub x: i32,
///
///             /// The Y value.
///             pub y: i32,
///         }
///     }
/// }
/// ```
///
/// [`Demo`](example::Demo) is a struct definition exported by [`export`].
/// As you can see it exists as expected as a normal struct.
///
/// [`inspect_demo`] is the inspection macro that was generated by [`export`].
/// This is the macro you would call to inspect the tokens of [`Demo`](example::Demo).
#[cfg(any(doc, doc_example))]
pub mod example {
    export! {
        /// Inspect demo struct.
        pub inspect_demo$

        /// Demo struct for inspection.
        pub struct Demo {
            /// The X value.
            pub x: i32,

            /// The Y value.
            pub y: i32,
        }
    }
}