2.1 Invocation location

A macro invocation may take the place of (and therefore expand to) an expression, an item, or a statement. The Rust parser will parse the macro invocation as a "placeholder" for whichever of those three nonterminals is appropriate for the location.

At expansion time, the output of the macro will be parsed as whichever of the three nonterminals it stands in for. This means that a single macro might, for example, expand to an item or an expression, depending on its arguments (and cause a syntax error if it is called with the wrong argument for its location). Although this behavior sounds excessively dynamic, it is known to be useful under some circumstances.

3.1 Interpolation location

The interpolation $argument_name may appear in any location consistent with its fragment specifier (i.e., if it is specified as ident, it may be used anywhere an identifier is permitted).

4.1 Invocation

Going back to the motivating example, recall that early_return expanded into a match that would return if the match's scrutinee matched the "special case" identifier provided as the second argument to early_return, and do nothing otherwise. Now suppose that we wanted to write a version of early_return that could handle a variable number of "special" cases.

The syntax $(...)* on the left-hand side of the => in a macro definition accepts zero or more occurrences of its contents. It works much like the * operator in regular expressions. It also supports a separator token (a comma-separated list could be written $(...),*), and + instead of * to mean "at least one".

macro_rules! early_return(
    ($inp:expr, [ $($sp:ident)|+ ]) => (
        match $inp {
            $(
                $sp(x) => { return x; }
            )+
            _ => {}
        }
    );
)
// ...
early_return!(input_1, [special_a|special_c|special_d]);
// ...
early_return!(input_2, [special_b]);

4.2 Parsing limitations

For technical reasons, there are two limitations to the treatment of syntax fragments by the macro parser:

1. The parser will always parse as much as possible of a Rust syntactic fragment. For example, if the comma were omitted from the syntax of early_return! above, input_1 [ would've been interpreted as the beginning of an array index. In fact, invoking the macro would have been impossible.
2. The parser must have eliminated all ambiguity by the time it reaches a $name:fragment_specifier declaration. This limitation can result in parse errors when declarations occur at the beginning of, or immediately after, a $(...)*. For example, the grammar $($t:ty)* $e:expr will always fail to parse because the parser would be forced to choose between parsing t and parsing e. Changing the invocation syntax to require a distinctive token in front can solve the problem. In the above example, $(T $t:ty)* E $e:exp solves the problem.

5.1 Motivation

match x {
    good_1(g1, val) => {
        match g1.body {
            good_2(result) => {
                // complicated stuff goes here
                return result + val;
            },
            _ => fail!("Didn't get good_2")
        }
    }
    _ => return 0 // default value
}

All the complicated stuff is deeply indented, and the error-handling code is separated from matches that fail. We'd like to write a macro that performs a match, but with a syntax that suits the problem better. The following macro can solve the problem:

macro_rules! biased_match (
    // special case: `let (x) = ...` is illegal, so use `let x = ...` instead
    ( ($e:expr) ~ ($p:pat) else $err:stmt ;
      binds $bind_res:ident
    ) => (
        let $bind_res = match $e {
            $p => ( $bind_res ),
            _ => { $err }
        };
    );
    // more than one name; use a tuple
    ( ($e:expr) ~ ($p:pat) else $err:stmt ;
      binds $( $bind_res:ident ),*
    ) => (
        let ( $( $bind_res ),* ) = match $e {
            $p => ( $( $bind_res ),* ),
            _ => { $err }
        };
    )
)

biased_match!((x)       ~ (good_1(g1, val)) else { return 0 };
              binds g1, val )
biased_match!((g1.body) ~ (good_2(result) )
                  else { fail!("Didn't get good_2") };
              binds result )
// complicated stuff goes here
return result + val;

This solves the indentation problem. But if we have a lot of chained matches like this, we might prefer to write a single macro invocation. The input pattern we want is clear:

    ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*
      binds $( $bind_res:ident ),*
    )

However, it's not possible to directly expand to nested match statements. But there is a solution.

5.2 The recursive approach to macro writing

A macro may accept multiple different input grammars. The first one to successfully match the actual argument to a macro invocation is the one that "wins".

In the case of the example above, we want to write a recursive macro to process the semicolon-terminated lines, one-by-one. So, we want the following input patterns:

    ( binds $( $bind_res:ident ),* )

...and:

    (    ($e     :expr) ~ ($p     :pat) else $err     :stmt ;
      $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )*
      binds  $( $bind_res:ident ),*
    )

The resulting macro looks like this. Note that the separation into biased_match! and biased_match_rec! occurs only because we have an outer piece of syntax (the let) which we only want to transcribe once.

macro_rules! biased_match_rec (
    // Handle the first layer
    (   ($e     :expr) ~ ($p     :pat) else $err     :stmt ;
     $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )*
     binds $( $bind_res:ident ),*
    ) => (
        match $e {
            $p => {
                // Recursively handle the next layer
                biased_match_rec!($( ($e_rest) ~ ($p_rest) else $err_rest ; )*
                                  binds $( $bind_res ),*
                )
            }
            _ => { $err }
        }
    );
    ( binds $( $bind_res:ident ),* ) => ( ($( $bind_res ),*) )
)

// Wrap the whole thing in a `let`.
macro_rules! biased_match (
    // special case: `let (x) = ...` is illegal, so use `let x = ...` instead
    ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*
      binds $bind_res:ident
    ) => (
        let ( $( $bind_res ),* ) = biased_match_rec!(
            $( ($e) ~ ($p) else $err ; )*
            binds $bind_res
        );
    );
    // more than one name: use a tuple
    ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*
      binds  $( $bind_res:ident ),*
    ) => (
        let ( $( $bind_res ),* ) = biased_match_rec!(
            $( ($e) ~ ($p) else $err ; )*
            binds $( $bind_res ),*
        );
    )
)


biased_match!(
    (x)       ~ (good_1(g1, val)) else { return 0 };
    (g1.body) ~ (good_2(result) ) else { fail!("Didn't get good_2") };
    binds val, result )
// complicated stuff goes here
return result + val;

This technique applies to many cases where transcribing a result all at once is not possible. The resulting code resembles ordinary functional programming in some respects, but has some important differences from functional programming.

The first difference is important, but also easy to forget: the transcription (right-hand) side of a macro_rules! rule is literal syntax, which can only be executed at run-time. If a piece of transcription syntax does not itself appear inside another macro invocation, it will become part of the final program. If it is inside a macro invocation (for example, the recursive invocation of biased_match_rec!), it does have the opportunity to affect transcription, but only through the process of attempted pattern matching.

The second, related, difference is that the evaluation order of macros feels "backwards" compared to ordinary programming. Given an invocation m1!(m2!()), the expander first expands m1!, giving it as input the literal syntax m2!(). If it transcribes its argument unchanged into an appropriate position (in particular, not as an argument to yet another macro invocation), the expander will then proceed to evaluate m2!() (along with any other macro invocations m1!(m2!()) produced).