Macro Patterns: Fragment Specifiers and Multiple Rules

20 min read

Once you can write a basic macro_rules! macro, the next step is matching meaningfully on what the caller passed. This page is about the two tools that make macro_rules! powerful: fragment specifiers (telling Rust what kind of syntax each captured piece is) and multiple rules (overload-like dispatch on the shape of the input).

Quick Overview

A macro_rules! macro is a set of pattern-matching rules over Rust syntax, not over runtime values. Each rule has a matcher (the pattern) and a transcriber (the code it expands to). Inside a matcher you capture pieces of input into metavariables like $x, and you must tell the compiler what category of syntax each one is using a fragment specifier such as :expr, :ident, :ty, :pat, or :tt. A single macro can hold several rules and tries them top-to-bottom, which gives you arity- and shape-based overloading that ordinary Rust functions cannot express.

Note: This is the deep dive on matchers. For what a macro is (and is not — it is not a decorator or a function), see Macro Basics. For the macro_rules! syntax itself, see Declarative Macros. For the $(...)* repetition operator that pairs with these specifiers, see Repetition. The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects it automatically.

TypeScript/JavaScript Example

TypeScript and JavaScript have no compile-time macro system. There is nothing that inspects your syntax and rewrites it before compilation. When a JS/TS developer wants “the same call to behave differently depending on its arguments,” they reach for one of three runtime tricks: variadic functions with arguments/rest params, runtime branching on typeof/arguments.length, or — the closest syntactic analog — tagged template literals.

1
// macro-like-helpers.mjs — the JS toolbox that stands in for "macros"
2

3
// 1. Variadic + runtime branching on argument count/type.
4
//    This is "overloading" but it happens at RUNTIME, with type checks.
5
function min(...nums) {
6
  return nums.reduce((a, b) => (a < b ? a : b));
7
}
8

9
// 2. A factory that builds a config value at RUNTIME. There is no static
10
//    type attached to the result — TypeScript types are erased before this runs.
11
function makeConfig(key, fallback) {
12
  const raw = process.env[key];
13
  const parsed = raw === undefined ? fallback : Number(raw);
14
  return Number.isFinite(parsed) ? parsed : fallback;
15
}
16

17
// 3. A tagged template literal — the nearest JS thing to "macro-ish syntax".
18
//    `strings` and `values` are pulled apart by the runtime, then recombined.
19
function sql(strings, ...values) {
20
  return strings.reduce(
21
    (acc, s, i) => acc + s + (i < values.length ? `$${i + 1}` : ""),
22
    "",
23
  );
24
}
25

26
console.log("min =", min(8, 3, 5, 1, 9));
27
console.log("port =", makeConfig("PORT", 8080));
28
const table = "users",
29
  id = 7;
30
console.log(sql`SELECT * FROM ${table} WHERE id = ${id}`);

Running this under Node v22 prints:

1
min = 1
2
port = 8080
3
SELECT * FROM $1 WHERE id = $2

Every one of these dispatches happens while the program runs. min re-checks arguments on each call; makeConfig parses strings at runtime; the sql tag receives already-evaluated values. Crucially, by the time any of this executes, the TypeScript types are gone — generics are erased. A Rust macro does the opposite: it dispatches on syntax categories before the program is compiled, and produces real, type-checked code with zero runtime dispatch cost.

Rust Equivalent

Here is a small request-router builder. It uses two rules (overloading on shape) and four different fragment specifiers: :literal, :expr, and :ident, plus the stringify! helper.

1
// A small request-routing macro showing several fragment specifiers and
2
// multiple rules selected by the SHAPE of the input.
3
macro_rules! route {
4
    // Rule 1: a literal `GET` keyword, a string-literal path, then a handler expression.
5
    (GET $path:literal => $handler:expr) => {
6
        Route { method: "GET", path: $path, handler: $handler }
7
    };
8
    // Rule 2: any method captured as an identifier (POST, PUT, DELETE, ...).
9
    ($method:ident $path:literal => $handler:expr) => {
10
        Route { method: stringify!($method), path: $path, handler: $handler }
11
    };
12
}
13

14
struct Route {
15
    method: &'static str,
16
    path: &'static str,
17
    handler: fn() -> String,
18
}
19

