Rust Macros: macro_rules! Patterns, Hygiene, and Procedural Macros
Matcher fragments, repetition, hygiene and the proc-macro crate. How to read a macro_rules! error and when a derive macro is the right tool.

Quick Summary
Rust has two macro systems. Declarative macros (macro_rules!) match token patterns and expand to code at compile time; they need no extra crate and cover most "write this boilerplate for me" cases. Procedural macros are functions that receive a TokenStream and return a TokenStream; they require a separate proc-macro = true crate and are the only way to derive traits or transform items.
macro_rules! is pattern matching over syntax. Each rule is (matcher) => { transcriber }, matchers use fragment specifiers ($x:expr, $name:ident, $t:ty, $($rest:tt)*), and repetition is written $( ... ),*. Hygiene is partial: variables created inside the macro are invisible to the caller, but item names and paths are not, which is why exported macros reference $crate:: instead of crate::.
Procedural macros come in three flavours with distinct attributes: #[proc_macro_derive(Trait)] for derives, #[proc_macro_attribute] for attribute-style wrappers, and #[proc_macro] for function-like invocation. All three work on token streams, so nearly every real implementation pairs them with syn (parsing) and quote (generation).
Basic Syntax & Signature
// Declarative macro: variadic constructor with a trailing comma allowed.
macro_rules! map {
() => { std::collections::HashMap::new() };
($($key:expr => $value:expr),* $(,)?) => {{
let mut m = std::collections::HashMap::new();
$( m.insert($key, $value); )*
m
}};
}
// Repetition with an index-free body: builds a Vec of tuples.
macro_rules! pairs {
($($k:expr => $v:expr),* $(,)?) => {
vec![ $( ($k, $v) ),* ]
};
}
// A macro that generates an item: item fragment specifiers.
macro_rules! make_getter {
($name:ident, $ty:ty) => {
pub fn $name(&self) -> &$ty {
&self.$name
}
};
}
struct Config { host: String, port: u16 }
impl Config {
make_getter!(host, String);
make_getter!(port, u16);
}
// Recursive "tt muncher": consumes token trees one at a time.
macro_rules! count_idents {
() => { 0usize };
($head:ident $($tail:ident)*) => { 1usize + count_idents!($($tail)*) };
}
fn main() {
let m = map! { "a" => 1, "b" => 2, };
assert_eq!(m.len(), 2);
let p = pairs!(1 => "one", 2 => "two");
assert_eq!(p[1], (2, "two"));
let c = Config { host: "localhost".into(), port: 8080 };
assert_eq!(c.host(), "localhost");
assert_eq!(*c.port(), 8080);
assert_eq!(count_idents!(a b c d), 4);
}The matcher fragment specifiers, and what they accept:
| Specifier | Matches | Notes |
|---|---|---|
$x:expr | An expression | Follow set restricted; cannot be followed by + in older editions |
$x:ident | An identifier or keyword | Used for names and field access |
$x:ty | A type | Follow set: {, [, ,, >, =, :, =>, ;, ` |
$x:path | A path | foo::bar, crate::x |
$x:pat | A pattern | pat_param variant when followed by ` |
$x:stmt | A statement | Rarely needed; hides semicolons |
$x:block | A { ... } block | Good for closures and DSL bodies |
$x:item | An item | Functions, structs, impls |
$x:literal | A literal token | Strings, numbers, chars, true |
$x:meta | An attribute body | derive(Debug), cfg(unix) |
$x:vis | A visibility | pub, pub(crate), or empty |
$x:tt | One token tree | The workhorse for recursion |
$x:lifetime | 'a | For generic parameters |
Repetition syntax: $( ... )* (zero or more), $( ... )+ (one or more), $( ... ),* with a separator, and $(,)? to allow an optional trailing comma. Repeated metavariables must appear in the transcriber with the same nesting: $( $name ),*.
Key Comparison Table
macro_rules! | Derive macro | Attribute macro | Function-like proc macro | |
|---|---|---|---|---|
| Declared with | macro_rules! name | #[proc_macro_derive(T)] | #[proc_macro_attribute] | #[proc_macro] |
| Location | Anywhere in the crate | proc-macro crate only | proc-macro crate only | proc-macro crate only |
| Input | Token pattern | DeriveInput (parsed) | Attribute args + item | Raw TokenStream |
| Runs | Expansion pass | Expansion pass | Before the item is parsed | Expansion pass |
| Typical use | Shorthand, variadics | Implementing traits | Wrapping or rewriting items | DSLs, codegen |
| Dependency | None | syn, quote | syn, quote | syn, quote |
| Can inspect types | No | Yes (via syn) | Yes | Yes |
| Errors | Compile error at match failure | compile_error! / syn::Error | compile_error! | compile_error! |
| Visible to other crates | Only with #[macro_export] | Yes, if the trait is | Yes | Yes |
Practical Edge Cases & Deep Dives
1. Hygiene: what is protected and what is not
macro_rules! make_local {
() => {
let internal_name = 1;
internal_name
};
}
macro_rules! leaky_path {
// BAD: resolves `helper` at the CALL site, not the definition site.
() => { helper() };
}
macro_rules! hygienic_path {
// GOOD: `$crate` always points at the defining crate.
() => { $crate::helper() };
}
fn helper() -> &'static str { "crate helper" }
fn main() {
let internal_name = 99;
// The macro's `internal_name` does not collide with the caller's.
assert_eq!(make_local!(), 1);
assert_eq!(internal_name, 99);
// Callers using the exported macro need no `helper` in scope.
assert_eq!(hygienic_path!(), "crate helper");
}Local variables introduced by macro_rules! carry a syntax context, so they cannot shadow or be shadowed by caller variables. Items, types and paths are not hygienic in the same way — a name inside a macro body resolves where the macro is expanded unless prefixed with $crate::. This is why nearly every published macro crate writes $crate:: in its expansions, and why older crates used #[macro_export(local_inner_macros)].
2. Recursion for a variadic constructor with mixed arms
macro_rules! json_like {
// Base case: null.
(null) => { serde_value::Value::Null };
// String literal.
($s:literal) => { serde_value::Value::String($s.to_string()) };
// Object: recurse over key: value pairs.
({ $($k:literal : $v:tt),* $(,)? }) => {{
let mut map = std::collections::BTreeMap::new();
$( map.insert($k.to_string(), json_like!($v)); )*
serde_value::Value::Map(map)
}};
}
mod serde_value {
#[derive(Debug, PartialEq)]
pub enum Value { Null, String(String), Map(std::collections::BTreeMap<String, Value>) }
}
fn main() {
let v = json_like!({ "a": "x", "b": null });
if let serde_value::Value::Map(m) = v {
assert_eq!(m.len(), 2);
assert_eq!(m["a"], serde_value::Value::String("x".into()));
}
}The tt matcher is what makes recursion possible: it accepts exactly one token tree, so a nested { ... } passes through untouched and is re-matched by the object arm. This "tt muncher" pattern is how vec!, println!, and the nom combinators handle arbitrary nesting.
3. A derive macro with syn and quote
// In crate `my_derive`, Cargo.toml: [lib] proc-macro = true
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};
#[proc_macro_derive(Describe, attributes(describe))]
pub fn describe(input: TokenStream) -> TokenStream {
let ast = parse_macro_input!(input as DeriveInput);
let name = &ast.ident;
// Read a helper attribute: #[describe(prefix = "cfg")]
let mut prefix = String::new();
for attr in &ast.attrs {
if attr.path().is_ident("describe") {
let _ = attr.parse_nested_meta(|meta| {
if meta.path.is_ident("prefix") {
let lit: syn::LitStr = meta.value()?.parse()?;
prefix = lit.value();
}
Ok(())
});
}
}
let expanded = quote! {
impl #name {
pub fn describe(&self) -> String {
format!("{} {}", #prefix, stringify!(#name)).trim().to_string()
}
}
};
expanded.into()
}// In the consuming crate:
use my_derive::Describe;
#[derive(Describe)]
#[describe(prefix = "service")]
struct Api;
fn main() {
assert_eq!(Api.describe(), "service Api");
}quote! interpolates with #var (and #(#items),* for repetition), producing a TokenStream that becomes ordinary tokens in the caller. Note the helper attribute is declared in the derive itself (attributes(describe)); without that, the compiler rejects #[describe(...)] as an unknown attribute.
4. Attribute macro that rewrites an item
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemFn};
#[proc_macro_attribute]
pub fn timed(_attr: TokenStream, item: TokenStream) -> TokenStream {
let func = parse_macro_input!(item as ItemFn);
let sig = &func.sig;
let body = &func.block;
let name = &sig.ident;
let attrs = &func.attrs;
let vis = &func.vis;
let expanded = quote! {
#(#attrs)*
#vis #sig {
let __start = std::time::Instant::now();
let __result = (|| #body)();
eprintln!("{} took {:?}", stringify!(#name), __start.elapsed());
__result
}
};
expanded.into()
}#[timed]
fn slow_add(a: u64, b: u64) -> u64 {
std::thread::sleep(std::time::Duration::from_millis(5));
a + b
}
fn main() {
assert_eq!(slow_add(1, 2), 3);
}The wrapper must preserve the original signature, visibility, and attributes, otherwise the function silently loses pub or #[inline]. Wrapping the body in a closure keeps ? working inside the body while letting the macro observe the result.
5. Reporting errors from a proc macro instead of panicking
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};
#[proc_macro_derive(Validated)]
pub fn validated(input: TokenStream) -> TokenStream {
let ast = parse_macro_input!(input as DeriveInput);
let name = &ast.ident;
let ok = matches!(ast.data, syn::Data::Struct(_));
if !ok {
// Emit a diagnostic at the item, not a panic.
return syn::Error::new_spanned(name, "Validated can only be derived for structs")
.to_compile_error()
.into();
}
quote! { impl #name { pub fn is_valid(&self) -> bool { true } } }.into()
}A panic! inside a proc macro also fails the build, but the message loses span information and points at the macro call rather than the offending field. syn::Error::new_spanned produces a proper clickable diagnostic. For a partially parsed input, parse_macro_input! returns the error as tokens automatically.
6. Debugging macros: cargo expand and stringify!
macro_rules! show {
($($t:tt)*) => {
println!("{} = {:?}", stringify!($($t)*), { $($t)* })
};
}
fn main() {
let x = 1 + 2;
show!(x * 3);
// prints: x * 3 = 9
}stringify! turns the tokens back into a string, which is invaluable when a matcher arm is not firing: print the pattern you think matched. cargo expand (install with cargo install cargo-expand) shows the fully expanded code, the fastest way to see why a macro produced code that does not compile. cargo rustc -- -Zunpretty=expanded works on nightly without the extra binary.
Common Compilation/Runtime Mistakes
| Error / symptom | Cause | Fix |
|---|---|---|
no rules expected this token in macro call | Matcher does not accept the shape given | Add an arm, or accept tt and recurse |
macro expansion ignores token ',' and any following | Repetition separator mismatch | Use $( ... ),* matching the transcriber |
cannot find macro 'foo' in this scope | Macro defined after use, or not exported | Move the definition up, #[macro_export], or use crate::foo |
expected expression, found ';' | $x:expr followed by something outside its follow set | Wrap in a block, or match tt |
| Cannot use a macro in expression position | $x:stmt or item macro used where an expression is required | Restructure to block or expr |
| Derive macro not found | proc-macro crate missing, or not in [dependencies] | Separate crate with proc-macro = true |
| Proc macro cannot be used in its own crate | Cargo forbids self-use | Move the derive to a sibling crate |
unexpected end of input inside a proc macro | syn parse failure on unfamiliar syntax | Return syn::Error::to_compile_error() |
$crate unresolved in an exported macro | 2015-edition style path | Use $crate:: and #[macro_export] |
| Macro expansion yields a huge error cascade | Generated code lacks spans | quote_spanned! with the original span |
One habit that prevents most macro bugs: keep the matcher narrow and the transcriber deliberately parenthesized. A transcriber that returns { let a = 1; a } protects callers from operator-precedence surprises; a transcriber that returns a bare expression lets macro!() + 1 associate in ways the author never intended.
Try matching browser tools
All toolsSmall utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Rust guides
All Rust guidesRust Unsafe: Raw Pointers, FFI Bindings, and Soundness Invariants
What unsafe actually unlocks, the five soundness contracts behind raw pointers, and the FFI rules for repr(C), CString and unwinding.
Rust Pin and Unpin: Memory Pinning, Self-Referential Structs, and Futures
Why a future must not move after polling starts, what Unpin opts out of, and how Box::pin, pin! and map_unchecked_mut express that guarantee.
Rust Arrays and Slices: Fixed Arrays, &[T] Fat Pointers, and DSTs
An array carries its length in its type; a slice carries it in the pointer. The split_at_mut, chunks and TryFrom patterns that follow from that.
Rust Serde: JSON Serialization, Derive Macros, and Field Attributes
Serde attributes decide the wire format: rename strategies, defaults, flatten, enum tags and custom codecs, plus the number and ordering traps.
More in Rust
All Rust guidesThe guides filed next to this one in Rust, in library order.