Declarative macros

macro_rules! hello {
    () => {
        println!("Hello!");
    };
}

hello!();

macro_rules! square {
    ($x:expr) => {
        $x * $x
    };
}

let a = square!(4);         // 16

$x:expr captures an expression and names it $x. In the expansion, $x is replaced by the code received.

macro_rules! declare {
    ($vis:vis $name:ident : $t:ty = $value:expr) => {
        $vis const $name: $t = $value;
    };
}

declare!(pub MAX: u32 = 100);
declare!(MIN: u32 = 0);         // empty vis: private

macro_rules! is {
    ($value:expr, $pattern:pat) => {
        matches!($value, $pattern)
    };
}

let ok = is!(Some(3), Some(1..=5));

macro_rules! my_vec {
    ( $( $x:expr ),* ) => {{
        let mut v = Vec::new();
        $( v.push($x); )*          // one generated line per captured element
        v
    }};
}

let v = my_vec![1, 2, 3];
let empty: Vec<i32> = my_vec![];

The double braces {{ ... }}: the first pair delimits the expansion, the second forms a block, so that the variables (v) do not leak and the whole is a single expression.

macro_rules! list {
    ( $( $x:expr ),* $(,)? ) => {
        vec![ $( $x ),* ]
    };
}

list![1, 2, 3];
list![1, 2, 3,];          // accepted thanks to $(,)?

macro_rules! table {
    ( $( $key:expr => $value:expr ),* $(,)? ) => {{
        let mut m = ::std::collections::HashMap::new();
        $( m.insert($key, $value); )*
        m
    }};
}

let t = table! {
    "one" => 1,
    "two" => 2,
};

The variables of the same repetition advance together: $key and $value must have been captured the same number of times.

macro_rules! matrix {
    ( $( [ $( $x:expr ),* ] ),* ) => {
        vec![ $( vec![ $( $x ),* ] ),* ]
    };
}

let m = matrix!([1, 2], [3, 4], [5, 6]);   // Vec<Vec<i32>>

macro_rules! field {
    ($name:ident : $t:ty $(= $default:expr)?) => {
        // $default can only be used inside a $( ... )? repetition
        let $name: $t = field!(@default $($default)?);
    };
    (@default $e:expr) => { $e };
    (@default) => { Default::default() };
}

macro_rules! log {
    ($msg:expr) => {
        println!("[INFO] {}", $msg)
    };
    ($level:ident, $msg:expr) => {
        println!("[{}] {}", stringify!($level), $msg)
    };
    ($level:ident, $fmt:literal, $($arg:tt)*) => {
        println!(concat!("[{}] ", $fmt), stringify!($level), $($arg)*)   // concat! requires a literal
    };
}

log!("starting");
log!(WARN, "disk almost full");
log!(ERROR, "code {}", 500);

macro_rules! timed {
    ($name:expr, $body:block) => {{
        let start = ::std::time::Instant::now();
        let r = $body;
        println!("{}: {:?}", $name, start.elapsed());
        r
    }};
}

let total = timed!("total", { (1..1_000_000u64).sum::<u64>() });

macro_rules! require {
    ($cond:expr, $err:expr) => {
        if !$cond {
            return Err($err.into());
        }
    };
}

fn register(age: u32, email: &str) -> Result<(), String> {
    require!(age >= 18, "you must be an adult");
    require!(email.contains('@'), "invalid email");
    Ok(())
}

This is the principle of anyhow::ensure!. A macro can return from the calling function, which a function cannot do.

macro_rules! show {
    ($($e:expr),+ $(,)?) => {
        $( println!("{} = {:?}", stringify!($e), $e); )+
    };
}

show!(1 + 2, "abc".len());
// 1 + 2 = 3
// "abc".len() = 3

stringify! turns the code received into text: this is how assert! and dbg! display the expression that failed.

macro_rules! getters {
    ($type:ident { $( $field:ident : $t:ty ),* $(,)? }) => {
        impl $type {
            $(
                pub fn $field(&self) -> &$t {
                    &self.$field
                }
            )*
        }
    };
}

struct User { name: String, age: u32 }
getters!(User { name: String, age: u32 });

macro_rules! identifier {
    ($name:ident) => {
        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
        pub struct $name(pub i64);

        impl ::std::fmt::Display for $name {
            fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
                write!(f, "{}#{}", stringify!($name), self.0)
            }
        }

        impl From<i64> for $name {
            fn from(v: i64) -> Self { $name(v) }
        }
    };
}

identifier!(UserId);
identifier!(OrderId);

Two lines generate two distinct types with six traits each: this is the typical case where a macro removes repetition that no generic can remove (each type must be named).

trait IsZero { fn is_zero(&self) -> bool; }

macro_rules! impl_is_zero {
    ($($t:ty),*) => {
        $( impl IsZero for $t { fn is_zero(&self) -> bool { *self == 0 as $t } } )*
    };
}

impl_is_zero!(i8, i16, i32, i64, u8, u16, u32, u64, f32, f64);

The standard library implements the numeric traits this way for each integer type.

fn double(x: i32) -> i32 { x * 2 }

macro_rules! double_tests {
    ($($name:ident : $input:expr => $expected:expr),* $(,)?) => {
        $(
            #[test]
            fn $name() {
                assert_eq!(double($input), $expected);
            }
        )*
    };
}

double_tests! {
    zero: 0 => 0,
    positive: 3 => 6,
    negative: -2 => -4,
}

macro_rules! maximum {
    ($x:expr) => { $x };
    ($x:expr, $($rest:expr),+) => {{
        let a = $x;
        let b = maximum!($($rest),+);
        if a > b { a } else { b }
    }};
}

let m = maximum!(3, 9, 2, 7);    // 9

