pretty_name/

lib.rs

#![doc = include_str!("../README.md")]

mod type_name;
pub use type_name::type_name;
pub use type_name::type_name_of_val;

/// Internal helper macro for caching string results in thread-local storage.
///
/// This macro wraps an expression that produces a `String` and caches it as a
/// `&'static str` using thread-local `LazyCell`. Each unique macro invocation
/// gets its own cache entry, ensuring zero runtime overhead after first use.
#[doc(hidden)]
#[macro_export]
macro_rules! __with_cache {
    ($expr:expr) => {{
        use std::cell::LazyCell;
        thread_local! {
            static CACHE: LazyCell<&'static str> =
                LazyCell::new(|| {
                    let result = $expr;
                    Box::leak(result.into_boxed_str())
                });
        }
        CACHE.with(|cell| *LazyCell::force(cell))
    }};
}

/// Get the name of the given local variable or constant as a string literal.
/// 
/// This macro checks that the identifier is valid in the current scope. If the identifier
/// is renamed via refactoring tools, the macro call will be updated accordingly.
/// 
/// # Examples
/// ```rust
/// let my_variable = 42;
/// const MY_CONSTANT: u32 = 42;
/// assert_eq!(pretty_name::of_var!(my_variable), "my_variable");
/// assert_eq!(pretty_name::of_var!(MY_CONSTANT), "MY_CONSTANT");
/// ```
#[macro_export]
macro_rules! of_var {
    ($ident:ident) => {{
        let _ = &$ident;
        stringify!($ident)
    }};
}

/// Get the name of the given function.
///
/// Use `::<..>` syntax to exclude generic parameters in the output, see examples.
///
/// This macro returns `&'static str`. It caches the result and subsequent calls have
/// zero runtime overhead.
///
/// This macro checks that the identifier is valid in the current scope. If the identifier
/// is renamed via refactoring tools, the macro call will be updated accordingly.
/// 
/// # Examples
/// ```rust
/// fn my_function() {}
/// fn my_generic_function<T>() {}
/// fn my_generic_function_2args<T, U>() {}
/// assert_eq!(pretty_name::of_function!(my_function), "my_function");
/// assert_eq!(pretty_name::of_function!(my_generic_function::<..>), "my_generic_function");
/// assert_eq!(pretty_name::of_function!(my_generic_function::<u32>), "my_generic_function::<u32>");
/// assert_eq!(pretty_name::of_function!(my_generic_function_2args::<..>), "my_generic_function_2args");
/// assert_eq!(pretty_name::of_function!(my_generic_function_2args::<u32, String>), "my_generic_function_2args::<u32, String>");
/// ```
#[macro_export]
macro_rules! of_function {
    // IMPLEMENTATION NOTE:
    //   - The $ident arm magically handles auto-completion for the other arms,
    //     especially for the $ident::<..> arm.
    //   - The $ident::<..> arm adopts an unusual approach for identifier validation
    //     by using `use $ident;`. This works because functions can be imported, but
    //     lacks auto-completion support in VSCode and other editors. This means that
    //     currently we cannot use this approach for the general case.
    ($ident:ident) => {{
        let _ = &$ident;
        stringify!($ident)
    }};
    ($ident:ident ::<..>) => {{
        #[allow(unused)] use $ident;
        stringify!($ident)
    }};
    ($ident:ident ::<$($arg:ty),*>) => {{
        let _ = &$ident::<$($arg),*>;
        $crate::__with_cache!(
            format!(
                "{}::<{}>",
                stringify!($ident),
                vec![$($crate::type_name::<$arg>()),*].join(", ")))
    }};
}

