SpireEnum

A self-proclaimed enum-macro suite for Rust, providing several macros that aim to make enums great again. (they never stopped being great, but I needed a punchline)

• #[delegated_enum]: Placed on enums, generates a declarative macro that allows you to delegate impls for your enum in a single line. , and/or allows extracting variant types.

• #[delegated_impl]: Placed on impl blocks, works in conjunction with #[delegated_enum] to generate your enum's delegated impls.

• #[variant_type_table]: Place on enums, generates a table type that holds exactly one of each of the enums's variants, as well as several useful implementations for that type.

• #[variant_generic_table]: Place on enums, works similarly to #[variant_type_table], except each value on the table is of a generic parameter instead of the variant's type.

• #[discriminant_generic_table]: Place on enums, works similarly to #[variant_generic_table], except this is meant for enums with unit variants, accessing the values is used by indexing with the enum variant itself(instead of the variant's type).

• For more info on the table macros, see each macro's documentation.

• For more info on #[delegated_enum] and #[delegated_impl], keep reading this file.

Table of Contents

• Showcase: What is a delegate enum?
• Key Features
• Overview
• Alternatives
• Usage
  • 1. #[delegated_enum] (Enum attribute macro)
    • 1.1 Basic Usage
    • 1.2 Conversion Settings
      • 1.2.1 impl_conversions
      • 1.2.2 impl_enum_try_into_variants
      • 1.2.3 impl_variants_into_enum
    • 1.3 Variant Types Generation
      • 1.3.1 extract_variants
      • 1.3.2 extract_variants( attrs(attribute_list) )
      • 1.3.3 extract_variants( derive(trait_list) )
  • 2. #[delegate_impl] (Inherent/Trait impl attribute macro)
    • 2.1 Associated Types, Constants and Static Functions
  • 3. Variant Attributes
    • 3.1 #[dont_impl_conversions] / #[dont_extract] (Variant attributes)
    • 3.2 #[delegate_via(|var| var.foo())] (Variant attribute)
    • 3.3 #[delegator] (Variant field attribute)
• Example: Basic Usage
• Example: State Machine
• Troubleshooting
• Performance
• Contributing

Showcase: What is a delegate enum?

A "delegate enum" is a common pattern where an enum is created to represent possible types that implement a certain trait.

Example

You're implementing a state machine for a turret in your video game:

// Trait that defines what every state should do.
trait IState {
    fn enter(&mut self, turret_body: &mut TurretBody);
    fn exit(self, turret_body: &mut TurretBody);

    /// Returns new state, if changed.
    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State>;
}

// Some state types
#[derive(Serialize, Deserialize)]
struct Idle {
    time_spent: f64,
}

#[derive(Serialize, Deserialize)]
struct Aiming {
    target_id: usize,
}

#[derive(Serialize, Deserialize)]
struct ChargingShot {
    progress: f64,
    shot_type: ShotType,
}

#[derive(Serialize, Deserialize)]
struct CoolingDown {
    time_remaining: f64,
}

// Their impls 
impl IState for Idle { /* ... */ }
impl IState for Aiming { /* ... */ }
impl IState for ChargingShot { /* ... */ }
impl IState for CoolingDown { /* ... */ }

// Now you need some type to store which state a given Turret currently is on.
// The first thing that may come to mind is to simply put it in a `Box<dyn IState>`, but that introduces some problems:
// 
// - Serializing cannot be easily done by just deriving `serde::Serialize`, you need to resort to something like [typetag](https://crates.io/crates/typetag).
// - You lose *some* performance: `dyn` uses dynamic dispatch, and you now need to box your states when storing them.
// 
// In this case, you know all possible variants of a state at compile time, so you could just store those in an enum:
#[derive(Serialize, Deserialize)] // Serialization is very straightforward
enum State {
    Idle(Idle),
    Aiming(Aiming),
    ChargingShot(ChargingShot),
    CoolingDown(CoolingDown),
}

// All good so far, but then, in your main function:

