::named-generics-bundle

Convenience macros to help with the "bundle multiple generic params with a helper trait" pattern

API summary

# use ::named_generics_bundle::named_generics_bundle;
# use Sized as SomeBounds;
#
#[named_generics_bundle]
trait SomeTrait {
    type SomeAssocType: SomeBounds + Clone;
}

fn some_api<S: SomeTrait>(nameable: S::SomeAssocType) {
    // Properly implied bounds.
    nameable.clone();
}

/// We shall have `Example: SomeTrait + Sized + AllStdDeriveTraits`
type Example = SomeTrait![
    # SomeAssocType = (), /*
    SomeAssocType = ...,
    # */
];

some_api::<Example>(
    // …,
    # (),
);
// or, directly:
some_api::<SomeTrait![SomeAssocType = i32]>(42);

Motivation

As your Rust projects grows in scope and functionality, your generic types may end up with more and more generic parameters:

# use ::core::marker::PhantomData;
# pub trait Burns {}
# enum Uranium {} impl Burns for Uranium {}
# pub trait EnergyForm {}
# enum Beam {} impl EnergyForm for Beam {}
# pub trait YieldsEnergy { fn yield_energy<E: EnergyForm>(&self, _: &mut impl Burns) -> E { todo!() } }
# enum FluxCapacitor {} impl YieldsEnergy for FluxCapacitor {}
#
#[derive(Debug)]
struct Device<Fuel, Engine, Output>
where
    Fuel: Burns,
    Engine: YieldsEnergy,
    Output: EnergyForm,
{
    fuel: Fuel,
    engine: Engine,
    _p: PhantomData<fn() -> Output>,
}

impl<Fuel, Engine, Output> Device<Fuel, Engine, Output>
where
    // 1. First problem: repeat these bounds on every usage of `Device`. So WET… 💦
    Fuel: Burns,
    Engine: YieldsEnergy,
    Output: EnergyForm,
{
    pub fn assemble(fuel: Fuel, engine: Engine) -> Self {
        Self { fuel, engine, _p: PhantomData }
    }

    pub fn frobnicate(&mut self) -> Output {
        self.engine.yield_energy(&mut self.fuel)
    }
}

fn get_away_from_the_beam() -> ! {
    // 2. Second problem: index/position-based generics "tuples"…
    //    😵‍💫 which one was going second again? 😵‍💫
    let mut device = Device::<Uranium, FluxCapacitor, Beam>::assemble(
        // …
        # todo!(), todo!(),
    );
    let beam: Beam = device.frobnicate();
    match beam {}
}

It turns out, you can make this already significantly more convenient from the point of view of the callee by using a helper trait to bundle all the generic parameters as associated types, and making the callees generic only over that helper trait.

# pub trait Burns {}
# enum Uranium {} impl Burns for Uranium {}
# pub trait EnergyForm {}
# enum Beam {} impl EnergyForm for Beam {}
# pub trait YieldsEnergy { fn yield_energy<E: EnergyForm>(&self, _: &mut impl Burns) -> E { todo!() } }
# enum FluxCapacitor {} impl YieldsEnergy for FluxCapacitor {}
#
pub trait DeviceSetup {
    //! Define your generic bounds *ONCE*. So 🌵 DRY 🐪 🌵
    type Fuel: Burns;
    type Output: EnergyForm;
    type Engine: YieldsEnergy;
}

#[derive(Debug)]
struct Device<S: DeviceSetup> {
    fuel: S::Fuel,
    engine: S::Engine,
}

impl<S: DeviceSetup> Device<S> {
    pub fn assemble(fuel: S::Fuel, engine: S::Engine) -> Self {
        Self { fuel, engine }
    }

    pub fn frobnicate(&mut self) -> S::Output {
        self.engine.yield_energy(&mut self.fuel)
    }
}