/// Get the name of the given struct field like `Type::field` as `&'static str`.
///
/// This macro returns `&'static str`. It caches the result and subsequent calls have
/// zero runtime overhead.
///
/// This macro resolves `Self` to the appropriate type when used inside an `impl` block.
///
/// By default, this macro expects a simple type identifier like `Type::field`. To use
/// types with qualified path or generic parameters, wrap the type in angle brackets
/// like `<Type<T>>::field` or `<module::Type>::field`.
///
/// This macro checks that the field exists on the given type. If either the type or field
/// is renamed via refactoring tools, the macro call will be updated accordingly.
/// 
/// # Examples
/// ```rust
/// struct MyStruct {
///     my_field: u32,
/// }
/// struct MyGenericStruct<T> {
///     my_field: T,
/// }
/// assert_eq!(pretty_name::of_field!(MyStruct::my_field), "MyStruct::my_field");
/// assert_eq!(pretty_name::of_field!(<MyGenericStruct<u32>>::my_field), "<MyGenericStruct<u32>>::my_field");
/// ```
#[macro_export]
macro_rules! of_field {
    ($ty:ident :: $field:ident) => {{
        let _ = |obj: $ty| { let _ = &obj.$field; };
        $crate::__with_cache!(
            format!("{}::{}", $crate::type_name::<$ty>(), stringify!($field)))
    }};
    (<$ty:ty> :: $field:ident) => {{
        let _ = |obj: $ty| { let _ = &obj.$field; };
        $crate::__with_cache!(
            format!("<{}>::{}", $crate::type_name::<$ty>(), stringify!($field)))
    }};
}

/// Get the name of the given method as `&'static str`.
///
/// This macro returns `&'static str`. It caches the result and subsequent calls have
/// zero runtime overhead.
///
/// This macro resolves `Self` to the appropriate type when used inside an `impl` block.
///
/// By default, this macro expects a simple type identifier like `Type::field`. To use
/// types with qualified path or generic parameters, wrap the type in angle brackets
/// like `<Type<T>>::field` or `<module::Type>::field`.
///
/// This macro checks that the method exists on the given type. If either the type or method
/// is renamed via refactoring tools, the macro call will be updated accordingly.
///
/// Due to implementation limitations, you cannot use `::<..>` syntax to exclude generic
/// parameters. Use explicit type arguments instead.
/// 
/// # Examples
/// ```rust
/// struct MyStruct;
/// impl MyStruct {
///     fn my_method(&self) {}
///     fn my_generic_method<T>(&self) {}
/// }
/// struct MyGenericStruct<T>(std::marker::PhantomData<T>);
/// impl<T> MyGenericStruct<T> {
///     fn my_method(&self) {}
///     fn my_generic_method<U>(&self) {}
/// }
/// assert_eq!(pretty_name::of_method!(MyStruct::my_method), "MyStruct::my_method");
/// assert_eq!(pretty_name::of_method!(MyStruct::my_generic_method::<u32>), "MyStruct::my_generic_method::<u32>");
/// assert_eq!(pretty_name::of_method!(<MyGenericStruct<u32>>::my_method), "<MyGenericStruct<u32>>::my_method");
/// assert_eq!(pretty_name::of_method!(<MyGenericStruct<u32>>::my_generic_method::<String>), "<MyGenericStruct<u32>>::my_generic_method::<String>");
/// ```
#[macro_export]
macro_rules! of_method {
    ($ty:ident :: $method:ident) => {{
        let _ = &$ty::$method;
        $crate::__with_cache!(
            format!("{}::{}", $crate::type_name::<$ty>(), stringify!($method)))
    }};
    ($ty:ident :: $method:ident ::<$($arg:ty),*>) => {{
        let _ = &$ty::$method::<$($arg),*>;
        $crate::__with_cache!(
            format!(
                "{}::{}::<{}>",
                $crate::type_name::<$ty>(),
                stringify!($method),
                vec![$($crate::type_name::<$arg>()),*].join(", ")))
    }};

    (<$ty:ty> :: $method:ident) => {{
        let _ = &<$ty>::$method;
        $crate::__with_cache!(
            format!("<{}>::{}", $crate::type_name::<$ty>(), stringify!($method)))
    }};
    (<$ty:ty> :: $method:ident ::<$($arg:ty),*>) => {{
        let _ = &<$ty>::$method::<$($arg),*>;
        $crate::__with_cache!(
            format!(
                "<{}>::{}::<{}>",
                $crate::type_name::<$ty>(),
                stringify!($method),
                vec![$($crate::type_name::<$arg>()),*].join(", ")))
    }};
}

