20.1.1. Metavariables¶

Syntax

MacroMetavariableMatch ::=
    $ MacroMetavariable : MacroFragmentSpecifier

MacroMetavariable ::=
    Keyword
  | NonKeywordIdentifier

MacroFragmentSpecifier ::=
    block
  | expr
  | expr_2021
  | ident
  | item
  | lifetime
  | literal
  | meta
  | pat
  | pat_param
  | path
  | stmt
  | tt
  | ty
  | vis

MacroMetavariableIndication ::=
    $ MacroMetavariable

Legality Rules

20.1.1:1 Declarative macros employ metavariables to match a token of a particular kind and bind its value to a name for use during macro transcription.

20.1.1:2 A metavariable is a macro match that describes a variable.

20.1.1:3 A metavariable is visible in the macro transcriber of the macro rule of the macro matcher it is declared in.

20.1.1:4 A fragment specifier is a construct that indicates the type of a metavariable.

20.1.1:5 Fragment specifier kinds impose the following fragment specifier restrictions on the tokens that follow them:

• 20.1.1:6 expr and expr_2021 shall only be followed by =>, ,, or ;.

• 20.1.1:7 pat shall only be followed by =>, ,, =, |, if, or in.

• 20.1.1:8 path shall only be followed by =>, ,, =, |, ;, :, >, >>, [, {, as, where, or a metavariable with the block fragment specifier kind.

• 20.1.1:9 pat_param shall only be followed by =>, ,, =, |, if, or in.

• 20.1.1:10 stmt shall only be followed by =>, ,, or ;.

• 20.1.1:11 ty shall only be followed by =>, ,, =, |, ;, :, >, >>, [, {, as, where, or a metavariable with the block fragment specifier kind.

• 20.1.1:12 vis shall only be followed by ,, an identifier except for priv, any token that may begin a TypeSpecification, or a metavariable with the ident, ty or block fragment specifier kind.

• 20.1.1:13 Any other kind may be followed by any token.

20.1.1:14 A metavariable indication is a construct that indicates a metavariable.

Examples

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

20.1.2. Repetition¶

Syntax

MacroRepetitionMatch ::=
    $ ( MacroRepetitionMatchContent ) MacroRepetitionSeparator? MacroRepetitionOperator

MacroRepetitionMatchContent ::=
    MacroMatch*

MacroRepetitionTranscriber ::=
    $ ( TokenTree* ) MacroRepetitionSeparator? MacroRepetitionOperator

MacroRepetitionOperator ::=
    +
  | *
  | ?

20.1.2:1 A MacroRepetitionSeparator is any lexical element in category LexicalElement, except punctuation +, *, ?, and category Delimiter.

Legality Rules

20.1.2:2 A macro repetition in matching allows for a syntactic pattern to be matched zero or multiple times during macro matching.

20.1.2:3 A macro repetition in transcription allows for a syntactic pattern to be transcribed zero or multiple times during macro transcription.

20.1.2:4 A macro repetition is either a macro repetition in matching or a macro repetition in transcription.

20.1.2:5 A repetition operator is a construct that indicates the number of times a macro repetition in matching or a macro repetition in transcription can be repeated.

20.1.2:6 The effects of a repetition operator are as follows:

• 20.1.2:7 * - Zero or more repetitions.

• 20.1.2:8 + - One or more repetitions.

• 20.1.2:9 ? - Zero or one repetition.

20.1.2:10 A macro repetition has the following additional restrictions:

• 20.1.2:11 If the macro repetition has a separator, the separator shall be allowed by the MacroRepetitionMatchContent‘s fragment specifier restrictions.

• 20.1.2:12 If the repetition operator is * or +, then the possible beginnings of the MacroRepetitionMatchContent shall be allowed by its MacroRepetitionMatchContent‘s fragment specifier restrictions.

• 20.1.2:13 If the repetition operator is ? or *, then the succeeding MacroMatch must be allowed by the preceding MacroMatch‘s fragment specifier restrictions.

• 20.1.2:14 The possible beginnings of the MacroRepetitionMatchContent must be allowed by the preceding MacroMatch‘s fragment specifier restrictions.

• 20.1.2:15 The succeeding MacroMatch must be allowed by the possible endings of the MacroRepetitionMatchContent‘s fragment specifier restrictions.

Examples

macro_rules! generate_pairs {
    ( $( $first:ident )* ; $( &second:ident )* )
        =>
    { $( $first, $second )* };
}

20.2.1. Function-like Macros¶

Legality Rules

20.2.1:1 A function-like macro is a procedural macro that consumes a stream of tokens and produces a stream of tokens.

20.2.1:2 The macro implementation function of a function-like macro shall be subject to the following restrictions:

• 20.2.1:3 It shall be subject to attribute proc_macro,

• 20.2.1:4 It shall be subject to visibility modifier pub,

• 20.2.1:5 It shall lack function qualifiers,

• 20.2.1:6 It shall lack generic parameters,

• 20.2.1:7 It shall have a single function parameter whose type specification indicates type proc_macro::TokenStream,

• 20.2.1:8 It shall have a return type whose type specification indicates type proc_macro::TokenStream.

20.2.1:9 A function-like macro is invoked using a macro invocation.

20.2.1:10 The sole parameter of the macro implementation function captures the token stream produced from the DelimitedTokenTree of the macro invocation, excluding outer Delimiters.

Examples

#[proc_macro]
pub fn make_answer_to_life(_items: TokenStream) -> TokenStream {
    "fn answer_to_life() -> u32 { 42 }".parse().unwrap()
}

20.2.2. Derive Macros¶

Legality Rules

20.2.2:1 A derive macro is a procedural macro that consumes a stream of tokens and produces a stream of tokens. Derive macros are used to construct new syntax for abstract data types.

20.2.2:2 The macro implementation function of a derive macro shall be subject to the following restrictions:

• 20.2.2:3 It shall be subject to attribute proc_macro_derive,

• 20.2.2:4 It shall be subject to visibility modifier pub,

• 20.2.2:5 It shall lack function qualifiers,

• 20.2.2:6 It shall lack generic parameters,

• 20.2.2:7 It shall have a single function parameter whose type specification indicates type proc_macro::TokenStream,

• 20.2.2:8 It shall have a return type whose type specification indicates type proc_macro::TokenStream.

20.2.2:9 A derive macro is invoked using attribute derive.

20.2.2:10 The sole parameter of the macro implementation function captures the token stream produced from the related EnumDeclaration, StructDeclaration, or UnionDeclaration.

20.2.2:11 A derive macro adds all its declared derive helper attributes into the derive helper attribute scope of the abstract data type the attribute is attached to.

20.2.2:12 A derive helper attribute is an inert attribute that acts as a hint to attribute derive.

Examples

#[proc_macro_derive(Answer)]
pub fn derive_answer_to_life(_items: TokenStream) -> TokenStream {
    "fn answer_to_life() -> u32 { 42 }".parse().unwrap()
}

20.2.3. Attribute Macros¶

Legality Rules

20.2.3:1 An attribute macro is a procedural macro that consumes two streams of tokens to produce a single stream of tokens, and defines a new outer attribute that can be attached to items. Attribute macros are used to replace items with other items.

20.2.3:2 The macro implementation function of an attribute macro shall be subject to the following restrictions:

• 20.2.3:3 It shall be subject to attribute proc_macro_attribute,

• 20.2.3:4 It shall be subject to visibility modifier pub,

• 20.2.3:5 It shall lack function qualifiers,

• 20.2.3:6 It shall lack generic parameters,

• 20.2.3:7 It shall have two function parameters whose type specifications indicate type proc_macro::TokenStream,

• 20.2.3:8 It shall have a return type whose type specification indicates type proc_macro::TokenStream.

20.2.3:9 An attribute macro is invoked using an attribute of the form

• 20.2.3:10 #[SimplePath], or

• 20.2.3:11 #[SimplePath DelimitedTokenTree]

20.2.3:12 The first function parameter of the macro implementation function captures the token stream produced from the DelimitedTokenTree of the invoking attribute, excluding outer Delimiters. If no DelimitedTokenTree is provided, then the token stream is considered empty.

20.2.3:13 The second function parameter of the macro implementation function captures the token stream produced from the related item, including all outer attributes that apply to that item.

Examples

#[proc_macro_attribute]
pub fn output_and_return_item
    (attr: TokenStream, item: TokenStream) -> TokenStream
{
    println!("attr: \"{}\"", attr.to_string());
    println!("item: \"{}\"", item.to_string());
    item
}

20.4.1. Macro Matching¶

Legality Rules

20.4.1:1 Macro matching is the process of performing rule matching and token matching.

20.4.2. Macro Transcription¶

Legality Rules

20.4.2:1 Macro transcription is the process of producing the expansion of a declarative macro.

20.4.2:2 Macro transcription proceeds as follows:

20.4.2:3 Every metavariable indication found in the DelimitedTokenTree of the macro transcriber that belongs to a matched macro rule is replaced by the matched sequence of tokens of the metavariable.

20.4.2:4 Unresolved metavariable indications are kept as tokens in the output verbatim.

20.4.2:5 Every macro repetition in transcription found in the DelimitedTokenTree of the macro transcriber shall be transcribed by repeatedly transcribing the tokens inside of it.

20.4.2:6 The number of transcription repetitions for a macro repetition in transcription shall depend on its repetition operator, as follows:

• 20.4.2:7 A repetition operator denoted by + shall require one or more repetitions.

• 20.4.2:8 A repetition operator denoted by * shall require zero or more repetitions.

• 20.4.2:9 A repetition operator denoted by ? shall require zero or one repetition.

20.4.2:10 A metavariable indication that is matched inside of a macro repetition shall not be used outside of a macro repetition in transcription.

20.4.2:11 A metavariable indication shall be used in a macro repetition in transcription of the same nesting depth as its corresponding metavariable appears in the macro matcher.

20.4.2:12 A metavariable indication within a macro repetition in transcription shall repeat the same number of times in its matching macro repetition if the macro repetition occurs at the same nesting depth.

20.4.2:13 Multiple transcribed metavariable indications in the same macro repetition in transcription shall repeat the same number of times.

20.4.2:14 When transcribing a metavariable indication in a macro repetition in transcription, the metavariable indication is replaced with the matched sequence of tokens of the corresponding iteration of the repetition metavariable taken from the ordered collection.

20.4.2:15 A metavariable indication in a macro repetition in transcription shall be transcribed to the matched tokens in order, as follows:

macro_rules! foo {
    ( $($expr:expr)* ) => {
        $( $expr ; )*
        // $expr is an error
    };
    ( $( $( $expr:expr )*  )*  ) => {
        $($($expr)*)*
    }
}

foo! {
  0
  1
  2
}

20.4.2:16 yields 0;1;2;

20.4.2:17 Given a macro invocation with N metavariable arguments, a macro of the form

macro_rules! m {
    ( $(param: expr)* ) => {
        $( $param )*
    }
}

20.4.2:18 is equivalent to a macro of the form

macro_rules! m {
    ( $param_1: expr $param_2: expr ... $param_N: expr) => {
        $param_1 $param_2 ... $param_N
    }
}

20.4.2:19 where the metavariable of the macro repetition in matching are repeated N times, and the metavariable indications of the macro repetition in transcription are repeated N times. Invoking such a macro relates the first metavariable argument of the macro invocation with the first metavariable of the macro repetition in matching, the second metavariable argument with the second metavariable, and so on.