Rust Macros Practice: macro_rules!, Declarative Macros

Fragment specifiers tell the macro parser what kind of syntax to expect:

tt (token tree) is the escape hatch — it matches any single token or balanced group in brackets. Use it for forwarding arbitrary tokens to other macros.

The most common macro error. Your fragment specifier doesn't match the input:

// WRONG: ident only matches a single identifier
// macro_rules! double {
//     ($x:ident) => { $x * 2 };
// }
// double!(1 + 1);  // error: no rules expected `1`

// RIGHT: use expr for expressions
macro_rules! double {
    ($x:expr) => { $x * 2 };
}
let result = double!(1 + 1); // 4

ident matches only a single identifier like x or foo. An expression like 1 + 1 requires expr.

// Simplest macro: no arguments
macro_rules! say_hello {
    () => {
        println!("Hello!");
    };
}
say_hello!();

// Capture an identifier and generate code
macro_rules! create_function {
    ($name:ident) => {
        fn $name() {
            println!("Called {}", stringify!($name));
        }
    };
}
create_function!(foo);
foo(); // prints "Called foo"

Semicolons between arms are required. A trailing semicolon after the last arm is conventional. The pattern-matching syntax inside macro_rules! is inspired by regular pattern matching, though the macro version operates on tokens rather than values.

// Build a Vec from comma-separated expressions
macro_rules! vec_of {
    ($($x:expr),* $(,)?) => {
        {
            let mut v = Vec::new();
            $(v.push($x);)*
            v
        }
    };
}

let v = vec_of![1, 2, 3];
let v2 = vec_of![1, 2, 3,]; // trailing comma OK

// Generate a function with a captured name and type
macro_rules! make_adder {
    ($name:ident, $t:ty) => {
        fn $name(x: $t, y: $t) -> $t {
            x + y
        }
    };
}

make_adder!(add_i32, i32);
let sum = add_i32(2, 3); // 5

Arms are matched top-to-bottom. Put specific patterns before general ones:

macro_rules! log {
    ($msg:expr) => {
        println!("[LOG] {}", $msg)
    };
    ($fmt:expr, $($arg:tt)*) => {
        println!("[LOG] {}", format!($fmt, $($arg)*))
    };
}

log!("simple message");
log!("hello {}", "world");

When two arms could both match the same input, the parser cannot decide:

// WRONG: both arms match a single expr
// macro_rules! ambiguous {
//     ($x:expr) => { println!("one: {}", $x) };
//     ($x:expr, $y:expr) => { println!("two: {} {}", $x, $y) };
// }
// ambiguous!(1, 2);  // error: local ambiguity

// RIGHT: add a distinguishing token
macro_rules! log {
    (single: $x:expr) => { println!("one: {}", $x) };
    (pair: $x:expr, $y:expr) => { println!("two: {} {}", $x, $y) };
}
log!(single: 1);
log!(pair: 1, 2);

The issue: $x:expr in the first arm can match 1, 2 as a single expression containing the comma operator. Adding a keyword prefix or restructuring the arms removes the ambiguity.

Macros in Rust are partially hygienic — variables defined inside the macro expansion don't leak into the caller's scope:

macro_rules! make_var {
    () => {
        let x = 42;  // this x is scoped to the expansion
    };
}

let x = 0;
make_var!();
println!("{x}"); // still 0 — the macro's x is separate

However, macros can access items (fn, struct, etc.) from the caller's scope. When passing identifiers to macros, the generated code uses the caller's namespace. The traits and generics guide explains how generics often provide a cleaner alternative to macros when the goal is type-parametric code.

Macro errors point at the call site, not the expansion. Use cargo expand to see generated code:

cargo install cargo-expand
cargo expand           # expand all macros in the crate
cargo expand my_module # expand a specific module

For quick debugging, stringify!() shows what tokens were captured:

macro_rules! debug_me {
    ($($t:tt)*) => {
        println!("tokens: {}", stringify!($($t)*));
    };
}
debug_me!(hello world 42); // prints: tokens: hello world 42

This page covers declarative macros (macro_rules!). Rust also has procedural macros, which are different:

If you're looking for #[derive(...)] traits, the derive traits guide covers which traits can be derived and when to implement manually. If you need attribute macros like #[test] or #[tokio::main], those are procedural macros.

• The Rust Book: Macros — declarative vs procedural overview
• Rust By Example: macro_rules! — practical examples
• The Little Book of Rust Macros — deep dive into macro patterns
• Rust Reference: Macros By Example — formal syntax and fragment specifiers