fn get_away_from_the_beam() -> ! {
    // No more index/position-based generics "tuples". Get _named_ generic entries.
    // So robust to misordering. Much readability.
    enum BlackMesaStyle {}
    impl DeviceSetup for BlackMesaStyle {
        type Fuel = Uranium;
        type Engine = FluxCapacitor;
        type Output = Beam;
    }
    let mut device = Device::<BlackMesaStyle>::assemble(
        // …
        # todo!(), todo!(),
    );
    let beam: Beam = device.frobnicate();
    match beam {}
}

This is already quite a useful trick, but it comes with certain caveats:

• The most notable one, is that you can no longer inline-turbofish the generics: it is necessary to define a helper type, and this can get unwieldy when there are outer generic parameters in scope.

• There are also some secondary issues, such as slapping #[derive(Clone)] on the struct Engine and this resulting in Output having to be clone, even though it is not part of the actual fields of Engine (it is a mere dummy PhantomData instead).

  • To be fair, this is a limitation/bug stemming from #[derive(Clone)] itself, and other similar stdlib #[derive()]s, being rather dumb w.r.t. the impls they generate, w.r.t. adding unnecessary bounds on the params themselves rather than focusing on bounding the field types (there is a desire to do the latter, called "perfect derives", but they only want to do so once all edge cases, such as recursive types, can be handled. There are also some "implicit SemVer" considerations involved as well).

  So you:

  • either make Output : Clone even if the only thing susceptible of being .clone()d is the Device,
  • or you stop using #[derive(Clone)], and manually impl the trait in question. Which is quite cumbersome! Or you involve some third-party lib to help you with that in a smarter or at least more tweakable manner than the stdlib, such as ::derivative (but this is a rather old crate, nowadays, and most people feel like it is unnecessary to add a dependency for such a small thing).

Enters this crate!

Detailed Example

# pub trait Burns {}
# enum Uranium {} impl Burns for Uranium {}
# pub trait EnergyForm {}
# enum Beam {} impl EnergyForm for Beam {}
# pub trait YieldsEnergy { fn yield_energy<E: EnergyForm>(&self, _: &mut impl Burns) -> E { todo!() } }
# enum FluxCapacitor {} impl YieldsEnergy for FluxCapacitor {}
#
#[::named_generics_bundle::named_generics_bundle] // 👈 1. Add this…
pub trait DeviceSetup {
    //! Define your generic bounds *ONCE*. So 🌵 DRY 🐪 🌵
    type Fuel: Burns;
    type Output: EnergyForm;
    type Engine: YieldsEnergy;
}

#[derive(Debug)]
struct Device<S: DeviceSetup> {
    fuel: S::Fuel,
    engine: S::Engine,
}

impl<S: DeviceSetup> Device<S> {
    pub fn assemble(fuel: S::Fuel, engine: S::Engine) -> Self {
        Self { fuel, engine }
    }

    pub fn frobnicate(&mut self) -> S::Output {
        self.engine.yield_energy(&mut self.fuel)
    }
}

fn get_away_from_the_beam() -> ! {
    // No more index/position-based generics "tuples". Get _named_ generic entries.
    // So robust to misordering. Much readability.
    type BlackMesaStyle = DeviceSetup![ // 👈 2. …so you get access to this
        Fuel = Uranium,
        Engine = FluxCapacitor,
        Output = Beam,
    ];
    let mut device = Device::<BlackMesaStyle>::assemble(
        // …
        # todo!(), todo!(),
    );
    let beam: Beam = device.frobnicate();
    match beam {}
}

# struct HandheldPortalDevice {}
# impl YieldsEnergy for HandheldPortalDevice {}
enum Cake {}
# impl EnergyForm for Cake {}
struct TestSubject {}
impl Burns for TestSubject {}

fn the_cake_is_a_lie() -> ! {
    let testing_chamber =
        // 👇 3. It can also be turbofished-inlined!
        Device::<DeviceSetup![
            Engine = HandheldPortalDevice,
            Output = Cake,
            Fuel = TestSubject,
        ]>::assemble(
            // …
            # todo!(), todo!(),
        )
    ;
    let puzzle_solved: Cake = testing_chamber.frobnicate();
    match puzzle_solved {}
}

See the docs of #[named_generics_bundle] for more info.