ty_tag/

lib.rs

//! Not all types in Rust are `'static`. Meaning they can't be used with [`core::any::TypeId`].
//! However, it is often useful to be able to name a lifetime containing type via a `'static`
//! type. Most implementations go about this by using the same type with all the lifetimes
//! replaced by `'static`. So for example `&'a [u8]` would be named by `&'static [u8]`. These
//! implementations suffer from some limitations. One being that they are usually limited to
//! a single lifetime `'a`.
//!
//! This crate takes a different approach to solve this issue. We introduce the idea of tags.
//! A tag is an arbitrary type with an associated lifetime containing type. So for the `&'a [u8]`
//! example we would have a `struct SliceU8;` with the `&'a [u8]` as an associated type.
//! You may notice that by itself this has an issue. We somehow need to get a `'a` to actually
//! write the `&'a [u8]` associated type. The lifetime can't live on the `SliceU8` because we
//! need that to be `'static`.
//!
//! We solve this by injecting the lifetime `'a` in an operation called reification. This operation
//! combines a tag type and some number of lifetimes into the lifetime containing type. So
//! `SliceU8` + `'a` reifies to `&'a [u8]`. Combining this with a way to get a tag type from a
//! lifetime containing type, we gain the ability to go full circle from a lifetime containing type
//! to a `'static` type back to the lifetime containing type.
//!
//! In this crate a tag type is defined to be a type that implements both [`Tag`] and [`WithLt`].
//! These types automatically gain the [`Reify`] operation for constructing the lifetime containing
//! type they name. Any type can have a tag associated with it via the [`Tagged`]
//! trait. Note, [`Tagged`] does not require the associated tag to name the `Self` type. This
//! is a useful property but may be unintuitive.
//!
//! ```
//! # #[cfg(all(feature = "macros", feature = "core"))]
//! # fn run() {
//! use ty_tag::{tag, TagOf, Reify, l};
//!
//! // Check that the tag of &str is a 'static type.
//! is_static::<TagOf<&str>>();
//!
//! // Introduce an arbitrary lifetime 'a.
//! fn with_lt<'a>() {
//!     // Combine the tag of &str with lifetime 'a to form the &'a str lifetime containing type.
//!     reify::<'a, TagOf<&str>, &'a str>();
//! }
//! with_lt();
//!
//! fn reify<'a, T: Reify<l!['a], Reified = U>, U>() {}
//!
//! fn is_static<T: 'static>() {}
//! # }
//! # #[cfg(all(feature = "macros", feature = "core"))]
//! # run();
//! ```
//!
//! Another concept this crate introduces is that of a tag group. Because of Rust's coherence rules
//! we are limited in our ability to implement [`Tagged`] for types outside a user's crate. To work
//! around this we use tag groups like [`DefaultGroup`] to allow a user to bypass the coherence
//! rules by naming a type they control. This functionality is not used within this crate, but
//! is designed to improve the ergonomics of other crates.
//!
//! ## Crate features
#![cfg_attr(
    feature = "document-features",
    doc = ::document_features::document_features!()
)]
//!
//! ## `no_std` Support
//!
//! This crate is `#![no_std]` by default, it can be used anywhere Rust can.
//!
//! ## Minimum Supported Rust Version
//!
//! Requires Rust 1.83.0.
//!
//! This crate follows the ["Latest stable Rust" policy](https://gist.github.com/alexheretic/d1e98d8433b602e57f5d0a9637927e0c). The listed MSRV won't be changed unless needed.
//! However, updating the MSRV anywhere up to the latest stable at time of release
//! is allowed.

// no_std by default.
#![cfg_attr(not(any(feature = "std", test)), no_std)]
// Only some convenience methods of Label need unsafe.
#![cfg_attr(not(feature = "unsafe"), forbid(unsafe_code))]
// On docs.rs we show the cfg requirements in the docs.
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
// Why not? The module name repetitions does flag a few spots where the modules aren't public.
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]

// If the alloc feature is enabled we need to depend on the alloc crate.
#[cfg(any(feature = "alloc", test))]
extern crate alloc;

pub mod lifetime_list;

// We only need this module if one of the features is enabled.
#[cfg(any(feature = "core", feature = "alloc", feature = "std"))]
pub mod external_tags;

pub mod modifiers;

mod tag_type_id;