fn main() {
    let mut turrets = some_collection_data_structure();

    while let Some(delta_time) = tick_game_internals() {
        // We want to call tick on the state of every turret.
        for Turret { body, state } in &mut turrets {
            let transition = match state {
                State::Idle(var) => var.tick(body, delta_time),
                State::Aiming(var) => var.tick(body, delta_time),
                State::ChargingShot(var) => var.tick(body, delta_time),
                State::CoolingDown(var) => var.tick(body, delta_time),
            };

            if let Some(new_state) = transition {
                // Exit old state
                let old_state = std::mem::replace(state, new_state);
                match old_state {
                    State::Idle(var) => var.exit(body),
                    State::Aiming(var) => var.exit(body),
                    State::ChargingShot(var) => var.exit(body),
                    State::CoolingDown(var) => var.exit(body),
                }

                // Enter new state
                match state {
                    State::Idle(var) => var.enter(body),
                    State::Aiming(var) => var.enter(body),
                    State::ChargingShot(var) => var.enter(body),
                    State::CoolingDown(var) => var.enter(body),
                }
            }
        }
    }
}

You can imagine how verbose this gets, you need to match on all the variants, every-single-time, even if you want to call a method that every variant has.

spire_enum can help this case in multiple ways.

First, we can generate those big match statements for you, which you replace by calling the generated delegate_state! macro:

use spire_enum::prelude::delegated_enum;

#[delegated_enum]
#[derive(Serialize, Deserialize)]
enum State {
    Idle(Idle),
    Aiming(Aiming),
    ChargingShot(ChargingShot),
    CoolingDown(CoolingDown),
}

// Your main function turns into:
fn main() {
    let mut turrets = some_collection_data_structure();

    while let Some(delta_time) = tick_game_internals() {
        // We want to call tick on the state of every turret.
        for Turret { body, state } in &mut turrets {
            // If you want to understand how the generated macro `delegate_state!` works, check the section "1.1 Basic Usage".
            let transition = delegate_state! { state.tick(body, delta_time) };

            if let Some(new_state) = transition {
                // Exit old state
                let old_state = std::mem::replace(state, new_state);
                delegate_state! { old_state.exit(body) }

                // Enter new state
                delegate_state! { state.enter(body) }
            }
        }
    }
}

// The declarative macro `delegate_state!` generates the same code mentioned in the initial example, except it doesn't pollute your view anymore :3

spire_enum can take it a step further though: instead of having you invoke that macro everytime, why not just let it implement the trait IState for your enum?

use spire_enum::prelude::delegate_impl;

#[delegate_impl]
impl IState for State {
    fn enter(&mut self, turret_body: &mut TurretBody);
    fn exit(self, turret_body: &mut TurretBody);

    /// Returns new state, if changed.
    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State>;
}

// Now you can just call those methods directly in the enum:
fn main() {
    let mut turrets = some_collection_data_structure();

    while let Some(delta_time) = tick_game_internals() {
        // We want to call tick on the state of every turret.
        for Turret { body, state } in &mut turrets {
            // If you want to understand how the generated macro `delegate_state!` works, check the section "1.1 Basic Usage".
            let transition = state.tick(body, delta_time);

            if let Some(new_state) = transition {
                // Exit old state
                let old_state = std::mem::replace(state, new_state);
                old_state.exit(body);

                // Enter new state
                state.enter(body);
            }
        }
    }
}

But that's not where spire_enum stops, in this case, it can also help if you specify the setting extract_variants in your enum:

#[delegated_enum(
    extract_variants(
        attrs(derive(Serialize, Deserialize)) // applies these attributes to every variant.
    )
)]
#[derive(Serialize, Deserialize)]
enum State {
    Idle { time_spent: f64 },
    Aiming { target_id: usize },
    ChargingShot { progress: f64, shot_type: ShotType },
    CoolingDown { time_remaining: f64 }
}

That setting will make the macro also generate and extract the types for each variant, so you don't need to declare the types anymore

This is how your entire file would look like with the usage of spire_enum

use spire_enum::prelude::{delegated_enum, delegate_impl};

// Trait
trait IState {
    fn enter(&mut self, turret_body: &mut TurretBody);
    fn exit(self, turret_body: &mut TurretBody);

    /// Returns new state, if changed.
    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State>;
}

// Enum
#[delegated_enum(extract_variants(derive(Serialize, Deserialize)))]
#[derive(Serialize, Deserialize)]
enum State {
    Idle { time_spent: f64 },
    Aiming { target_id: usize },
    ChargingShot { progress: f64, shot_type: ShotType },
    CoolingDown { time_remaining: f64 }
}