/// Get the name of the given enum variant as `&'static str`.
///
/// This macro returns `&'static str`. It caches the result and subsequent calls have
/// zero runtime overhead.
///
/// This macro resolves `Self` to the appropriate type when used inside an `impl` block.
///
/// This macros supports both unit variants, tuple variants and struct variants. See
/// examples for syntax for each variant type.
///
/// This macro checks that the variant exists on the given enum type. If either the type or
/// variant is renamed via refactoring tools, the macro call will be updated accordingly.
///
/// This macro currently expects only simple type identifiers like `Type::field`.
/// Support for more complex types requires the experimental feature `more_qualified_paths`
/// (issue #86935 <https://github.com/rust-lang/rust/issues/86935>) to be stabilized.
/// 
/// # Examples
/// ```rust
/// enum MyEnum {
///     UnitVariant,
///     TupleVariant(u32, String),
///     StructVariant { field: u32 },
/// }
/// assert_eq!(pretty_name::of_variant!(MyEnum::UnitVariant), "MyEnum::UnitVariant");
/// assert_eq!(pretty_name::of_variant!(MyEnum::TupleVariant(..)), "MyEnum::TupleVariant");
/// assert_eq!(pretty_name::of_variant!(MyEnum::StructVariant {..}), "MyEnum::StructVariant");
/// ```
#[macro_export]
macro_rules! of_variant {
    ($ty:ident $(::<$($ty_arg:ty),*>)? :: $variant:ident) => {{
        let _ = |obj| match obj { $ty $(::<$($ty_arg),*>)?::$variant => {}, _ => {} };
        $crate::__with_cache!(
            format!("{}::{}", $crate::type_name::<$ty $(::<$($ty_arg),*>)?>(), stringify!($variant)))
    }};
    ($ty:ident $(::<$($ty_arg:ty),*>)? :: $variant:ident (..)) => {{
        let _ = |obj| match obj { $ty $(::<$($ty_arg),*>)?::$variant(..) => {}, _ => {} };
        $crate::__with_cache!(
            format!("{}::{}", $crate::type_name::<$ty $(::<$($ty_arg),*>)?>(), stringify!($variant)))
    }};
    ($ty:ident $(::<$($ty_arg:ty),*>)? :: $variant:ident {..}) => {{
        let _ = |obj| match obj { $ty $(::<$($ty_arg),*>)?::$variant { .. } => {}, _ => {} };
        $crate::__with_cache!(
            format!("{}::{}", $crate::type_name::<$ty $(::<$($ty_arg),*>)?>(), stringify!($variant)))
    }};

    (<$ty:ty> :: $variant:ident) => {{
        let _ = |obj| match obj { <$ty>::$variant => {}, _ => {} };
        $crate::__with_cache!(
            format!("<{}>::{}", $crate::type_name::<$ty>(), stringify!($variant)))
    }};
    (<$ty:ty> :: $variant:ident (..)) => {{
        let _ = |obj| match obj { <$ty>::$variant(..) => {}, _ => {} };
        $crate::__with_cache!(
            format!("<{}>::{}", $crate::type_name::<$ty>(), stringify!($variant)))
    }};
    (<$ty:ty> :: $variant:ident {..}) => {{
        let _ = |obj| match obj { <$ty>::$variant { .. } => {}, _ => {} };
        $crate::__with_cache!(
            format!("<{}>::{}", $crate::type_name::<$ty>(), stringify!($variant)))
    }};
}