]>
Commit | Line | Data |
---|---|---|
85aaf69f SL |
1 | % Macros |
2 | ||
bd371182 | 3 | By now you’ve learned about many of the tools Rust provides for abstracting and |
85aaf69f SL |
4 | reusing code. These units of code reuse have a rich semantic structure. For |
5 | example, functions have a type signature, type parameters have trait bounds, | |
6 | and overloaded functions must belong to a particular trait. | |
7 | ||
bd371182 | 8 | This structure means that Rust’s core abstractions have powerful compile-time |
85aaf69f | 9 | correctness checking. But this comes at the price of reduced flexibility. If |
bd371182 | 10 | you visually identify a pattern of repeated code, you may find it’s difficult |
85aaf69f | 11 | or cumbersome to express that pattern as a generic function, a trait, or |
bd371182 | 12 | anything else within Rust’s semantics. |
85aaf69f | 13 | |
bd371182 | 14 | Macros allow us to abstract at a syntactic level. A macro invocation is |
85aaf69f SL |
15 | shorthand for an "expanded" syntactic form. This expansion happens early in |
16 | compilation, before any static checking. As a result, macros can capture many | |
bd371182 | 17 | patterns of code reuse that Rust’s core abstractions cannot. |
85aaf69f SL |
18 | |
19 | The drawback is that macro-based code can be harder to understand, because | |
20 | fewer of the built-in rules apply. Like an ordinary function, a well-behaved | |
21 | macro can be used without understanding its implementation. However, it can be | |
22 | difficult to design a well-behaved macro! Additionally, compiler errors in | |
23 | macro code are harder to interpret, because they describe problems in the | |
24 | expanded code, not the source-level form that developers use. | |
25 | ||
bd371182 AL |
26 | These drawbacks make macros something of a "feature of last resort". That’s not |
27 | to say that macros are bad; they are part of Rust because sometimes they’re | |
85aaf69f SL |
28 | needed for truly concise, well-abstracted code. Just keep this tradeoff in |
29 | mind. | |
30 | ||
31 | # Defining a macro | |
32 | ||
62682a34 SL |
33 | You may have seen the `vec!` macro, used to initialize a [vector][vector] with |
34 | any number of elements. | |
85aaf69f | 35 | |
bd371182 | 36 | [vector]: vectors.html |
85aaf69f SL |
37 | |
38 | ```rust | |
39 | let x: Vec<u32> = vec![1, 2, 3]; | |
c34b1796 | 40 | # assert_eq!(x, [1, 2, 3]); |
85aaf69f SL |
41 | ``` |
42 | ||
bd371182 | 43 | This can’t be an ordinary function, because it takes any number of arguments. |
85aaf69f SL |
44 | But we can imagine it as syntactic shorthand for |
45 | ||
46 | ```rust | |
47 | let x: Vec<u32> = { | |
48 | let mut temp_vec = Vec::new(); | |
49 | temp_vec.push(1); | |
50 | temp_vec.push(2); | |
51 | temp_vec.push(3); | |
52 | temp_vec | |
53 | }; | |
c34b1796 | 54 | # assert_eq!(x, [1, 2, 3]); |
85aaf69f SL |
55 | ``` |
56 | ||
57 | We can implement this shorthand, using a macro: [^actual] | |
58 | ||
59 | [^actual]: The actual definition of `vec!` in libcollections differs from the | |
bd371182 | 60 | one presented here, for reasons of efficiency and reusability. |
85aaf69f SL |
61 | |
62 | ```rust | |
63 | macro_rules! vec { | |
64 | ( $( $x:expr ),* ) => { | |
65 | { | |
66 | let mut temp_vec = Vec::new(); | |
223e47cc | 67 | $( |
85aaf69f SL |
68 | temp_vec.push($x); |
69 | )* | |
70 | temp_vec | |
223e47cc | 71 | } |
85aaf69f | 72 | }; |
223e47cc | 73 | } |
85aaf69f | 74 | # fn main() { |
c34b1796 | 75 | # assert_eq!(vec![1,2,3], [1, 2, 3]); |
223e47cc | 76 | # } |
85aaf69f | 77 | ``` |
1a4d82fc | 78 | |
bd371182 | 79 | Whoa, that’s a lot of new syntax! Let’s break it down. |
223e47cc | 80 | |
85aaf69f SL |
81 | ```ignore |
82 | macro_rules! vec { ... } | |
83 | ``` | |
223e47cc | 84 | |
bd371182 AL |
85 | This says we’re defining a macro named `vec`, much as `fn vec` would define a |
86 | function named `vec`. In prose, we informally write a macro’s name with an | |
85aaf69f SL |
87 | exclamation point, e.g. `vec!`. The exclamation point is part of the invocation |
88 | syntax and serves to distinguish a macro from an ordinary function. | |
223e47cc | 89 | |
85aaf69f | 90 | ## Matching |
223e47cc | 91 | |
bd371182 | 92 | The macro is defined through a series of rules, which are pattern-matching |
85aaf69f | 93 | cases. Above, we had |
223e47cc | 94 | |
85aaf69f SL |
95 | ```ignore |
96 | ( $( $x:expr ),* ) => { ... }; | |
97 | ``` | |
1a4d82fc | 98 | |
85aaf69f SL |
99 | This is like a `match` expression arm, but the matching happens on Rust syntax |
100 | trees, at compile time. The semicolon is optional on the last (here, only) | |
bd371182 | 101 | case. The "pattern" on the left-hand side of `=>` is known as a ‘matcher’. |
85aaf69f | 102 | These have [their own little grammar] within the language. |
1a4d82fc | 103 | |
85aaf69f | 104 | [their own little grammar]: ../reference.html#macros |
1a4d82fc | 105 | |
85aaf69f | 106 | The matcher `$x:expr` will match any Rust expression, binding that syntax tree |
bd371182 AL |
107 | to the ‘metavariable’ `$x`. The identifier `expr` is a ‘fragment specifier’; |
108 | the full possibilities are enumerated later in this chapter. | |
85aaf69f SL |
109 | Surrounding the matcher with `$(...),*` will match zero or more expressions, |
110 | separated by commas. | |
111 | ||
112 | Aside from the special matcher syntax, any Rust tokens that appear in a matcher | |
113 | must match exactly. For example, | |
114 | ||
115 | ```rust | |
116 | macro_rules! foo { | |
117 | (x => $e:expr) => (println!("mode X: {}", $e)); | |
118 | (y => $e:expr) => (println!("mode Y: {}", $e)); | |
1a4d82fc JJ |
119 | } |
120 | ||
121 | fn main() { | |
85aaf69f | 122 | foo!(y => 3); |
1a4d82fc | 123 | } |
85aaf69f | 124 | ``` |
1a4d82fc | 125 | |
85aaf69f | 126 | will print |
1a4d82fc | 127 | |
85aaf69f SL |
128 | ```text |
129 | mode Y: 3 | |
130 | ``` | |
131 | ||
132 | With | |
1a4d82fc | 133 | |
85aaf69f SL |
134 | ```rust,ignore |
135 | foo!(z => 3); | |
136 | ``` | |
1a4d82fc | 137 | |
85aaf69f | 138 | we get the compiler error |
1a4d82fc | 139 | |
85aaf69f SL |
140 | ```text |
141 | error: no rules expected the token `z` | |
142 | ``` | |
1a4d82fc | 143 | |
85aaf69f | 144 | ## Expansion |
1a4d82fc | 145 | |
85aaf69f SL |
146 | The right-hand side of a macro rule is ordinary Rust syntax, for the most part. |
147 | But we can splice in bits of syntax captured by the matcher. From the original | |
148 | example: | |
149 | ||
150 | ```ignore | |
151 | $( | |
152 | temp_vec.push($x); | |
153 | )* | |
1a4d82fc JJ |
154 | ``` |
155 | ||
85aaf69f SL |
156 | Each matched expression `$x` will produce a single `push` statement in the |
157 | macro expansion. The repetition in the expansion proceeds in "lockstep" with | |
158 | repetition in the matcher (more on this in a moment). | |
1a4d82fc | 159 | |
bd371182 AL |
160 | Because `$x` was already declared as matching an expression, we don’t repeat |
161 | `:expr` on the right-hand side. Also, we don’t include a separating comma as | |
85aaf69f SL |
162 | part of the repetition operator. Instead, we have a terminating semicolon |
163 | within the repeated block. | |
1a4d82fc | 164 | |
85aaf69f SL |
165 | Another detail: the `vec!` macro has *two* pairs of braces on the right-hand |
166 | side. They are often combined like so: | |
1a4d82fc | 167 | |
85aaf69f SL |
168 | ```ignore |
169 | macro_rules! foo { | |
170 | () => {{ | |
171 | ... | |
172 | }} | |
173 | } | |
174 | ``` | |
175 | ||
176 | The outer braces are part of the syntax of `macro_rules!`. In fact, you can use | |
177 | `()` or `[]` instead. They simply delimit the right-hand side as a whole. | |
178 | ||
179 | The inner braces are part of the expanded syntax. Remember, the `vec!` macro is | |
180 | used in an expression context. To write an expression with multiple statements, | |
181 | including `let`-bindings, we use a block. If your macro expands to a single | |
bd371182 | 182 | expression, you don’t need this extra layer of braces. |
85aaf69f SL |
183 | |
184 | Note that we never *declared* that the macro produces an expression. In fact, | |
185 | this is not determined until we use the macro as an expression. With care, you | |
186 | can write a macro whose expansion works in several contexts. For example, | |
187 | shorthand for a data type could be valid as either an expression or a pattern. | |
1a4d82fc | 188 | |
85aaf69f | 189 | ## Repetition |
1a4d82fc | 190 | |
c34b1796 | 191 | The repetition operator follows two principal rules: |
1a4d82fc | 192 | |
c34b1796 AL |
193 | 1. `$(...)*` walks through one "layer" of repetitions, for all of the `$name`s |
194 | it contains, in lockstep, and | |
85aaf69f | 195 | 2. each `$name` must be under at least as many `$(...)*`s as it was matched |
bd371182 | 196 | against. If it is under more, it’ll be duplicated, as appropriate. |
1a4d82fc | 197 | |
85aaf69f SL |
198 | This baroque macro illustrates the duplication of variables from outer |
199 | repetition levels. | |
200 | ||
201 | ```rust | |
202 | macro_rules! o_O { | |
203 | ( | |
204 | $( | |
205 | $x:expr; [ $( $y:expr ),* ] | |
206 | );* | |
207 | ) => { | |
208 | &[ $($( $x + $y ),*),* ] | |
209 | } | |
1a4d82fc JJ |
210 | } |
211 | ||
85aaf69f SL |
212 | fn main() { |
213 | let a: &[i32] | |
214 | = o_O!(10; [1, 2, 3]; | |
215 | 20; [4, 5, 6]); | |
1a4d82fc | 216 | |
85aaf69f SL |
217 | assert_eq!(a, [11, 12, 13, 24, 25, 26]); |
218 | } | |
219 | ``` | |
1a4d82fc | 220 | |
bd371182 | 221 | That’s most of the matcher syntax. These examples use `$(...)*`, which is a |
85aaf69f SL |
222 | "zero or more" match. Alternatively you can write `$(...)+` for a "one or |
223 | more" match. Both forms optionally include a separator, which can be any token | |
224 | except `+` or `*`. | |
1a4d82fc | 225 | |
c34b1796 | 226 | This system is based on |
62682a34 | 227 | "[Macro-by-Example](https://www.cs.indiana.edu/ftp/techreports/TR206.pdf)" |
c34b1796 AL |
228 | (PDF link). |
229 | ||
85aaf69f | 230 | # Hygiene |
1a4d82fc | 231 | |
85aaf69f SL |
232 | Some languages implement macros using simple text substitution, which leads to |
233 | various problems. For example, this C program prints `13` instead of the | |
234 | expected `25`. | |
1a4d82fc | 235 | |
85aaf69f SL |
236 | ```text |
237 | #define FIVE_TIMES(x) 5 * x | |
238 | ||
239 | int main() { | |
240 | printf("%d\n", FIVE_TIMES(2 + 3)); | |
241 | return 0; | |
1a4d82fc | 242 | } |
85aaf69f | 243 | ``` |
1a4d82fc | 244 | |
85aaf69f | 245 | After expansion we have `5 * 2 + 3`, and multiplication has greater precedence |
bd371182 | 246 | than addition. If you’ve used C macros a lot, you probably know the standard |
85aaf69f | 247 | idioms for avoiding this problem, as well as five or six others. In Rust, we |
bd371182 | 248 | don’t have to worry about it. |
85aaf69f SL |
249 | |
250 | ```rust | |
251 | macro_rules! five_times { | |
252 | ($x:expr) => (5 * $x); | |
253 | } | |
254 | ||
255 | fn main() { | |
256 | assert_eq!(25, five_times!(2 + 3)); | |
257 | } | |
1a4d82fc JJ |
258 | ``` |
259 | ||
85aaf69f SL |
260 | The metavariable `$x` is parsed as a single expression node, and keeps its |
261 | place in the syntax tree even after substitution. | |
262 | ||
bd371182 AL |
263 | Another common problem in macro systems is ‘variable capture’. Here’s a C |
264 | macro, using [a GNU C extension] to emulate Rust’s expression blocks. | |
85aaf69f SL |
265 | |
266 | [a GNU C extension]: https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html | |
1a4d82fc | 267 | |
85aaf69f SL |
268 | ```text |
269 | #define LOG(msg) ({ \ | |
270 | int state = get_log_state(); \ | |
271 | if (state > 0) { \ | |
272 | printf("log(%d): %s\n", state, msg); \ | |
273 | } \ | |
274 | }) | |
275 | ``` | |
276 | ||
bd371182 | 277 | Here’s a simple use case that goes terribly wrong: |
1a4d82fc | 278 | |
85aaf69f SL |
279 | ```text |
280 | const char *state = "reticulating splines"; | |
c34b1796 | 281 | LOG(state) |
85aaf69f | 282 | ``` |
1a4d82fc | 283 | |
c34b1796 | 284 | This expands to |
85aaf69f SL |
285 | |
286 | ```text | |
c34b1796 AL |
287 | const char *state = "reticulating splines"; |
288 | int state = get_log_state(); | |
289 | if (state > 0) { | |
290 | printf("log(%d): %s\n", state, state); | |
291 | } | |
85aaf69f SL |
292 | ``` |
293 | ||
c34b1796 AL |
294 | The second variable named `state` shadows the first one. This is a problem |
295 | because the print statement should refer to both of them. | |
296 | ||
85aaf69f | 297 | The equivalent Rust macro has the desired behavior. |
1a4d82fc JJ |
298 | |
299 | ```rust | |
85aaf69f SL |
300 | # fn get_log_state() -> i32 { 3 } |
301 | macro_rules! log { | |
302 | ($msg:expr) => {{ | |
303 | let state: i32 = get_log_state(); | |
304 | if state > 0 { | |
305 | println!("log({}): {}", state, $msg); | |
306 | } | |
307 | }}; | |
1a4d82fc JJ |
308 | } |
309 | ||
85aaf69f SL |
310 | fn main() { |
311 | let state: &str = "reticulating splines"; | |
312 | log!(state); | |
1a4d82fc | 313 | } |
85aaf69f SL |
314 | ``` |
315 | ||
e9174d1e | 316 | This works because Rust has a [hygienic macro system]. Each macro expansion |
bd371182 AL |
317 | happens in a distinct ‘syntax context’, and each variable is tagged with the |
318 | syntax context where it was introduced. It’s as though the variable `state` | |
85aaf69f | 319 | inside `main` is painted a different "color" from the variable `state` inside |
bd371182 | 320 | the macro, and therefore they don’t conflict. |
1a4d82fc | 321 | |
62682a34 | 322 | [hygienic macro system]: https://en.wikipedia.org/wiki/Hygienic_macro |
85aaf69f SL |
323 | |
324 | This also restricts the ability of macros to introduce new bindings at the | |
325 | invocation site. Code such as the following will not work: | |
326 | ||
327 | ```rust,ignore | |
328 | macro_rules! foo { | |
329 | () => (let x = 3); | |
330 | } | |
331 | ||
332 | fn main() { | |
333 | foo!(); | |
334 | println!("{}", x); | |
1a4d82fc | 335 | } |
1a4d82fc JJ |
336 | ``` |
337 | ||
bd371182 | 338 | Instead you need to pass the variable name into the invocation, so it’s tagged |
85aaf69f | 339 | with the right syntax context. |
1a4d82fc | 340 | |
85aaf69f SL |
341 | ```rust |
342 | macro_rules! foo { | |
343 | ($v:ident) => (let $v = 3); | |
344 | } | |
345 | ||
346 | fn main() { | |
347 | foo!(x); | |
348 | println!("{}", x); | |
349 | } | |
350 | ``` | |
351 | ||
62682a34 | 352 | This holds for `let` bindings and loop labels, but not for [items][items]. |
85aaf69f | 353 | So the following code does compile: |
1a4d82fc JJ |
354 | |
355 | ```rust | |
85aaf69f SL |
356 | macro_rules! foo { |
357 | () => (fn x() { }); | |
358 | } | |
359 | ||
360 | fn main() { | |
361 | foo!(); | |
362 | x(); | |
1a4d82fc | 363 | } |
1a4d82fc JJ |
364 | ``` |
365 | ||
85aaf69f SL |
366 | [items]: ../reference.html#items |
367 | ||
c34b1796 AL |
368 | # Recursive macros |
369 | ||
bd371182 | 370 | A macro’s expansion can include more macro invocations, including invocations |
c34b1796 AL |
371 | of the very same macro being expanded. These recursive macros are useful for |
372 | processing tree-structured input, as illustrated by this (simplistic) HTML | |
373 | shorthand: | |
374 | ||
375 | ```rust | |
376 | # #![allow(unused_must_use)] | |
377 | macro_rules! write_html { | |
378 | ($w:expr, ) => (()); | |
379 | ||
380 | ($w:expr, $e:tt) => (write!($w, "{}", $e)); | |
381 | ||
382 | ($w:expr, $tag:ident [ $($inner:tt)* ] $($rest:tt)*) => {{ | |
383 | write!($w, "<{}>", stringify!($tag)); | |
384 | write_html!($w, $($inner)*); | |
385 | write!($w, "</{}>", stringify!($tag)); | |
386 | write_html!($w, $($rest)*); | |
387 | }}; | |
388 | } | |
389 | ||
390 | fn main() { | |
391 | # // FIXME(#21826) | |
392 | use std::fmt::Write; | |
393 | let mut out = String::new(); | |
394 | ||
395 | write_html!(&mut out, | |
396 | html[ | |
397 | head[title["Macros guide"]] | |
398 | body[h1["Macros are the best!"]] | |
399 | ]); | |
400 | ||
401 | assert_eq!(out, | |
402 | "<html><head><title>Macros guide</title></head>\ | |
403 | <body><h1>Macros are the best!</h1></body></html>"); | |
404 | } | |
405 | ``` | |
406 | ||
407 | # Debugging macro code | |
408 | ||
409 | To see the results of expanding macros, run `rustc --pretty expanded`. The | |
410 | output represents a whole crate, so you can also feed it back in to `rustc`, | |
411 | which will sometimes produce better error messages than the original | |
412 | compilation. Note that the `--pretty expanded` output may have a different | |
413 | meaning if multiple variables of the same name (but different syntax contexts) | |
414 | are in play in the same scope. In this case `--pretty expanded,hygiene` will | |
415 | tell you about the syntax contexts. | |
416 | ||
417 | `rustc` provides two syntax extensions that help with macro debugging. For now, | |
418 | they are unstable and require feature gates. | |
419 | ||
420 | * `log_syntax!(...)` will print its arguments to standard output, at compile | |
421 | time, and "expand" to nothing. | |
422 | ||
423 | * `trace_macros!(true)` will enable a compiler message every time a macro is | |
424 | expanded. Use `trace_macros!(false)` later in expansion to turn it off. | |
425 | ||
9346a6ac | 426 | # Syntactic requirements |
85aaf69f | 427 | |
9346a6ac AL |
428 | Even when Rust code contains un-expanded macros, it can be parsed as a full |
429 | [syntax tree][ast]. This property can be very useful for editors and other | |
430 | tools that process code. It also has a few consequences for the design of | |
bd371182 | 431 | Rust’s macro system. |
85aaf69f | 432 | |
9346a6ac AL |
433 | [ast]: glossary.html#abstract-syntax-tree |
434 | ||
435 | One consequence is that Rust must determine, when it parses a macro invocation, | |
436 | whether the macro stands in for | |
437 | ||
438 | * zero or more items, | |
439 | * zero or more methods, | |
440 | * an expression, | |
441 | * a statement, or | |
442 | * a pattern. | |
443 | ||
444 | A macro invocation within a block could stand for some items, or for an | |
445 | expression / statement. Rust uses a simple rule to resolve this ambiguity. A | |
446 | macro invocation that stands for items must be either | |
447 | ||
448 | * delimited by curly braces, e.g. `foo! { ... }`, or | |
449 | * terminated by a semicolon, e.g. `foo!(...);` | |
450 | ||
451 | Another consequence of pre-expansion parsing is that the macro invocation must | |
452 | consist of valid Rust tokens. Furthermore, parentheses, brackets, and braces | |
453 | must be balanced within a macro invocation. For example, `foo!([)` is | |
454 | forbidden. This allows Rust to know where the macro invocation ends. | |
455 | ||
bd371182 | 456 | More formally, the macro invocation body must be a sequence of ‘token trees’. |
9346a6ac AL |
457 | A token tree is defined recursively as either |
458 | ||
459 | * a sequence of token trees surrounded by matching `()`, `[]`, or `{}`, or | |
460 | * any other single token. | |
461 | ||
bd371182 | 462 | Within a matcher, each metavariable has a ‘fragment specifier’, identifying |
9346a6ac AL |
463 | which syntactic form it matches. |
464 | ||
465 | * `ident`: an identifier. Examples: `x`; `foo`. | |
466 | * `path`: a qualified name. Example: `T::SpecialA`. | |
467 | * `expr`: an expression. Examples: `2 + 2`; `if true then { 1 } else { 2 }`; `f(42)`. | |
468 | * `ty`: a type. Examples: `i32`; `Vec<(char, String)>`; `&T`. | |
469 | * `pat`: a pattern. Examples: `Some(t)`; `(17, 'a')`; `_`. | |
470 | * `stmt`: a single statement. Example: `let x = 3`. | |
471 | * `block`: a brace-delimited sequence of statements. Example: | |
472 | `{ log(error, "hi"); return 12; }`. | |
62682a34 | 473 | * `item`: an [item][item]. Examples: `fn foo() { }`; `struct Bar;`. |
9346a6ac AL |
474 | * `meta`: a "meta item", as found in attributes. Example: `cfg(target_os = "windows")`. |
475 | * `tt`: a single token tree. | |
476 | ||
477 | There are additional rules regarding the next token after a metavariable: | |
478 | ||
62682a34 SL |
479 | * `expr` variables may only be followed by one of: `=> , ;` |
480 | * `ty` and `path` variables may only be followed by one of: `=> , : = > as` | |
481 | * `pat` variables may only be followed by one of: `=> , = if in` | |
9346a6ac AL |
482 | * Other variables may be followed by any token. |
483 | ||
bd371182 | 484 | These rules provide some flexibility for Rust’s syntax to evolve without |
9346a6ac AL |
485 | breaking existing macros. |
486 | ||
487 | The macro system does not deal with parse ambiguity at all. For example, the | |
488 | grammar `$($t:ty)* $e:expr` will always fail to parse, because the parser would | |
489 | be forced to choose between parsing `$t` and parsing `$e`. Changing the | |
490 | invocation syntax to put a distinctive token in front can solve the problem. In | |
491 | this case, you can write `$(T $t:ty)* E $e:exp`. | |
492 | ||
493 | [item]: ../reference.html#items | |
494 | ||
495 | # Scoping and macro import/export | |
496 | ||
497 | Macros are expanded at an early stage in compilation, before name resolution. | |
498 | One downside is that scoping works differently for macros, compared to other | |
499 | constructs in the language. | |
500 | ||
501 | Definition and expansion of macros both happen in a single depth-first, | |
bd371182 | 502 | lexical-order traversal of a crate’s source. So a macro defined at module scope |
9346a6ac AL |
503 | is visible to any subsequent code in the same module, which includes the body |
504 | of any subsequent child `mod` items. | |
505 | ||
506 | A macro defined within the body of a single `fn`, or anywhere else not at | |
507 | module scope, is visible only within that item. | |
508 | ||
509 | If a module has the `macro_use` attribute, its macros are also visible in its | |
bd371182 AL |
510 | parent module after the child’s `mod` item. If the parent also has `macro_use` |
511 | then the macros will be visible in the grandparent after the parent’s `mod` | |
9346a6ac AL |
512 | item, and so forth. |
513 | ||
514 | The `macro_use` attribute can also appear on `extern crate`. In this context | |
515 | it controls which macros are loaded from the external crate, e.g. | |
516 | ||
517 | ```rust,ignore | |
518 | #[macro_use(foo, bar)] | |
519 | extern crate baz; | |
520 | ``` | |
521 | ||
522 | If the attribute is given simply as `#[macro_use]`, all macros are loaded. If | |
523 | there is no `#[macro_use]` attribute then no macros are loaded. Only macros | |
524 | defined with the `#[macro_export]` attribute may be loaded. | |
525 | ||
bd371182 | 526 | To load a crate’s macros without linking it into the output, use `#[no_link]` |
9346a6ac AL |
527 | as well. |
528 | ||
529 | An example: | |
530 | ||
531 | ```rust | |
532 | macro_rules! m1 { () => (()) } | |
533 | ||
534 | // visible here: m1 | |
535 | ||
536 | mod foo { | |
537 | // visible here: m1 | |
538 | ||
539 | #[macro_export] | |
540 | macro_rules! m2 { () => (()) } | |
541 | ||
542 | // visible here: m1, m2 | |
543 | } | |
544 | ||
545 | // visible here: m1 | |
546 | ||
547 | macro_rules! m3 { () => (()) } | |
548 | ||
549 | // visible here: m1, m3 | |
550 | ||
551 | #[macro_use] | |
552 | mod bar { | |
553 | // visible here: m1, m3 | |
554 | ||
555 | macro_rules! m4 { () => (()) } | |
556 | ||
557 | // visible here: m1, m3, m4 | |
558 | } | |
559 | ||
560 | // visible here: m1, m3, m4 | |
561 | # fn main() { } | |
562 | ``` | |
563 | ||
564 | When this library is loaded with `#[macro_use] extern crate`, only `m2` will | |
565 | be imported. | |
566 | ||
567 | The Rust Reference has a [listing of macro-related | |
bd371182 | 568 | attributes](../reference.html#macro-related-attributes). |
9346a6ac AL |
569 | |
570 | # The variable `$crate` | |
571 | ||
572 | A further difficulty occurs when a macro is used in multiple crates. Say that | |
573 | `mylib` defines | |
574 | ||
575 | ```rust | |
576 | pub fn increment(x: u32) -> u32 { | |
577 | x + 1 | |
578 | } | |
579 | ||
580 | #[macro_export] | |
581 | macro_rules! inc_a { | |
582 | ($x:expr) => ( ::increment($x) ) | |
583 | } | |
584 | ||
585 | #[macro_export] | |
586 | macro_rules! inc_b { | |
587 | ($x:expr) => ( ::mylib::increment($x) ) | |
588 | } | |
589 | # fn main() { } | |
590 | ``` | |
591 | ||
592 | `inc_a` only works within `mylib`, while `inc_b` only works outside the | |
593 | library. Furthermore, `inc_b` will break if the user imports `mylib` under | |
594 | another name. | |
595 | ||
596 | Rust does not (yet) have a hygiene system for crate references, but it does | |
597 | provide a simple workaround for this problem. Within a macro imported from a | |
598 | crate named `foo`, the special macro variable `$crate` will expand to `::foo`. | |
599 | By contrast, when a macro is defined and then used in the same crate, `$crate` | |
600 | will expand to nothing. This means we can write | |
601 | ||
602 | ```rust | |
603 | #[macro_export] | |
604 | macro_rules! inc { | |
605 | ($x:expr) => ( $crate::increment($x) ) | |
606 | } | |
607 | # fn main() { } | |
608 | ``` | |
609 | ||
610 | to define a single macro that works both inside and outside our library. The | |
611 | function name will expand to either `::increment` or `::mylib::increment`. | |
612 | ||
613 | To keep this system simple and correct, `#[macro_use] extern crate ...` may | |
614 | only appear at the root of your crate, not inside `mod`. This ensures that | |
615 | `$crate` is a single identifier. | |
616 | ||
617 | # The deep end | |
618 | ||
619 | The introductory chapter mentioned recursive macros, but it did not give the | |
620 | full story. Recursive macros are useful for another reason: Each recursive | |
bd371182 | 621 | invocation gives you another opportunity to pattern-match the macro’s |
9346a6ac AL |
622 | arguments. |
623 | ||
624 | As an extreme example, it is possible, though hardly advisable, to implement | |
62682a34 | 625 | the [Bitwise Cyclic Tag](https://esolangs.org/wiki/Bitwise_Cyclic_Tag) automaton |
bd371182 | 626 | within Rust’s macro system. |
9346a6ac AL |
627 | |
628 | ```rust | |
629 | macro_rules! bct { | |
630 | // cmd 0: d ... => ... | |
631 | (0, $($ps:tt),* ; $_d:tt) | |
632 | => (bct!($($ps),*, 0 ; )); | |
633 | (0, $($ps:tt),* ; $_d:tt, $($ds:tt),*) | |
634 | => (bct!($($ps),*, 0 ; $($ds),*)); | |
635 | ||
636 | // cmd 1p: 1 ... => 1 ... p | |
637 | (1, $p:tt, $($ps:tt),* ; 1) | |
638 | => (bct!($($ps),*, 1, $p ; 1, $p)); | |
639 | (1, $p:tt, $($ps:tt),* ; 1, $($ds:tt),*) | |
640 | => (bct!($($ps),*, 1, $p ; 1, $($ds),*, $p)); | |
641 | ||
642 | // cmd 1p: 0 ... => 0 ... | |
643 | (1, $p:tt, $($ps:tt),* ; $($ds:tt),*) | |
644 | => (bct!($($ps),*, 1, $p ; $($ds),*)); | |
645 | ||
646 | // halt on empty data string | |
647 | ( $($ps:tt),* ; ) | |
648 | => (()); | |
649 | } | |
650 | ``` | |
651 | ||
652 | Exercise: use macros to reduce duplication in the above definition of the | |
653 | `bct!` macro. | |
654 | ||
bd371182 AL |
655 | # Common macros |
656 | ||
657 | Here are some common macros you’ll see in Rust code. | |
658 | ||
659 | ## panic! | |
660 | ||
661 | This macro causes the current thread to panic. You can give it a message | |
662 | to panic with: | |
663 | ||
664 | ```rust,no_run | |
665 | panic!("oh no!"); | |
666 | ``` | |
667 | ||
668 | ## vec! | |
669 | ||
670 | The `vec!` macro is used throughout the book, so you’ve probably seen it | |
671 | already. It creates `Vec<T>`s with ease: | |
672 | ||
673 | ```rust | |
674 | let v = vec![1, 2, 3, 4, 5]; | |
675 | ``` | |
676 | ||
677 | It also lets you make vectors with repeating values. For example, a hundred | |
678 | zeroes: | |
679 | ||
680 | ```rust | |
681 | let v = vec![0; 100]; | |
682 | ``` | |
683 | ||
684 | ## assert! and assert_eq! | |
685 | ||
62682a34 SL |
686 | These two macros are used in tests. `assert!` takes a boolean. `assert_eq!` |
687 | takes two values and checks them for equality. `true` passes, `false` `panic!`s. | |
688 | Like this: | |
bd371182 AL |
689 | |
690 | ```rust,no_run | |
691 | // A-ok! | |
692 | ||
693 | assert!(true); | |
694 | assert_eq!(5, 3 + 2); | |
695 | ||
696 | // nope :( | |
697 | ||
698 | assert!(5 < 3); | |
699 | assert_eq!(5, 3); | |
700 | ``` | |
62682a34 | 701 | |
bd371182 AL |
702 | ## try! |
703 | ||
704 | `try!` is used for error handling. It takes something that can return a | |
705 | `Result<T, E>`, and gives `T` if it’s a `Ok<T>`, and `return`s with the | |
706 | `Err(E)` if it’s that. Like this: | |
707 | ||
708 | ```rust,no_run | |
709 | use std::fs::File; | |
710 | ||
711 | fn foo() -> std::io::Result<()> { | |
712 | let f = try!(File::create("foo.txt")); | |
713 | ||
714 | Ok(()) | |
715 | } | |
716 | ``` | |
717 | ||
718 | This is cleaner than doing this: | |
719 | ||
720 | ```rust,no_run | |
721 | use std::fs::File; | |
722 | ||
723 | fn foo() -> std::io::Result<()> { | |
724 | let f = File::create("foo.txt"); | |
725 | ||
726 | let f = match f { | |
727 | Ok(t) => t, | |
728 | Err(e) => return Err(e), | |
729 | }; | |
730 | ||
731 | Ok(()) | |
732 | } | |
733 | ``` | |
734 | ||
735 | ## unreachable! | |
736 | ||
737 | This macro is used when you think some code should never execute: | |
738 | ||
739 | ```rust | |
740 | if false { | |
741 | unreachable!(); | |
742 | } | |
743 | ``` | |
744 | ||
745 | Sometimes, the compiler may make you have a different branch that you know | |
746 | will never, ever run. In these cases, use this macro, so that if you end | |
747 | up wrong, you’ll get a `panic!` about it. | |
748 | ||
749 | ```rust | |
750 | let x: Option<i32> = None; | |
751 | ||
752 | match x { | |
753 | Some(_) => unreachable!(), | |
754 | None => println!("I know x is None!"), | |
755 | } | |
756 | ``` | |
757 | ||
758 | ## unimplemented! | |
759 | ||
760 | The `unimplemented!` macro can be used when you’re trying to get your functions | |
761 | to typecheck, and don’t want to worry about writing out the body of the | |
762 | function. One example of this situation is implementing a trait with multiple | |
763 | required methods, where you want to tackle one at a time. Define the others | |
764 | as `unimplemented!` until you’re ready to write them. | |
765 | ||
9346a6ac AL |
766 | # Procedural macros |
767 | ||
bd371182 AL |
768 | If Rust’s macro system can’t do what you need, you may want to write a |
769 | [compiler plugin](compiler-plugins.html) instead. Compared to `macro_rules!` | |
9346a6ac AL |
770 | macros, this is significantly more work, the interfaces are much less stable, |
771 | and bugs can be much harder to track down. In exchange you get the | |
772 | flexibility of running arbitrary Rust code within the compiler. Syntax | |
bd371182 | 773 | extension plugins are sometimes called ‘procedural macros’ for this reason. |