20
fn list_users() -> String { "200 OK: users".to_string() }
21
fn create_user() -> String { "201 Created".to_string() }
22

23
fn main() {
24
    let routes = [
25
        route!(GET "/users" => list_users),
26
        route!(POST "/users" => create_user),
27
    ];
28
    for r in &routes {
29
        println!("{} {} -> {}", r.method, r.path, (r.handler)());
30
    }
31
}

Output:

1
GET /users -> 200 OK: users
2
POST /users -> 201 Created

The compiler picks Rule 1 for route!(GET ...) because the bare token GET matches the literal GET in the first matcher. For route!(POST ...) the first rule fails (the token is not literally GET), so it falls through to Rule 2, which captures POST as an :ident and turns it into the string "POST" with stringify!. No runtime dispatch happens — by the time main runs, each route!(...) is already a plain Route { .. } struct literal.

Detailed Explanation

Why specifiers exist at all

Rust parses your program into an abstract syntax tree. A macro matcher does not see characters — it sees a stream of token trees. When you write $x in a matcher, the compiler needs to know how much of the token stream to consume and how to validate it. That is the job of the fragment specifier after the colon: $x:expr says “parse one expression here,” $name:ident says “parse one identifier here,” and so on. This is fundamentally different from a C-style textual macro, which just pastes characters.

A captured fragment is treated as a single opaque syntax node in the output. This is the property that makes :expr safe:

1
macro_rules! square_expr {
2
    ($x:expr) => { $x * $x };
3
}
4

5
fn main() {
6
    // `2 + 3` is captured as ONE expression node, so this is (2+3)*(2+3) = 25,
7
    // NOT 2 + 3 * 2 + 3 = 11 (which is what a C-style textual macro would give).
8
    println!("square_expr!(2 + 3) = {}", square_expr!(2 + 3));
9
}

Output:

1
square_expr!(2 + 3) = 25

Even better: a macro invocation in expression position is itself a single node. So when you embed a macro call inside a larger expression, the whole expansion is grouped:

1
macro_rules! add_expr {
2
    ($x:expr) => { $x + 1 };
3
}
4

5
fn main() {
6
    // `add_expr!(2)` expands to the single node `(2 + 1)`, so this is 3 * 3 = 9,
7
    // NOT the textual `3 * 2 + 1` = 7.
8
    println!("{}", 3 * add_expr!(2));
9
}

Output:

1
9

Tip: Because :expr and macro-invocation-in-expression-position are atomic, you rarely need to add parentheses for the captured fragments. You still might choose to parenthesize the whole transcriber ({ ($x * $x) }) for defensive clarity, but the 9 above shows Rust already groups the invocation for you.

The fragment specifiers you will actually use

Specifier	Captures	Example input
`:expr`	An expression	`2 + 3`, `foo()`, `vec![1]`
`:ident`	An identifier or keyword	`count`, `String`, `GET`
`:ty`	A type	`u32`, `Vec<String>`, `&str`
`:pat`	A pattern (as in `match`/`let`)	`Some(x)`, `1..=10`, `_`
`:literal`	A literal value	`42`, `"hi"`, `3.14`, `true`
`:path`	A path	`std::cmp::max`, `Option::None`
`:block`	A brace-delimited block	`{ let x = 1; x + 1 }`
`:stmt`	A statement	`let x = 1`, `foo()`
`:tt`	A single token tree (most flexible)	`+`, `foo`, `(a, b)`, `{ .. }`
`:meta`	The contents of an attribute	`derive(Debug)`, `cfg(test)`
`:vis`	A visibility qualifier (may be empty)	`pub`, `pub(crate)`, (nothing)
`:lifetime`	A lifetime	`'a`, `'static`
`:item`	A whole item	`fn f() {}`, `struct S;`

Note: :pat in the 2021 and 2024 editions also matches or-patterns like A | B. The older, single-alternative form is available as :pat_param when you need to forbid top-level |. For everyday macros, :pat is what you want.

Here are the most common ones exercised in one program:

1
use std::collections::HashMap;
2

