.RS File Format – Macros

Invocation

A macro is invoked by its path, ! and a delimited token tree, in any of the three delimiters: m!(…), m![…] or m!{…}. An invocation may appear as an expression, a statement, an item, a type, a pattern, and an item in a trait, impl or extern block. Invocations in statement or item position that use parentheses or square brackets end in a semicolon. Derive and attribute macros are invoked as attributes.

macro_rules

MacroRulesDefinition:
    macro_rules ! IDENTIFIER MacroRulesDef

MacroRulesDef:
      ( MacroRules ) ;
    | [ MacroRules ] ;
    | { MacroRules }

MacroRules:     MacroRule ( ; MacroRule )* ;?
MacroRule:      MacroMatcher => MacroTranscriber
MacroMatcher:   ( MacroMatch* ) | [ MacroMatch* ] | { MacroMatch* }

MacroMatch:
      Token except $ and delimiters
    | MacroMatcher
    | $ ( IDENTIFIER_OR_KEYWORD except crate | RAW_IDENTIFIER ) : MacroFragSpec
    | $ ( MacroMatch+ ) MacroRepSep? MacroRepOp

MacroRepOp:       * | + | ?
MacroTranscriber: DelimTokenTree

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

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

A rule has a matcher and a transcriber. The expander tries the rules in order and transcribes the first that matches. If that transcription produces a compile error, later rules are not tried. The outer delimiters of a matcher match any pair of delimiters. $ cannot be matched or transcribed literally.

Matching has no lookahead. In $($i:ident)* $j:ident the parser cannot tell where the repetition ends, and it reports a local ambiguity.

Scoping

A macro has two kinds of scope.

• Textual scope is based on source order, like a let binding but also at module level. A macro is in scope from its definition until the enclosing scope closes, and this extends into child modules, including in other files. Redefining a macro is not an error: the latest definition shadows the earlier one while in scope.
• Path-based scope works like other items and needs a #[macro_export] or a use re-export such as pub(crate) use m;.

An unqualified m!() checks textual scope first, then path-based scope. A qualified path checks only path-based scope.

Hygiene

Macros by example use mixed-site hygiene: local variables and loop or block labels are resolved where the macro is defined, and everything else (functions, types, other macros) is resolved where it is invoked.

let x = 1;
fn func() { unreachable!("this is never called") }

macro_rules! check {
    () => {
        assert_eq!(x, 1);  // the definition-site x
        func();            // the invocation-site func
    };
}

{
    let x = 2;
    fn func() { /* does not panic */ }
    check!();              // passes
}

A local variable or label introduced by one expansion is not visible to another expansion.

$crate refers to the crate that defined the macro, so a macro can reach items in its own crate from anywhere: $crate::inner::foo(). It does not change visibility: a call to a private item still fails.

Procedural macros

A procedural macro is a function that runs at compile time, in a crate of type proc-macro (with Cargo, [lib] proc-macro = true). It must be defined in the crate root and cannot be used in the crate that defines it. It works on proc_macro::TokenStream values, and has the same security implications as a build script: a procedural macro runs arbitrary code with the compiler’s access.

use proc_macro::TokenStream;

#[proc_macro]
pub fn make_answer(_item: TokenStream) -> TokenStream {
    "fn answer() -> u32 { 42 }".parse().unwrap()
}

#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    TokenStream::new()
}

#[proc_macro_attribute]
pub fn return_as_is(_attr: TokenStream, item: TokenStream) -> TokenStream {
    item
}

• Function-like macros take the tokens inside the delimiters and replace the whole invocation with the result.
• Derive macros take the item’s tokens and add new items after it. A derive macro can declare inert helper attributes in attributes(…) for use on the item’s fields and variants.
• Attribute macros take the tokens of their argument and of the item, and replace the item with the output.
• Procedural macros are not hygienic: output behaves as if written inline. Use absolute paths such as ::std::option::Option.
• A macro reports errors by panicking or by producing a compile_error! invocation.

The tokens differ slightly from those of macro_rules. Multi-character operators arrive as single characters, lifetimes arrive as ' and an identifier, negative literals can be a single token, and doc comments have already been turned into #[doc = "…"] attributes.

Built-in macros

These macros come with the standard library or the compiler (std macro list).

The format! family takes a format string, checked at compile time. A replacement field is written {}, and can name its argument and give options after a colon.