Macros

Core Question

Is a macro the simplest way to eliminate this repetition, or would a function, generic, or trait do the job?

Macros generate code at compile time. They are powerful but harder to read, debug, and maintain than plain Rust. Reach for them only after ruling out simpler alternatives.

Error → Design Question

Quick Decisions

Fragment Specifiers

Repetition Patterns

Three repetition operators with an optional separator:

macro_rules! make_list {
    // Zero or more
    ( $( $item:expr ),* ) => {
        vec![ $( $item ),* ]
    };
}

macro_rules! require_one {
    // One or more
    ( $( $item:expr ),+ ) => {
        vec![ $( $item ),+ ]
    };
}

macro_rules! optional_label {
    ( $( $label:ident : )? $value:expr ) => {
        println!("{}", $value);
    };
}

Nested repetition handles parallel lists:

macro_rules! impl_from {
    ( $target:ident : $( $source:ty => $variant:ident ),+ ) => {
        $(
            impl From<$source> for $target {
                fn from(val: $source) -> Self {
                    Self::$variant(val)
                }
            }
        )+
    };
}

The Macro vs Generic Decision

1. Can a function do it? → Use a function.
2. Can a generic do it? → Use a generic.
3. Can a trait do it? → Use a trait.
4. None of the above? → Then use a macro.

Macros are the right tool when you need to:

• Generate new identifiers or types
• Repeat code with varying structure (not just types)
• Create syntax that Rust's type system cannot express
• Implement a trait for a list of types

macro_rules! Hygiene

Identifiers inside macro_rules! are hygienic — they do not collide with names at the call site. However, this means a macro cannot reference local variables from the caller unless passed in as arguments.

Use $crate to reference items from the defining crate:

#[macro_export]
macro_rules! create_error {
    ( $msg:expr ) => {
        $crate::Error::new($msg)
    };
}

Without $crate, the macro breaks when used from another crate because Error resolves in the caller's namespace.

Usage Scenarios

Scenario 1: "I have 12 structs that all need the same trait impl with minor variations" → Write a macro_rules! with repetition that takes the struct name and the varying parts as parameters. See references/declarative.md for trait impl patterns.

Scenario 2: "I want to generate tests for multiple input/output pairs" → Use macro_rules! to generate #[test] functions with unique names from a list of cases. See references/declarative.md for test generation.

Scenario 3: "I need a #[derive(MyTrait)] that generates methods based on struct fields" → Create a proc macro crate with syn and quote. Parse DeriveInput, iterate fields, emit impl block. See references/procedural.md for derive macro setup.

Reference Files

Cross-References