spire_enum_macros 0.1.0

Procedural macros to facilitate enum usage, such as when delegating implementations and/or generating variant types.
Documentation
spire_enum_macros-0.1.0 has been yanked.

SpireEnum

A Rust library that provides powerful macros for working with enums, designed to simplify delegation patterns and reduce boilerplate code when implementing traits and methods for enums.

Table of Contents

Key Features:

  • Automatic delegation: Automatically implement methods and traits for enums by delegating to their inner types.
  • Flexibility: Provide case-by-case implementations when needed.
  • Conversion utilities: Generate conversion methods between the enum and its variants.
  • Reduce boilerplate: Eliminate repetitive match statements and error-prone manual delegation.
  • Hygiene (IDE friendly!):
    • 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 through several steps:

  1. Parsing and Analysis: When you apply #[delegated_enum] to an enum, the macro parses the enum definition, its settings and variants, analyzing the types and structures.

  2. Code Generation: 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. Delegation Logic: The #[delegate_impl] macro is applied on trait or inherent implementations of the enum, identifies delegation targets, then uses the generated delegate_[enum_name] macro, expanding to the appropriate match statements that forward method calls to the inner types.

  4. The Generated Declarative Macro: The most interesting part is the generated declarative macro (e.g., delegate_my_enum!). This macro:

    • Takes trait implementations or methods as input
    • Expands them into match statements that delegate to the appropriate variant's inner value
    • Properly handles generic parameters, lifetimes, and other complex syntax elements.

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 generate_variants setting.

Usage

1. #[delegated_enum] (Enum attribute macro)

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

use spire_enum::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
  • 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(__input: MediaContent) -> Result<Self, Self::Error> {
		if let MediaContent::Text(__var) = __input {
			Ok(__var)
		} else {
			Err(__input)
		}
	}
}

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

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

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

// ... same for each other variant

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

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> 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 generate_variants

Generates a new type for each variant:

#[delegated_enum(
	generate_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 generate_variants( attrs = [attribute_list] )

Applies every attribute in [attribute_list] to each generated variant type.

#[delegated_enum(
	generate_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 generate_variants( derive(trait_list) )

Shorthand for attrs = [derive(trait_list)]

#[delegated_enum(
	generate_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::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::{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_generate_type] (Variant attributes)

#[delegated_enum(generate_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 the new type for this variant.
	// Does nothing if `generate_variants` isn't present.
	#[dont_generate_type]
	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(generate_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(generate_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::{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 `generate_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.

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.