// Variant impls
impl IState for Idle { /* ... */ }
impl IState for Aiming { /* ... */ }
impl IState for ChargingShot { /* ... */ }
impl IState for CoolingDown { /* ... */ }

// Enum impl
#[delegate_impl]
impl IState for State {
    fn enter(&mut self, turret_body: &mut TurretBody);
    fn exit(self, turret_body: &mut TurretBody);
    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State>;
}

fn main() {
    let mut turrets = some_collection_data_structure();

    while let Some(delta_time) = tick_game_internals() {
        for Turret { body, state } in &mut turrets {
            let transition = state.tick(body, delta_time);

            if let Some(new_state) = transition {
                let old_state = std::mem::replace(state, new_state);
                old_state.exit(body);
                state.enter(body);
            }
        }
    }
}

You thought we were done? Not yet.

When implementing the trait for each variant, there's a good chance you're often converting variants from/into the enum.

impl IState for Idle {
    /* other functions */

    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State> {
        if let Some(target) = seek_new_target(turret_body) {
            Some(State::Aiming(Aiming { target_id: target.id }))
        } else {
            None
        }
    }
}

That's the least of our worries, but it doesn't mean we can't do better.

Let's have spire_enum generate conversions implementations too (From<Variant> for Enum, TryFrom<Enum> for Variant), which can be done with the setting impl_conversions:

#[delegated_enum(
    extract_variants(derive(Serialize, Deserialize)),
    impl_conversions, // <----- This setting
)]
#[derive(Serialize, Deserialize)]
enum State {
    Idle { time_spent: f64 },
    Aiming { target_id: usize },
    ChargingShot { progress: f64, shot_type: ShotType },
    CoolingDown { time_remaining: f64 }
}

So now we can just use .into():

impl IState for Idle {
    /* other functions */

    fn tick(&mut self, turret_body: &mut TurretBody, delta_time: f64) -> Option<State> {
        if let Some(target) = seek_new_target(turret_body) {
            Some(Aiming { target_id: target.id }.into())
        } else {
            None
        }
    }
}

There's more this crate can do, but this showcase is already long enough, check the Usage section if you want to know more.

Key Features:

• Delegation: Generates inherent/trait implementations for your enums, by delegating to their inner types.
• Conversions: Generate From<>/TryFrom<> implementations between your enums and their variants.
• Not limited to just plain/simple types: It properly handles generic parameters, lifetimes (bounds included), where clauses, etc.
• Hygiene (IDE friendly!):
  • Proc macros desugar into declarative macros.
  • Token spans are preserved.
  • Macro only uses inputs feed into it, no reflection is performed, no files are read (no IO operations).
  • No state is preserved between macro invocations, each invocation is completely isolated.

Overview

SpireEnum provides three macros that work together:

1. #[delegated_enum] - An attribute macro for defining enums with delegation capabilities.
2. #[delegate_impl] - An attribute macro for implementing traits or methods for the enum.
3. (Generated on the fly) delegate_[enum_name] - A declarative macro generated by delegated_enum, one for each annotated enum.

Macros 1. and 2. work together by:

1. When you apply #[delegated_enum] to an enum, the macro parses the enum definition, its settings and variants.
2. Based on the analysis, the macro generates:
   • A declarative macro named delegate_[enum_name] that handles the delegation logic.
   • [Optional] A new type for each variant.
   • [Optional] Conversion (From<>, TryFrom<>) implementations between the enum and its variants.
3. The #[delegate_impl] macro can be applied on trait or inherent implementations of the enum, it uses the generated delegate_[enum_name] macro to implement the method bodies that need delegation.

Alternatives

• enum_delegate - The initial inspiration for this crate, I aimed to provide better features while avoiding that crate's drawbacks (the main ones being lack of hygiene, preserving state between macro invocations).
• delegation - A fork of enum_delegate, which solves some of the old one's issues - though it takes a different approach compared to spire_enum.
• enum_variant_type - Provides similar functionality to this crate's extract_variants setting.

Usage

1. #[delegated_enum] (Enum attribute macro)

This attribute is applied to an enum definition to enable delegation capabilities:

