Macros: an introduction

Macros in Rust are different from macros in C. C macros are textual substitution — fragile, scope-unaware, a common source of subtle bugs. Rust macros are syntactic: they match patterns in the token stream and produce valid Rust syntax, checked by the compiler. They're a metaprogramming tool — code that writes code.

You've been using macros from the start: println!, vec!, assert_eq!, format!, todo!. This lesson shows you how they work and when to write your own.

Macros vs functions

A function is called at runtime with a fixed, typed signature. A macro is expanded at compile time and can:

• Accept a variable number of arguments (like println!("{} {}", a, b, c))
• Accept different types in the same position
• Generate different code depending on the input

vec![1, 2, 3]          // macro — variable number of args
[1, 2, 3]              // array literal — fixed-size, known at compile time
Vec::from([1, 2, 3])   // function — but can't take variable args like vec!

The trade-off: macros are more powerful but harder to read, harder to write, and harder to debug. Use functions when they can do the job.

macro_rules!

Declarative macros use macro_rules! and work by matching patterns:

macro_rules! say_hello {
    () => {
        println!("Hello!");
    };
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
}

say_hello!();             // Hello!
say_hello!("Ferris");     // Hello, Ferris!

A macro_rules! definition contains one or more rules: (pattern) => { expansion }. The pattern uses metavariables — $name:expr matches any Rust expression and binds it to $name in the expansion.

Common metavariable types

Repetition patterns

Use $(...)* or $(...)+ to match repeated tokens:

macro_rules! my_vec {
    ($($element:expr),*) => {
        {
            let mut v = Vec::new();
            $(v.push($element);)*
            v
        }
    };
}

let v = my_vec![1, 2, 3, 4];

$($element:expr),* matches zero or more comma-separated expressions. $(v.push($element);)* expands the push call once for each matched element. This is (approximately) how the standard vec! macro works.

vec! and println! dissected

// vec! is approximately:
macro_rules! vec {
    () => (std::vec::Vec::new());
    ($($x:expr),+ $(,)?) => ({
        let mut v = std::vec::Vec::new();
        $(v.push($x);)+
        v
    });
}

// println! wraps format_args! and writes to stdout:
// It accepts a format string literal (checked at compile time) and any number of arguments.

println!'s format string is checked at compile time — println!("{} {}", a) is a compile error (too few args), not a runtime error. Functions can't provide this guarantee; the macro's compile-time pattern matching makes it possible.

When to write a macro

Macros are appropriate when:

1. You need a variable number of arguments.
2. You need to generate repetitive code from a shorter specification (e.g., implementing a trait for many types).
3. You need compile-time checking of input structure (e.g., SQL queries, format strings).

Prefer functions otherwise. A function that takes a Vec of arguments is usually clearer than a macro.

Procedural macros: a brief overview

Declarative macros (macro_rules!) match patterns. Procedural macros (proc macros) are full Rust programs that receive a token stream and return a token stream. They're more powerful but require a separate crate:

• Derive macros: #[derive(Debug, Serialize)] — auto-implement traits for types.
• Attribute macros: #[route(GET, "/")] — transform annotated items.
• Function-like macros: sql!(SELECT * FROM users) — macro with function call syntax but arbitrary parsing.

You've used proc macros many times: #[derive(Debug)] is a proc macro from the standard library. #[tokio::main] is a proc macro from Tokio. The serde crate's #[derive(Serialize, Deserialize)] generates serialization code automatically.

Writing proc macros requires the proc-macro2, quote, and syn crates. It's advanced territory — worth knowing exists, but not necessary until you're building a library that others will use.

Check your understanding

Do it yourself

Write a map! macro that creates a HashMap from key-value pairs:

let m = map!{ "a" => 1, "b" => 2, "c" => 3 };

Hint: use $(key:expr => $val:expr),* as the pattern. The expansion should create a HashMap::new(), insert each pair, and return the map.

When the agent's away

# See the expanded output of a macro call
cargo install cargo-expand
cargo expand          # shows the full expanded source

# Check a specific item
cargo expand --item my_function

cargo expand is invaluable for debugging macros — it shows you exactly what code the macro generated.

Where to go next

This completes the ecosystem and tooling module. The lab at the end of this module puts the advanced topics together. After that, you've covered the full Rust track — from ownership basics through async concurrency and metaprogramming.