3
// :ident + :ty + :expr together — declare a typed constant.
4
macro_rules! declare_const {
5
    ($name:ident: $ty:ty = $value:expr) => {
6
        const $name: $ty = $value;
7
    };
8
}
9
declare_const!(MAX_RETRIES: u32 = 5);
10

11
// :pat — build a `matches!`-style check.
12
macro_rules! is_some_of {
13
    ($value:expr, $pat:pat) => {
14
        matches!($value, Some($pat))
15
    };
16
}
17

18
// :literal — only accepts literals, never variables or expressions.
19
macro_rules! describe_literal {
20
    ($l:literal) => { format!("literal: {}", $l) };
21
}
22

23
// :tt — captures any single token tree; used here to count tokens recursively.
24
macro_rules! count_tts {
25
    () => { 0 };
26
    ($head:tt $($rest:tt)*) => { 1 + count_tts!($($rest)*) };
27
}
28

29
// :block — captures a `{ ... }` block and runs it twice.
30
macro_rules! run_twice {
31
    ($b:block) => {{ $b $b }};
32
}
33

34
// :path — captures a path and calls it.
35
macro_rules! call_path {
36
    ($p:path, $arg:expr) => { $p($arg) };
37
}
38

39
fn double(n: i32) -> i32 { n * 2 }
40

41
fn main() {
42
    println!("MAX_RETRIES = {}", MAX_RETRIES);
43
    println!("is_some_of(Some(7), 1..=10) = {}", is_some_of!(Some(7i32), 1..=10));
44
    println!("{}", describe_literal!(42));
45
    println!("{}", describe_literal!("hi"));
46
    println!("count_tts!(a b c) = {}", count_tts!(a b c));
47

48
    let mut counter = 0;
49
    run_twice!({ counter += 1; });
50
    println!("counter after run_twice = {}", counter);
51

52
    println!("call_path double(21) = {}", call_path!(double, 21));
53

54
    // Avoid an unused-variable warning by reading the HashMap import in scope.
55
    let _seen: HashMap<&str, i32> = HashMap::new();
56
}

Output:

1
MAX_RETRIES = 5
2
is_some_of(Some(7), 1..=10) = true
3
literal: 42
4
literal: hi
5
count_tts!(a b c) = 3
6
counter after run_twice = 2
7
call_path double(21) = 42

`:expr` vs `:tt` — the central trade-off

:expr is strict: it parses and validates a full expression, and the result is opaque. :tt is maximally permissive: it grabs a single token tree (one token, or a balanced (...)/[...]/{...} group) without interpreting it. You reach for :tt when you need to:

accept syntax that does not fit a single fragment category (e.g. arbitrary tokens to forward elsewhere),
recurse over an unknown token stream (the count_tts! example above), or
forward tokens verbatim to another macro.

The cost of :tt is that you lose the parser’s help: nothing checks that the tokens form a valid expression until the expansion is re-parsed. For anything that is an expression, prefer :expr — you get better error messages and grouping for free.

Multiple rules: overloading by shape

A macro_rules! macro is an ordered list of (matcher) => { transcriber }; arms. The compiler tries them top to bottom and uses the first matcher that fits the entire input. This is how you emulate function overloading — something Rust functions cannot do:

1
macro_rules! greet {
2
    () => {
3
        String::from("Hello, world!")
4
    };
5
    ($name:expr) => {
6
        format!("Hello, {}!", $name)
7
    };
8
    ($greeting:expr, $name:expr) => {
9
        format!("{}, {}!", $greeting, $name)
10
    };
11
}
12

13
fn main() {
14
    println!("{}", greet!());
15
    println!("{}", greet!("Ada"));
16
    println!("{}", greet!("Hi there", "Ada"));
17
}

Output:

1
Hello, world!
2
Hello, Ada!
3
Hi there, Ada!

Because order matters, put more specific rules first. In the route! example, the GET literal rule must come before the general $method:ident rule — if the :ident rule were first, it would happily capture GET as an identifier and the specific rule would never fire.

Key Differences