use spire_enum::prelude::delegated_enum;

#[delegated_enum]
pub enum ApiResponse<T> {
    Success(T),
    Error(String),
    Pending { request_id: u64 },
    Timeout,
}

The delegated_enum attribute supports several optional settings that control how the enum behaves:

1.1 Basic Usage

When used without any settings, delegated_enum generates:

• A declarative macro named delegate_[enum_name] that can be used to implement delegated traits for the enum.

#[delegated_enum]
pub enum MediaContent {
    Text(String),
    Image(ImageData),
    Audio { track: AudioFile },
    Video(VideoStream),
    Document(DocumentFile),
}

Which generates the declared enum, and this macro:

macro_rules! delegate_media_content {
    ($_Self:expr => |$arg:ident| $($Rest:tt)*) => {
        match $_Self {
            MediaContent::Text($arg,..) => { $($Rest)* }
            MediaContent::Image($arg,..) => { $($Rest)* }
            MediaContent::Audio{track:$arg,..} => { $($Rest)* }
            MediaContent::Video($arg,..) => { $($Rest)* }
            MediaContent::Document($arg,..) => { $($Rest)* }
        }
    };
    ($_Self:tt $($Rest:tt)*) => {
        match $_Self {
            MediaContent::Text(__var,..) => { __var $($Rest)* }
            MediaContent::Image(__var,..) => { __var $($Rest)* }
            MediaContent::Audio{track,..} => { track$($Rest)* }
            MediaContent::Video(__var,..) => { __var $($Rest)* }
            MediaContent::Document(__var,..) => { __var$($Rest)* }
        }
    };
}

pub(crate) use delegate_media_content;

The macro may seem a bit cryptic, but it allows you to manually delegate impls in a very simple way:

// Let's Imagine that all variants of the enum `MediaContent` implement this trait:
pub trait OnLoad {
    fn on_after_deserialize(&mut self, cfg: &Cfg);
}

// If you were to manually write that implementation for the enum, you would have to:
impl OnLoad for MediaContent {
    fn on_after_deserialize(&mut self, cfg: &Cfg) {
        match self {
            MediaContent::Text(text) => { text.on_after_deserialize(cfg); }
            MediaContent::Image(img) => { img.on_after_deserialize(cfg); }
            MediaContent::Audio { track } => { track.on_after_deserialize(cfg); }
            MediaContent::Video(video) => { video.on_after_deserialize(cfg); }
            MediaContent::Document(doc) => { doc.on_after_deserialize(cfg); }
        }
    }
}

// That can obviously get very tedious if you're frequently using this pattern, 
// that's where the generated macro (`delegate_media_content`) comes in: 
impl OnLoad for MediaContent {
    fn on_after_deserialize(&mut self, cfg: &Cfg) {
        delegate_media_content!(self.on_after_deserialize(cfg));
    }
}

Although it can be used manually, the generated declarative macro delegate_media_content is used by the #[delegate_impl] attribute macro in the exact same way.

1.2 Conversion Settings

These are specified inside #[delegated_enum( **here** )], separated by commas.

1.2.1 impl_conversions

Enable automatic generation of conversion methods between the enum and its variants. For each Variant:

• TryFrom<Enum> for Variant
• TryFrom<&Enum> for &Variant
• TryFrom<&mut Enum> for &mut Variant
• From<Variant> for Enum

#[delegated_enum(
    impl_conversions
)]
pub enum MediaContent {
    Text(String),
    Image(ImageData),
    Audio { track: AudioFile },
    Video(VideoStream),
    Document(DocumentFile),
}

Which additionally generates:

impl TryFrom<MediaContent> for String {
    type Error = MediaContent;
    fn try_from(_value: MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Text(__var) = _value {
            Ok(__var)
        } else {
            Err(_value)
        }
    }
}

impl<'_r1> TryFrom<&'_r1 MediaContent> for &'_r1 String {
    type Error = ();

    fn try_from(_value: &'_r1 MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Text(__var) = _value {
            Ok(__var)
        } else {
            Err(())
        }
    }
}

impl<'_r1> TryFrom<&'_r1 mut MediaContent> for &'_r1 mut String {
    type Error = ();

    fn try_from(_value: &'_r1 mut MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Text(__var) = _value {
            Ok(__var)
        } else {
            Err(())
        }
    }
}

