src/doc/reference/src/macros-by-example.md

   1 # Macros By Example
   2
   3 `macro_rules` allows users to define syntax extension in a declarative way.  We
   4 call such extensions "macros by example" or simply "macros".
   5
   6 Currently, macros can expand to expressions, statements, items, or patterns.
   7
   8 (A `sep_token` is any token other than `*` and `+`. A `non_special_token` is
   9 any token other than a delimiter or `$`.)
  10
  11 The macro expander looks up macro invocations by name, and tries each macro
  12 rule in turn. It transcribes the first successful match. Matching and
  13 transcription are closely related to each other, and we will describe them
  14 together.
  15
  16 The macro expander matches and transcribes every token that does not begin with
  17 a `$` literally, including delimiters. For parsing reasons, delimiters must be
  18 balanced, but they are otherwise not special.
  19
  20 In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the Rust
  21 syntax named by _designator_. Valid designators are:
  22
  23 * `item`: an [item]
  24 * `block`: a [block]
  25 * `stmt`: a [statement]
  26 * `pat`: a [pattern]
  27 * `expr`: an [expression]
  28 * `ty`: a [type]
  29 * `ident`: an [identifier] or [keyword]
  30 * `path`: a [path]
  31 * `tt`: a token tree (a single [token] by matching `()`, `[]`, or `{}`)
  32 * `meta`: the contents of an [attribute]
  33
  34 [item]: items.html
  35 [block]: expressions/block-expr.html
  36 [statement]: statements.html
  37 [pattern]: expressions/match-expr.html
  38 [expression]: expressions.html
  39 [type]: types.html
  40 [identifier]: identifiers.html
  41 [keyword]: keywords.html
  42 [path]: paths.html
  43 [token]: tokens.html
  44 [attribute]: attributes.html
  45
  46 In the transcriber, the
  47 designator is already known, and so only the name of a matched nonterminal comes
  48 after the dollar sign.
  49
  50 In both the matcher and transcriber, the Kleene star-like operator indicates
  51 repetition. The Kleene star operator consists of `$` and parentheses, optionally
  52 followed by a separator token, followed by `*` or `+`. `*` means zero or more
  53 repetitions, `+` means at least one repetition. The parentheses are not matched or
  54 transcribed. On the matcher side, a name is bound to _all_ of the names it
  55 matches, in a structure that mimics the structure of the repetition encountered
  56 on a successful match. The job of the transcriber is to sort that structure
  57 out.
  58
  59 The rules for transcription of these repetitions are called "Macro By Example".
  60 Essentially, one "layer" of repetition is discharged at a time, and all of them
  61 must be discharged by the time a name is transcribed. Therefore, `( $( $i:ident
  62 ),* ) => ( $i )` is an invalid macro, but `( $( $i:ident ),* ) => ( $( $i:ident
  63 ),*  )` is acceptable (if trivial).
  64
  65 When Macro By Example encounters a repetition, it examines all of the `$`
  66 _name_ s that occur in its body. At the "current layer", they all must repeat
  67 the same number of times, so ` ( $( $i:ident ),* ; $( $j:ident ),* ) => ( $(
  68 ($i,$j) ),* )` is valid if given the argument `(a,b,c ; d,e,f)`, but not
  69 `(a,b,c ; d,e)`. The repetition walks through the choices at that layer in
  70 lockstep, so the former input transcribes to `(a,d), (b,e), (c,f)`.
  71
  72 Nested repetitions are allowed.
  73
  74 ### Parsing limitations
  75
  76 The parser used by the macro system is reasonably powerful, but the parsing of
  77 Rust syntax is restricted in two ways:
  78
  79 1. Macro definitions are required to include suitable separators after parsing
  80    expressions and other bits of the Rust grammar. This implies that
  81    a macro definition like `$i:expr [ , ]` is not legal, because `[` could be part
  82    of an expression. A macro definition like `$i:expr,` or `$i:expr;` would be legal,
  83    however, because `,` and `;` are legal separators. See [RFC 550] for more information.
  84 2. The parser must have eliminated all ambiguity by the time it reaches a `$`
  85    _name_ `:` _designator_. This requirement most often affects name-designator
  86    pairs when they occur at the beginning of, or immediately after, a `$(...)*`;
  87    requiring a distinctive token in front can solve the problem.
  88
  89 [RFC 550]: https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.md