src/doc/trpl/advanced-macros.md

   1 % Advanced macros
   2
   3 This chapter picks up where the [introductory macro chapter](macros.html) left
   4 off.
   5
   6 # Syntactic requirements
   7
   8 Even when Rust code contains un-expanded macros, it can be parsed as a full
   9 [syntax tree][ast]. This property can be very useful for editors and other
  10 tools that process code. It also has a few consequences for the design of
  11 Rust's macro system.
  12
  13 [ast]: glossary.html#abstract-syntax-tree
  14
  15 One consequence is that Rust must determine, when it parses a macro invocation,
  16 whether the macro stands in for
  17
  18 * zero or more items,
  19 * zero or more methods,
  20 * an expression,
  21 * a statement, or
  22 * a pattern.
  23
  24 A macro invocation within a block could stand for some items, or for an
  25 expression / statement. Rust uses a simple rule to resolve this ambiguity. A
  26 macro invocation that stands for items must be either
  27
  28 * delimited by curly braces, e.g. `foo! { ... }`, or
  29 * terminated by a semicolon, e.g. `foo!(...);`
  30
  31 Another consequence of pre-expansion parsing is that the macro invocation must
  32 consist of valid Rust tokens. Furthermore, parentheses, brackets, and braces
  33 must be balanced within a macro invocation. For example, `foo!([)` is
  34 forbidden. This allows Rust to know where the macro invocation ends.
  35
  36 More formally, the macro invocation body must be a sequence of *token trees*.
  37 A token tree is defined recursively as either
  38
  39 * a sequence of token trees surrounded by matching `()`, `[]`, or `{}`, or
  40 * any other single token.
  41
  42 Within a matcher, each metavariable has a *fragment specifier*, identifying
  43 which syntactic form it matches.
  44
  45 * `ident`: an identifier. Examples: `x`; `foo`.
  46 * `path`: a qualified name. Example: `T::SpecialA`.
  47 * `expr`: an expression. Examples: `2 + 2`; `if true then { 1 } else { 2 }`; `f(42)`.
  48 * `ty`: a type. Examples: `i32`; `Vec<(char, String)>`; `&T`.
  49 * `pat`: a pattern. Examples: `Some(t)`; `(17, 'a')`; `_`.
  50 * `stmt`: a single statement. Example: `let x = 3`.
  51 * `block`: a brace-delimited sequence of statements. Example:
  52   `{ log(error, "hi"); return 12; }`.
  53 * `item`: an [item][]. Examples: `fn foo() { }`; `struct Bar;`.
  54 * `meta`: a "meta item", as found in attributes. Example: `cfg(target_os = "windows")`.
  55 * `tt`: a single token tree.
  56
  57 There are additional rules regarding the next token after a metavariable:
  58
  59 * `expr` variables must be followed by one of: `=> , ;`
  60 * `ty` and `path` variables must be followed by one of: `=> , : = > as`
  61 * `pat` variables must be followed by one of: `=> , =`
  62 * Other variables may be followed by any token.
  63
  64 These rules provide some flexibility for Rust's syntax to evolve without
  65 breaking existing macros.
  66
  67 The macro system does not deal with parse ambiguity at all. For example, the
  68 grammar `$($t:ty)* $e:expr` will always fail to parse, because the parser would
  69 be forced to choose between parsing `$t` and parsing `$e`. Changing the
  70 invocation syntax to put a distinctive token in front can solve the problem. In
  71 this case, you can write `$(T $t:ty)* E $e:exp`.
  72
  73 [item]: ../reference.html#items
  74
  75 # Scoping and macro import/export
  76
  77 Macros are expanded at an early stage in compilation, before name resolution.
  78 One downside is that scoping works differently for macros, compared to other
  79 constructs in the language.
  80
  81 Definition and expansion of macros both happen in a single depth-first,
  82 lexical-order traversal of a crate's source. So a macro defined at module scope
  83 is visible to any subsequent code in the same module, which includes the body
  84 of any subsequent child `mod` items.
  85
  86 A macro defined within the body of a single `fn`, or anywhere else not at
  87 module scope, is visible only within that item.
  88
  89 If a module has the `macro_use` attribute, its macros are also visible in its
  90 parent module after the child's `mod` item. If the parent also has `macro_use`
  91 then the macros will be visible in the grandparent after the parent's `mod`
  92 item, and so forth.
  93
  94 The `macro_use` attribute can also appear on `extern crate`. In this context
  95 it controls which macros are loaded from the external crate, e.g.
  96
  97 ```rust,ignore
  98 #[macro_use(foo, bar)]
  99 extern crate baz;
 100 ```
 101
 102 If the attribute is given simply as `#[macro_use]`, all macros are loaded. If
 103 there is no `#[macro_use]` attribute then no macros are loaded. Only macros
 104 defined with the `#[macro_export]` attribute may be loaded.
 105
 106 To load a crate's macros *without* linking it into the output, use `#[no_link]`
 107 as well.
 108
 109 An example:
 110
 111 ```rust
 112 macro_rules! m1 { () => (()) }
 113
 114 // visible here: m1
 115
 116 mod foo {
 117     // visible here: m1
 118
 119     #[macro_export]
 120     macro_rules! m2 { () => (()) }
 121
 122     // visible here: m1, m2
 123 }
 124
 125 // visible here: m1
 126
 127 macro_rules! m3 { () => (()) }
 128
 129 // visible here: m1, m3
 130
 131 #[macro_use]
 132 mod bar {
 133     // visible here: m1, m3
 134
 135     macro_rules! m4 { () => (()) }
 136
 137     // visible here: m1, m3, m4
 138 }
 139
 140 // visible here: m1, m3, m4
 141 # fn main() { }
 142 ```
 143
 144 When this library is loaded with `#[macro_use] extern crate`, only `m2` will
 145 be imported.
 146
 147 The Rust Reference has a [listing of macro-related
 148 attributes](../reference.html#macro--and-plugin-related-attributes).
 149
 150 # The variable `$crate`
 151
 152 A further difficulty occurs when a macro is used in multiple crates. Say that
 153 `mylib` defines
 154
 155 ```rust
 156 pub fn increment(x: u32) -> u32 {
 157     x + 1
 158 }
 159
 160 #[macro_export]
 161 macro_rules! inc_a {
 162     ($x:expr) => ( ::increment($x) )
 163 }
 164
 165 #[macro_export]
 166 macro_rules! inc_b {
 167     ($x:expr) => ( ::mylib::increment($x) )
 168 }
 169 # fn main() { }
 170 ```
 171
 172 `inc_a` only works within `mylib`, while `inc_b` only works outside the
 173 library. Furthermore, `inc_b` will break if the user imports `mylib` under
 174 another name.
 175
 176 Rust does not (yet) have a hygiene system for crate references, but it does
 177 provide a simple workaround for this problem. Within a macro imported from a
 178 crate named `foo`, the special macro variable `$crate` will expand to `::foo`.
 179 By contrast, when a macro is defined and then used in the same crate, `$crate`
 180 will expand to nothing. This means we can write
 181
 182 ```rust
 183 #[macro_export]
 184 macro_rules! inc {
 185     ($x:expr) => ( $crate::increment($x) )
 186 }
 187 # fn main() { }
 188 ```
 189
 190 to define a single macro that works both inside and outside our library. The
 191 function name will expand to either `::increment` or `::mylib::increment`.
 192
 193 To keep this system simple and correct, `#[macro_use] extern crate ...` may
 194 only appear at the root of your crate, not inside `mod`. This ensures that
 195 `$crate` is a single identifier.
 196
 197 # The deep end
 198
 199 The introductory chapter mentioned recursive macros, but it did not give the
 200 full story. Recursive macros are useful for another reason: Each recursive
 201 invocation gives you another opportunity to pattern-match the macro's
 202 arguments.
 203
 204 As an extreme example, it is possible, though hardly advisable, to implement
 205 the [Bitwise Cyclic Tag](http://esolangs.org/wiki/Bitwise_Cyclic_Tag) automaton
 206 within Rust's macro system.
 207
 208 ```rust
 209 macro_rules! bct {
 210     // cmd 0:  d ... => ...
 211     (0, $($ps:tt),* ; $_d:tt)
 212         => (bct!($($ps),*, 0 ; ));
 213     (0, $($ps:tt),* ; $_d:tt, $($ds:tt),*)
 214         => (bct!($($ps),*, 0 ; $($ds),*));
 215
 216     // cmd 1p:  1 ... => 1 ... p
 217     (1, $p:tt, $($ps:tt),* ; 1)
 218         => (bct!($($ps),*, 1, $p ; 1, $p));
 219     (1, $p:tt, $($ps:tt),* ; 1, $($ds:tt),*)
 220         => (bct!($($ps),*, 1, $p ; 1, $($ds),*, $p));
 221
 222     // cmd 1p:  0 ... => 0 ...
 223     (1, $p:tt, $($ps:tt),* ; $($ds:tt),*)
 224         => (bct!($($ps),*, 1, $p ; $($ds),*));
 225
 226     // halt on empty data string
 227     ( $($ps:tt),* ; )
 228         => (());
 229 }
 230 ```
 231
 232 Exercise: use macros to reduce duplication in the above definition of the
 233 `bct!` macro.
 234
 235 # Procedural macros
 236
 237 If Rust's macro system can't do what you need, you may want to write a
 238 [compiler plugin](plugins.html) instead. Compared to `macro_rules!`
 239 macros, this is significantly more work, the interfaces are much less stable,
 240 and bugs can be much harder to track down. In exchange you get the
 241 flexibility of running arbitrary Rust code within the compiler. Syntax
 242 extension plugins are sometimes called *procedural macros* for this reason.