impl From<String> for MediaContent {
    fn from(_value: String) -> Self {
        MediaContent::Text(_value)
    }
}

impl TryFrom<MediaContent> for ImageData {
    type Error = MediaContent;
    fn try_from(_value: MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Image(__var) = _value {
            Ok(__var)
        } else {
            Err(_value)
        }
    }
}

impl<'_r1> TryFrom<&'_r1 MediaContent> for &'_r1 ImageData {
    type Error = ();

    fn try_from(_value: &'_r1 MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Image(__var) = _value {
            Ok(__var)
        } else {
            Err(())
        }
    }
}

impl<'_r1> TryFrom<&'_r1 mut MediaContent> for &'_r1 mut ImageData {
    type Error = ();

    fn try_from(_value: &'_r1 mut MediaContent) -> Result<Self, Self::Error> {
        if let MediaContent::Image(__var) = _value {
            Ok(__var)
        } else {
            Err(())
        }
    }
}

impl From<ImageData> for MediaContent {
    fn from(_value: ImageData) -> Self {
        MediaContent::Image(_value)
    }
}

// ... same for each other variant

These implementations facilitate conversions between the enums and its possible variants, especially when each variant has a unique type.

---

The setting also generates a set of custom trait implementations provided by spire_enum:

• FromEnum/FromEnumRef/FromEnumMut for Variant

These traits allow spire_enum::prelude::EnumExtensions to be implemented for your enum, which provides even more utilities for enum-variant conversion:

use spire_enum::prelude::EnumExtensions;

let media = MediaContent::Text("hello world".to_string());
assert!(media.is_var::<String>());
assert!(media.try_ref_var::<ImageData>().is_none());
assert_eq!(*media.try_mut_var::<String>(), "hello world");
assert_eq!(media.try_into_var::<String>(), Ok("hello world".to_string()));

For more information, read the trait EnumExtensions's documentation.

---

This setting is configurable in a per-variant basis, you may skip generating the implementations for certain variants by using the attribute # [dont_impl_conversions]:

#[delegated_enum(
    impl_conversions
)]
pub enum MediaContent {
    Text(String),
    Image(ImageData),
    Audio { track: AudioFile },
    Video(VideoStream),
    #[dont_impl_conversions] // Will not generate conversions between `DocumentFile` and `MediaContent`
    Document(DocumentFile),
}

1.2.2 impl_enum_try_into_variants

Similar to impl_conversions, except it only generates TryFrom<Enum>, TryFrom<&Enum> and TryFrom<&mut Enum> for each variant.

#[delegated_enum(
    impl_enum_try_into_variants
)]
pub enum MediaContent {
    Text(String),
    Image(ImageData),
    Audio { track: AudioFile },
    Video(VideoStream),
    Document(DocumentFile),
}

1.2.3 impl_variants_into_enum

Similar to impl_conversions, except it only generates From<Variant> for the enum.

#[delegated_enum(
    impl_variants_into_enum
)]
pub enum MediaContent {
    Text(String),
    Image(ImageData),
    Audio { track: AudioFile },
    Video(VideoStream),
    Document(DocumentFile),
}

1.3 Variant Types Generation

These are specified inside #[delegated_enum( **here** )], separated by commas.

1.3.1 extract_variants

Generates a new type for each variant:

#[delegated_enum(extract_variants)]
pub enum SettingsEnum {
    MaxFps(i32),
    DialogueTextSpeed { speed_percent: i32 },
    Vsync(bool),
    Volume(i32),
}

Which additionally generates:

pub struct MaxFps(pub i32);
pub struct Vsync(pub bool);
pub struct Volume(pub i32);

pub struct DialogueTextSpeed {
    pub speed_percent: i32,
}

// And replaces the original enum's variant types with the generated ones:
pub enum SettingsEnum {
    MaxFps(MaxFps),
    Vsync(Vsync),
    Volume(Volume),
    DialogueTextSpeed(DialogueTextSpeed),
}

Note that the declarative macro delegate_[enum_name] is also generated differently to handle the new variant types.

1.3.2 extract_variants( attrs(attribute_list) )

Applies every attribute in (attribute_list) to each generated variant type.