use lifetime_list::ops::{FirstNLifetimes, Prefix, ToHoleList};
use lifetime_list::{HoleList, LifetimeList, L0};
pub use tag_type_id::TagTypeId;
/// Create a tag for a type.
///
/// Tags use the same syntax as type aliases.
///
/// ```
/// use ty_tag::tag;
///
/// struct MyType<'a, T: 'a, const N: usize>(&'a [T; N]);
///
/// #[tag]
/// type MyTag<'a, T: 'a, const N: usize> = MyType<'a, T, N>;
/// ```
///
/// `MyTag` will be converted to a type without the lifetime parameter `'a`.
/// This type can then be used anywhere a [`Tagged`] implementing type is needed.
/// The tag will reify to `&'a [T; N]` when the lifetime `'a` is added.
///
/// ## Option `remote`
///
/// The `remote` option can be included to remove the implementation of [`Tagged`]
/// for the type in the [`DefaultGroup`] group. This is needed if the type
/// is not considered local under the orphan rules.
///
/// ```
/// use ty_tag::tag;
///
/// // error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate
/// // #[tag]
/// // type Tag = u8;
///
/// #[tag(remote)]
/// type Tag = u8;
/// ```
///
/// ## Option `group = ...`
///
/// Option to tag the type in a group. This can be used to implement [`Tagged`] for a type
/// even if it's not local. The group type can be anything; There are no required traits for it.
///
/// ```
/// use ty_tag::tag;
///
/// struct MyGroup;
///
/// struct MyType;
///
/// #[tag(remote, group = MyGroup)]
/// type Tag = MyType;
/// ```
///
/// ## Attribute `itself`
///
/// By default, generic types will use [`Tagged`] to lookup a tag for them. However, this may not
/// always be wanted. Instead, if the generic is `'static`, then `#[itself]` can be added to the
/// generic type to use the generic type as the tag directly.
///
/// ```
/// use ty_tag::{tag, TagOf};
///
/// struct MyType<T>(T);
///
/// struct NotTagged;
///
/// #[tag]
/// type Tag<#[itself] T: 'static> = MyType<T>;
///
/// let _example: TagOf<Tag<NotTagged>>;
/// ```
#[cfg(feature = "macros")]
pub use ty_tag_macros::tag;

/// Get the associated [`Tagged::Tag`] of `T`.
pub type TagOf<T, Group = DefaultGroup> = <T as Tagged<Group>>::Tag;

// This is used by the tag macro to prevent constructing a tag struct.
#[doc(hidden)]
pub enum __ {}

// Needed for the tag macro to work within this crate.
extern crate self as ty_tag;

/// The default tag group.
///
/// All tag types are themselves always tagged within this default group.
/// Most APIs will default to this group.
pub struct DefaultGroup(());

/// `Self` is tagged in `Group`.
///
/// Prefer using the [`tag`] macro over implementing this manually.
/// When implementing this trait, it is recommended to implement for all `Group: ?Sized`.
/// This is possible when the `Self` type is local. When it is not local then a specific
/// local group type can be used instead.
///
/// Instead of using this trait directly, [`TagOf`] can be used to get the `Tag` associated type.
/// Additionally, most uses should bound by [`Reify`] instead. `Reify` includes [`Tagged`] as
/// a super trait.
pub trait Tagged<Group: ?Sized = DefaultGroup> {
    /// The tag for `Self` within the group `Group`.
    type Tag: Tag;
}

/// A tag for a type.
///
/// Tags can be for types with an arbitrary number of lifetimes.
/// The number of lifetimes in the tagged type is described by the
/// [`Tag::NeededLifetimes`] associated type.
///
/// For a tag to be complete, it needs to implement [`WithLt`] which defines
/// which type the tag is for. Once a tag implements both [`Tag`] and [`WithLt`]
/// then it will also implement [`Reify`] which can be used to reify the tag into
/// the type it is for.
///
/// Tags are also required to tag themselves within the [`DefaultGroup`] group.
/// This requirement allows for some extra ergonomics.
pub trait Tag: Sized + Tagged<DefaultGroup, Tag = Self> + 'static {
    /// The needed lifetimes by the tagged type.
    type NeededLifetimes: HoleList;
}

/// The reified type for a tag.
///
/// All tag types are required to implement this trait to be complete.
/// Once a tag implements both [`Tag`] and [`WithLt`]
/// then it will also implement [`Reify`] which can be used to reify the tag into
/// the type it is for.
///
/// The `L` generic allows an arbitrary number of lifetime to be used to construct the
/// [`WithLt::Reified`] type.
// I wish the commented out bound was here but it causes a infinite loop resolving the Reify
// bounds.
pub trait WithLt<L: LifetimeList>: Tag {
    /// The type tagged.
    type Reified: ?Sized;
}