Each call handles the first element and calls the macro again on the rest, until the base case (a single element).

macro_rules! count {
    () => { 0usize };
    ($head:tt $($rest:tt)*) => { 1usize + count!($($rest)*) };
}

const N: usize = count!(a b c d);   // 4

macro_rules! replace { ($_t:tt $sub:expr) => { $sub }; }

macro_rules! count_fast {
    ($($t:tt)*) => { <[()]>::len(&[$(replace!($t ())),*]) };
}

const M: usize = count_fast!(a b c d e);   // 5

Each element becomes a () in an array, whose length is taken: no recursion limit.

macro_rules! name_array {
    ($($name:ident),* $(,)?) => {
        [$(stringify!($name)),*]
    };
}

const FIELDS: [&str; 3] = name_array!(name, email, age);

macro_rules! naive_square {
    ($x:expr) => { $x * $x };
}

let mut counter = 0;
let mut next = || { counter += 1; counter };
let c = naive_square!(next());   // next() is called TWICE: 1 * 2 = 2, not 1

The code received is copied at each $x. An expression with a side effect (or an expensive one) is run as many times. Fix: evaluate it once in a variable.

macro_rules! square {
    ($x:expr) => {{
        let v = $x;
        v * v
    }};
}

macro_rules! new_map {
    () => { HashMap::new() };               // fails if the user has not imported HashMap
}

macro_rules! new_map_ok {
    () => { ::std::collections::HashMap::new() };   // works everywhere
}

In the expansion of a macro, write full paths: ::std::... for the standard library, $crate::... for your own crate (see macros-export).

macro_rules! with_temp {
    ($e:expr) => {{
        let temp = 10;
        $e + temp
    }};
}

let temp = 1;
let r = with_temp!(temp);    // 11: the caller's `temp` is not the macro's one

A variable declared inside a macro cannot collide with a variable of the caller, even with the same name: macro_rules! is hygienic for local variables.

macro_rules! declare_function {
    () => { fn help() -> u32 { 42 } };
}

declare_function!();
let x = help();              // the function is visible: items (fn, struct, impl) are not hygienic

The names of functions, types, modules and traits generated by a macro are visible as usual. Paths in the expansion are resolved at the call site, hence the absolute path rule (section 10.3).

macro_rules! color {
    (red) => { (255, 0, 0) };
    (green) => { (0, 255, 0) };
    ($other:tt) => {
        compile_error!(concat!("unknown color: ", stringify!($other)))
    };
}

let c = color!(red);
// let d = color!(blue);   // ERROR: unknown color: blue

Without the last arm, the error would be "no rules expected the token blue", which is less helpful.

cargo install cargo-expand
cargo expand                  # the whole crate expanded
cargo expand module::path     # a single module

This is the essential tool for understanding an error in a macro: you read the code produced, and compile the faulty part by hand.

const VERSION: &str = env!("CARGO_PKG_VERSION");          // version from Cargo.toml, fixed at compile time
const README: &str = include_str!("../README.md");        // the file is embedded in the binary

// runique/src/macros/routeur/router.rs (start)
macro_rules! urlpatterns {
    (@parse $routes:ident;) => {};

    (@parse $routes:ident;
        admin $path:expr => $handler:expr,
        name = $name:expr,
        for_model = $model:ty,
        overrides = $view:expr,
        $($rest:tt)*
    ) => {
        $routes.add_admin_route::<$model>($path, $name, $handler, $view);
        $crate::urlpatterns!(@parse $routes; $($rest)*);
    };
    // ... other arms for the other route forms ...
}

All the techniques of this course appear here: @parse internal rules, a base case ((@parse $routes:ident;) => {}), capturing the rest with $($rest:tt)*, the recursive call, specific arms (starting with the word admin) placed before the general arms, and $crate:: so that the recursive call works from the user's crate.

// runique/src/macros/context/impl_error.rs
#[macro_export]
macro_rules! impl_from_error {
    ($($err:ty => $method:ident),*) => {
        $(
            impl From<$err> for AppError {
                fn from(err: $err) -> Self { Self { context: ErrorContext::$method(&err) } }
            }
            impl From<$err> for Box<AppError> {
                fn from(err: $err) -> Self { Box::new(AppError::from(err)) }
            }
        )*
    };
}

impl_from_error!(
    anyhow::Error => from_anyhow,
    DbErr => database,
    tower_sessions::session::Error => database
);

A repetition with two variables ($err and $method), generating two impl blocks per entry: three call lines replace six impl blocks.

use std::collections::HashMap;
use std::hash::Hash;

// 1. Generic function: readable, autocompleted, debuggable
fn map_from<K: Hash + Eq, V, const N: usize>(pairs: [(K, V); N]) -> HashMap<K, V> {
    HashMap::from(pairs)
}

// 2. Standard library: nothing to write
let a = HashMap::from([("one", 1), ("two", 2)]);

// 3. Macro: lighter syntax, nothing more
macro_rules! map {
    ($($k:expr => $v:expr),* $(,)?) => {
        ::std::collections::HashMap::from([$(($k, $v)),*])
    };
}
let b = map! { "one" => 1, "two" => 2 };
let c = map_from([("one", 1)]);

macro_rules! name {
    () => { .. };                                   // no argument
    ($x:expr) => { .. };                            // an expression
    ($a:ident, $t:ty) => { .. };                    // identifier, type
    ($($x:expr),* $(,)?) => { $( f($x); )* };       // repetition, optional trailing comma
    ($($k:expr => $v:expr),*) => { .. };            // pairs
    (@internal $acc:expr; $($rest:tt)*) => { .. };  // internal rule + tt muncher
    ($x:tt) => { compile_error!("..") };            // last resort: clear error
}