Concept	TypeScript/JavaScript	Rust `macro_rules!`
When dispatch happens	Runtime (`typeof`, `arguments.length`)	Compile time, on syntax categories
What is matched	Runtime values	Token trees / syntax fragments
”Overloading”	Not real; one function body branches at runtime	Multiple rules, first match wins, zero runtime cost
Type information	Erased before execution	Fully present; expansion is type-checked normally
Grouping/precedence	N/A (values already evaluated)	Each `:expr` / invocation is one atomic node
Closest syntactic kin	Tagged template literals	Fragment specifiers + matchers
Failure mode	Throws at runtime, or silently wrong	Compile error before the program ever runs

Unlike TypeScript, where a “polymorphic” function inspects its arguments while running, a Rust macro has already chosen a rule and produced concrete code by the time compilation finishes. There is no arguments object, no runtime type check, and no per-call overhead — the macro is gone after expansion.

Unlike a JavaScript variadic function, Rust macro rules can require categories of syntax. declare_const! literally cannot be called with 1 + 1 where it expects an :ident; the compiler rejects it. JavaScript would accept anything and fail (or misbehave) later.

Common Pitfalls

Pitfall 1: A fragment is followed by a disallowed token

After certain fragment specifiers, only specific tokens may appear. In particular, an :expr fragment may only be followed by =>, ,, or ;. This follow-set rule prevents ambiguous parsing. Writing [ after an :expr is a hard error:

1
macro_rules! bad_follow {
2
    ($e:expr [ $i:expr ]) => { $e[$i] }; // does not compile
3
}
4

5
fn main() {
6
    let arr = [10, 20, 30];
7
    println!("{}", bad_follow!(arr [1]));
8
}

The real compiler error:

1
error: `$e:expr` is followed by `[`, which is not allowed for `expr` fragments
2
 --> src/main.rs:2:14
3
  |
4
2 |     ($e:expr [ $i:expr ]) => { $e[$i] };
5
  |              ^ not allowed after `expr` fragments
6
  |
7
  = note: allowed there are: `=>`, `,` or `;`

Fix: Capture the indexable thing as a :tt (or restructure the matcher to separate the pieces with an allowed delimiter such as a comma), then build the index expression in the transcriber. Here :tt accepts the single identifier arr and the parser is satisfied:

1
macro_rules! index {
2
    ($container:tt [ $i:expr ]) => { $container[$i] };
3
}
4

5
fn main() {
6
    let arr = [10, 20, 30];
7
    println!("{}", index!(arr[1])); // prints 20
8
}

Pitfall 2: Passing the wrong category of syntax

If the caller hands a macro the wrong kind of token for a specifier, the matcher simply fails to match — and because there is no other rule, you get a “no rules expected this token” error that points at the metavariable it was trying to match:

1
macro_rules! declare_const {
2
    ($name:ident: $ty:ty = $value:expr) => {
3
        const $name: $ty = $value;
4
    };
5
}
6

7
fn main() {
8
    declare_const!(1 + 1: u32 = 5); // does not compile: `1` is not an :ident
9
    println!("done");
10
}

The real compiler error:

1
error: no rules expected `1`
2
 --> src/main.rs:9:20
3
  |
4
1 | macro_rules! declare_const {
5
  | -------------------------- when calling this macro
6
...
7
9 |     declare_const!(1 + 1: u32 = 5);
8
  |                    ^ no rules expected this token in macro call
9
  |
10
note: while trying to match meta-variable `$name:ident`
11
 --> src/main.rs:2:6
12
  |
13
2 |     ($name:ident: $ty:ty = $value:expr) => {

Fix: Pass an actual identifier: declare_const!(MAX: u32 = 5);. The note: line telling you which metavariable failed to match is your most useful clue when debugging a stubborn macro call.

Pitfall 3: Rule order — the general rule shadows the specific one

The first matching rule wins, so a too-general rule placed first will swallow inputs you meant for a specific rule:

1
// BUG: the :ident rule is first, so `route!(GET ...)` never reaches the GET rule.
2
macro_rules! route {
3
    ($method:ident $path:literal => $handler:expr) => { /* always taken */ "general" };
4
    (GET $path:literal => $handler:expr) => { "specific GET" }; // unreachable in practice
5
}

This usually compiles but quietly does the wrong thing (route!(GET ...) produces "general"). Fix: Order rules from most specific to least specific, exactly as in the working route! example above.

Pitfall 4: A captured `:expr` re-used multiple times is evaluated multiple times

A metavariable substitutes the syntax, not a cached value. If you mention $x twice and the caller passes a side-effecting expression, it runs twice:

1
macro_rules! square {
2
    ($x:expr) => { $x * $x };
3
}
4

5
fn main() {
6
    let mut calls = 0;
7
    let mut next = || { calls += 1; 3 };
8
    let result = square!(next()); // expands to `next() * next()`
9
    println!("result = {result}, calls = {calls}"); // result = 9, calls = 2
10
}

Fix: Bind once with a let inside a block-transcriber so the expression is evaluated a single time:

1
macro_rules! square {
2
    ($x:expr) => {{
3
        let v = $x;
4
        v * v
5
    }};
6
}

Best Practices

Choose the most specific specifier that fits. Prefer :expr, :ident, :ty, or :pat over :tt. The stricter the specifier, the earlier and clearer the error the caller gets, and the better the grouping guarantees.
Reserve :tt for forwarding and recursion. Use it when you genuinely need raw, uninterpreted tokens — for example to count items or to pass a token stream on to another macro.
Order rules specific → general. Literal/keyword-anchored rules first, catch-all rules last, so the right arm fires.
Evaluate side-effecting :expr arguments exactly once. Bind them to a let in a {{ ... }} block before reusing them.
Use stringify!, concat!, and $crate to keep expansions robust. stringify!($x) turns captured syntax into a string literal; $crate makes a macro callable from other crates without the caller needing your crate in scope.
Reach for a function first. A macro is the right tool only when you need to operate on syntax (variadic shapes, generating items, capturing identifiers/types). If a generic function would do, write the function — see Generics and Traits.

Real-World Example

A common production need is reading typed configuration from environment variables with optional defaults — the Rust analog of the JavaScript makeConfig helper above, but type-checked at compile time. This macro uses :ident, :ty, :literal, and :expr, plus two rules (required vs. defaulted):

1
use std::collections::HashMap;
2

3
// Read a typed env var into a local binding.
4
//   config_field!(name: Type = env "KEY");                  // required
5
//   config_field!(name: Type = env "KEY", default expr);    // optional with default
6
macro_rules! config_field {
7
    ($name:ident: $ty:ty = env $key:literal) => {
8
        let $name: $ty = std::env::var($key)
9
            .ok()
10
            .and_then(|v| v.parse::<$ty>().ok())
11
            .unwrap_or_else(|| panic!("missing/invalid env var {}", $key));
12
    };
13
    ($name:ident: $ty:ty = env $key:literal, default $default:expr) => {
14
        let $name: $ty = std::env::var($key)
15
            .ok()
16
            .and_then(|v| v.parse::<$ty>().ok())
17
            .unwrap_or($default);
18
    };
19
}
20

21
// A tiny map literal: zero pairs, or one `key => value` pair.
22
macro_rules! map {
23
    () => { HashMap::new() };
24
    ($k:expr => $v:expr) => {{
25
        let mut m = HashMap::new();
26
        m.insert($k, $v);
27
        m
28
    }};
29
}
30

31
fn main() {
32
    // No env vars set here, so both fall back to their defaults.
33
    config_field!(port: u16 = env "PORT", default 8080u16);
34
    config_field!(workers: usize = env "WORKERS", default 4usize);
35
    println!("port={port} workers={workers}");
36

37
    let single: HashMap<&str, i32> = map!("answer" => 42);
38
    println!("single = {single:?}");
39
    let empty: HashMap<&str, i32> = map!();
40
    println!("empty = {empty:?}");
41
}

Output:

1
port=8080 workers=4
2
single = {"answer": 42}
3
empty = {}

The config_field! macro picks the second rule when a default ... clause is present and the first rule otherwise — a clean shape-based dispatch. Each invocation expands to an ordinary let binding with a known static type, so the rest of main type-checks exactly as if you had written the bindings by hand. The map! macro previews the repetition you will build out fully in Repetition (a real vec!-style macro that takes any number of pairs).

Exercises

Exercise 1: A variadic `min!`

Difficulty: Easy

Objective: Combine multiple rules with the :expr specifier and recursion.

Instructions:

Write a macro min! that returns the smallest of its arguments.
It must accept a single expression (min!(5) returns 5) and any number of comma-separated expressions (min!(8, 3, 5, 1, 9) returns 1).
Accept an optional trailing comma. Use a recursive rule that peels off the first argument and calls min! on the rest.
Print min!(8, 3, 5, 1, 9).

Solution

1
macro_rules! min {
2
    ($a:expr) => { $a };
3
    ($a:expr, $($rest:expr),+ $(,)?) => {{
4
        let a = $a;
5
        let b = min!($($rest),+);
6
        if a < b { a } else { b }
7
    }};
8
}
9

10
fn main() {
11
    println!("min = {}", min!(8, 3, 5, 1, 9)); // min = 1
12
    println!("single = {}", min!(42));         // single = 42
13
}

The first rule is the recursion base case (one expression). The second rule binds the head, recurses on the tail with the $(...),+ repetition, and compares. The $(,)? allows a trailing comma. Output: min = 1 then single = 42.

Exercise 2: A `getter!` method generator

Difficulty: Medium

Objective: Use the :ident and :ty specifiers together to generate code (a method), not just a value.

Instructions:

Write a macro getter!(field: Type) that expands to a method named after field returning &Type, reading self.field.
Define struct Account { owner: String, balance: u64 }.
Inside impl Account, invoke getter! twice to generate owner() and balance() accessors.
Construct an Account and print both accessor results.

Solution

1
macro_rules! getter {
2
    ($field:ident : $ty:ty) => {
3
        fn $field(&self) -> &$ty {
4
            &self.$field
5
        }
6
    };
7
}
8

9
struct Account {
10
    owner: String,
11
    balance: u64,
12
}
13

14
impl Account {
15
    getter!(owner: String);
16
    getter!(balance: u64);
17
}
18

19
fn main() {
20
    let acc = Account { owner: String::from("Ada"), balance: 100 };
21
    println!("owner={} balance={}", acc.owner(), acc.balance());
22
}

$field:ident becomes both the method name and the field name accessed via self.$field; $ty becomes the return type. Output: owner=Ada balance=100.

Exercise 3: A `match_or!` expression

Difficulty: Medium-Hard

Objective: Use the :pat specifier alongside :expr to build a control-flow construct.

Instructions:

Write a macro match_or!(value, PATTERN => RESULT, _ => DEFAULT) that expands to a match returning RESULT when value matches PATTERN (binding any captured variables for use in RESULT), and DEFAULT otherwise.
Use it on Some(42) with the pattern Some(n) to produce "got 42", and confirm None falls through to a default.

Solution

1
macro_rules! match_or {
2
    ($value:expr, $pat:pat => $result:expr, _ => $default:expr) => {
3
        match $value {
4
            $pat => $result,
5
            _ => $default,
6
        }
7
    };
8
}
9

10
fn main() {
11
    let hit = match_or!(Some(42), Some(n) => format!("got {n}"), _ => "none".to_string());
12
    println!("{hit}");
13

14
    let miss: Option<i32> = None;
15
    let label = match_or!(miss, Some(n) => format!("got {n}"), _ => "none".to_string());
16
    println!("{label}");
17
}

The $pat:pat fragment captures Some(n) as a real pattern, so the binding n is in scope inside the $result expression. Output: got 42 then none.

Macro Patterns: Fragment Specifiers and Multiple Rules

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why specifiers exist at all

The fragment specifiers you will actually use

:expr vs :tt — the central trade-off

Multiple rules: overloading by shape

Key Differences

Common Pitfalls

Pitfall 1: A fragment is followed by a disallowed token

Pitfall 2: Passing the wrong category of syntax

Pitfall 3: Rule order — the general rule shadows the specific one

Pitfall 4: A captured :expr re-used multiple times is evaluated multiple times

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A variadic min!

Exercise 2: A getter! method generator

Exercise 3: A match_or! expression

`:expr` vs `:tt` — the central trade-off

Pitfall 4: A captured `:expr` re-used multiple times is evaluated multiple times

Exercise 1: A variadic `min!`

Exercise 2: A `getter!` method generator

Exercise 3: A `match_or!` expression