/// Type level operation to reify a tag into it's associated type.
///
/// **Do not** attempt to implement this manually.
/// This trait is implemented on anything that implements [`Tagged`] with a valid tag.
///
/// The `L` generic is some list of lifetimes to combine with the tag to form the reified type.
/// By default, it is a list with no lifetimes.
/// The lifetime list length does not need to match that of the tag. The first N lifetimes
/// of the list will be used in the reify operation.
///
/// For most uses, the default `Group` of [`DefaultGroup`] will be enough. In cases where
/// `Self` is expected to be tagged by another group it can be changed.
///
/// The extra associated types are provided to reduce the needed trait
/// bounds for some usages. They fully connect the tag with the reified
/// type in a self consistent way.
///
/// # Examples
///
/// ```
/// # #[cfg(all(feature = "macros", feature = "core"))]
/// # fn run() {
/// use ty_tag::{tag, TagOf, Reify, l};
///
/// fn with_lt<'a>() {
///     // Combine the tag of &str with lifetime 'a to form the &'a str lifetime containing type.
///     reify::<'a, TagOf<&str>, &'a str>();
///
///     // The type itself also (usually) works with Reify.
///     reify::<'a, &'static str, &'a str>();
///
///     // Even the lifetime containing form can be used.
///     reify::<'static, &'a str, &'static str>();
/// }
/// with_lt();
///
/// fn reify<'a, T: Reify<l!['a], Reified = U>, U>() {}
/// # }
/// # #[cfg(all(feature = "macros", feature = "core"))]
/// # run();
/// ```
///
pub trait Reify<L: LifetimeList = L0, Group: ?Sized = DefaultGroup>:
    Tagged<Group, Tag = Self::UsedTag>
{
    /// The reified type.
    ///
    /// This is taken from the tag's [`WithLt`] implementation.
    type Reified: ?Sized;

    /// The lifetimes used to reify the type.
    ///
    /// This will be some prefix of the full `L` list of lifetimes.
    type Lifetimes: LifetimeList + ToHoleList<HoleList = Self::UsedNeededLifetimes> + Prefix<L>;

    /// The tag used for the reification.
    ///
    /// [`Reify`] is implemented on anything with an implementation of [`Tagged`].
    /// This type is the [`Tagged::Tag`].
    type UsedTag: Tag<NeededLifetimes = Self::UsedNeededLifetimes>
        + WithLt<Self::Lifetimes, Reified = Self::Reified>;

    /// The needed lifetimes from the tag.
    ///
    /// This is the [`Tag::NeededLifetimes`] of [`Tagged::Tag`]. It is also the same length as the
    /// [`Reify::Lifetimes`] list.
    type UsedNeededLifetimes: FirstNLifetimes<Self::Lifetimes, Output = Self::Lifetimes>
        + FirstNLifetimes<L, Output = Self::Lifetimes>
        + HoleList;
}

/// [`Reify`] but with a [`Sized`] `Reified`.
///
/// Because a `Sized` time is often expected this trait can be used instead
/// to reduce the amount of bounds needed at the usage site.
///
/// This trait is automatically implemented for all types it can be.
pub trait ReifySized<L: LifetimeList, Group: ?Sized = DefaultGroup>:
    Reify<L, Group, Reified = Self::SizedReified>
{
    /// Same as [`Reify::Reified`].
    type SizedReified;
}

impl<L: LifetimeList, Group: ?Sized, T> ReifySized<L, Group> for T
where
    T: Reify<L, Group>,
    T::Reified: Sized,
{
    type SizedReified = <T as Reify<L, Group>>::Reified;
}

/// Types that reify to themselves.
///
/// Some tags have a special property; They are tagged and that tag reifies by [`Reify`] to
/// that same type. This makes that one tag unique. As a result that tag can be used as a true
/// unique name of the type containing lifetimes.
///
/// This trait is automatically implemented for all types it can be.
pub trait ReifySelf<L: LifetimeList = L0>: Reify<L, Reified = Self> {}

impl<L: LifetimeList, T: ?Sized> ReifySelf<L> for T where T: Reify<L, Reified = Self> {}

// Some helpers for the impl below.
type NeededLt<T> = <T as Tag>::NeededLifetimes;
type TakeLt<H, L> = <H as FirstNLifetimes<L>>::Output;

// This is the core impl of the crate.
//
// It combines anything implementing `Tagged` and a lifetime list of arbitrary length
// to form the reified type named by the tag used in the tagged impl.
//
// Doing the FirstNLifetimes stuff here removes a lot of extra bounds from the WithLt trait impls.
impl<T, L, Group: ?Sized> Reify<L, Group> for T
where
    // T is some type with an associated tag. The reified type may or may not actually be T.
    // In any case the lifetimes T may contain will be replaced by the ones in L.
    T: ?Sized + Tagged<Group>,

    // A list of lifetime to use to reify the type named by the tag.
    L: LifetimeList,

    // We need to be able to take the lifetimes needed by the tag from L.
    NeededLt<T::Tag>: FirstNLifetimes<L>,

    // This bound makes it so we can use the subset of lifetimes from the above abound
    // to do the same thing. This bound should be trivial in practice since we have strong
    // knowledge of what L could be.
    NeededLt<T::Tag>:
        FirstNLifetimes<TakeLt<NeededLt<T::Tag>, L>, Output = TakeLt<NeededLt<T::Tag>, L>>,

    // The tag needs to have WithLt with the lifetime list the tag said it needed.
    T::Tag: WithLt<TakeLt<NeededLt<T::Tag>, L>>,
{
    // Reify the type using the subset of L.
    type Reified = <T::Tag as WithLt<TakeLt<NeededLt<T::Tag>, L>>>::Reified;

    // The subset of L that was used.
    type Lifetimes = TakeLt<NeededLt<T::Tag>, L>;

    // The tag.
    type UsedTag = T::Tag;

    // The lifetimes the tag needed.
    type UsedNeededLifetimes = NeededLt<T::Tag>;
}