]>
Commit | Line | Data |
---|---|---|
85aaf69f SL |
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 | |
c34b1796 AL |
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 | |
85aaf69f SL |
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 | ||
c34b1796 AL |
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. | |
85aaf69f | 234 | |
c34b1796 | 235 | # Procedural macros |
85aaf69f SL |
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, | |
c34b1796 | 240 | and bugs can be much harder to track down. In exchange you get the |
85aaf69f SL |
241 | flexibility of running arbitrary Rust code within the compiler. Syntax |
242 | extension plugins are sometimes called *procedural macros* for this reason. |