#[delegated_enum(
    extract_variants(
        attrs(cfg(test))
    )
)]
pub enum ApiResource {
    User(UserData),
    Post(PostData),
    Comment(CommentData),
}

Which will generate:

#[cfg(test)]
pub struct User(pub UserData);

#[cfg(test)]
pub struct Post(pub PostData);

#[cfg(test)]
pub struct Comment(pub CommentData);

pub enum ApiResource {
    User(User),
    Post(Post),
    Comment(Comment),
}

1.3.3 extract_variants( derive(trait_list) )

Shorthand for attrs(derive(trait_list))

#[delegated_enum(
    extract_variants(derive(Debug, Clone, Serialize, Deserialize))
)]
pub enum ApiResource {
    User(UserData),
    Post(PostData),
    Comment(CommentData),
}

Which will generate:

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User(pub UserData);

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Post(pub PostData);

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Comment(pub CommentData);

pub enum ApiResource {
    User(User),
    Post(Post),
    Comment(Comment),
}

2. #[delegate_impl] (Inherent/Trait impl attribute macro)

This attribute should be applied to the enum's implementation blocks:

use spire_enum::prelude::delegate_impl;

#[delegate_impl]
impl<T: Clone> Clone for ApiResponse<T> {
    // The implementation is automatically delegated to the inner types
    // No need to write match statements
    fn clone(&self) -> Self;
}

Which generates:

impl<T: Clone> Clone for ApiResponse<T> {
    fn clone(&self) -> Self {
        delegate_api_response! { self.clone().into() }
    }
}

Note that it uses the macro delegate_api_response, which would be generated by the enum annotated with #[delegated_enum].

2.1 Associated Types, Constants and Static Functions

Delegating these items is impossible since there's no enum value to match on, you must write that particular item manually if a trait requires these.

Example:

use spire_enum::prelude::{delegated_enum, delegate_impl};

// Suppose you have this trait:
trait ISetting {
    type Inner;
    const DEFAULT_VALUE: Self::Inner;

    fn apply(&self);
    fn read_from_disk() -> Result<Self>;
}

// And you wish to apply it to the enum:
#[delegated_enum]
enum VolumeSetting {
    Main(MainVolume),
    Music(MusicVolume),
    Sfx(SfxVolume),
}

// The only item that can be delegated is `fn apply(&self)`, other items must be manually written:
#[delegate_impl]
impl ISetting for VolumeSetting {
    // Cannot be delegated, you must provide the type.
    type Inner = f64;

    // Cannot be delegated, you must provide the constant's value.
    const DEFAULT_VALUE: Self::Inner = 50.0;

    // Can be delegated, no need to manually write the implementation.
    fn apply(&self);

    // Cannot be delegated, you must write the implementation.
    fn read_from_disk() -> Result<Self> {
        let file = std::fs::read_to_string("user://settings.cfg");
        // rest of your impl ...
    }
}

Note that you may still manually write the implementation of fn apply(&self), which will "override" what would be generated by the macro.

3. Variant Attributes

Attributes that can be applied on a per-variant basis.

3.1 #[dont_impl_conversions] / #[dont_extract] (Variant attributes)

#[delegated_enum(extract_variants, impl_conversions)]
pub enum Config {
    // Don't implement conversion methods (TryFrom<>, From<>) for this variant.
    // Does nothing if `impl_conversions` isn't present.
    #[dont_impl_conversions]
    Default(DefaultConfig),

    // Don't generate/extract this variant.
    // Does nothing if `extract_variants` isn't present.
    #[dont_extract]
    Custom(CustomConfig),

    Legacy(LegacyConfig),
    Simple(SimpleConfig),
}

3.2 #[delegate_via(|var| var.foo())] (Variant attribute)

When delegating methods, instead of calling the method directly on the variant, call the delegated method on the result of the closure inside delegate_via.

Example:

#[delegated_enum(extract_variants, impl_conversions)]
pub enum Config {
    Default(DefaultConfig),
    #[delegate_via(|legacy_config| legacy_config.some_fallback())]
    Legacy(LegacyConfig),
    Simple(SimpleConfig),
}

This attribute affects how the macro delegate_[enum_name] will be generated, in this, changing it:

// From
macro_rules! delegate_config {
    ($_Self:expr => |$arg:ident| $($Rest:tt)*) => {
        match $_Self {
            Config::Default($arg) => { $($Rest)* }
            Config::Legacy($arg) => { $($Rest)* }
            Config::Simple($arg) => { $($Rest)*}
        }
    };

    ($_Self:tt $($Rest:tt)*) => {
        match $_Self {
            Config::Default(__var) => { __var $($Rest)* }
            Config::Legacy(__var) => { __var $($Rest)* }
            Config::Simple(__var) => { __var$($Rest)* }
        }
    };
}

// To
macro_rules! delegate_config {
    ($_Self:expr => |$arg:ident| $($Rest:tt)*) => {
        match $_Self {
            Config::Default($arg) => { $($Rest)* }
            Config::Legacy(__var) => {
                let __f = (|legacy_config| legacy_config.some_fallback());
                let $arg = __f(__var);
                $($Rest)*
            }
            Config::Simple($arg) => { $($Rest)*}
        }
    };

    ($_Self:tt $($Rest:tt)*) => {
        match $_Self {
            Config::Default(__var) => { __var $($Rest)* }
            Config::Legacy(__var) => {
                let __f = (|legacy_config| legacy_config.some_fallback());
                let __res = __f(__var);
                __res $($Rest)*
            }
            Config::Simple(__var) => { __var$($Rest)* }
        }
    };
}

3.3 #[delegator] (Variant field attribute)

Use this to delegate method calls to a field of the variant instead of the variant itself.

Example:

#[delegated_enum(extract_variants, impl_conversions)]
pub enum Config {
    Default(DefaultConfig),
    Legacy { version: i64, #[delegator] config: LegacyConfig },
    Simple(SimpleConfig),
}

This will change the Legacy case in the delegate_[enum_name] macro:

// From
Config::Legacy { version: $ arg, ..} => { $ ( $ Rest) * }

// To
Config::Legacy { config: $ arg, ..} => { $ ( $ Rest) * }

Example: Basic Usage

use spire_enum::prelude::{delegated_enum, delegate_impl};

#[delegated_enum]
pub enum Value<'a, T>  // Generics are supported.
    where T: Display
{
    Integer(i64),
    Float(f64),
    Text(String),
    Boolean(bool),
    List(&'a Vec<T>),
}

#[delegate_impl]
impl<'c, F> std::fmt::Display for Value<'c, F>
    where T: Display
{
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result;
}

let some_variant: Value =..;
println!("{some_variant}");

Example: State Machine

SpireEnum is particularly useful for implementing state machines:

// Each state already has its own variant type declared outside the macro, no need to use `extract_variants`. 
#[delegated_enum(
    impl_conversions // conversions are nice though
)]
pub enum GameState {
    MainMenu(MenuState),
    Playing(PlayState),
    Paused(PauseState),
    GameOver(GameOverState),
    LevelTransition(TransitionState),
}

// Common interface for all states
trait State {
    fn update(&mut self, delta_time: f32);
    fn handle_input(&mut self, input: UserInput) -> StateTransition;
    fn render(&self, renderer: &mut Renderer);
}

// Implementation delegated to each state.
#[delegate_impl]
impl State for GameState {
    fn update(&mut self, delta_time: f32);
    fn handle_input(&mut self, input: UserInput) -> StateTransition;
    fn render(&self, renderer: &mut Renderer);
}

Troubleshooting

The macros provided by this crate carefully parse the inputs provided to it, I aimed to provide helpful error messages as reasonably as I could. If you encounter a cryptic error message, please open an issue, I'll do what I can to fix it in a timely manner.

1. "Cannot find macro delegate_[enum_name]"

You're likely using the macro #[delegate_impl] outside of the module that contains your enum. The macro delegate_[enum_name] is generated alongside the enum annotated with #[delegated_enum], you need to import it on other modules where #[delegate_impl] is used:

use path_to_enum_module::{MyEnum, delegate_my_enum};

#[delegate_impl]
impl Foo for MyEnum {
    fn bar(&self);
}

Performance

The delegation macros generate code that is equivalent to what you would write manually with match statements. There is no runtime overhead compared to manually written code.

Contributing

The best way to contribute is by using the crate and providing feedback. Please open an issue if you'd like to request a feature or report a bug.