| Position | 39 |Input | 40 |inits |
41 | recur |
42 |
|---|---|---|---|
a[n] = $($inits:expr),+ , ... , $recur:expr
47 | ⌂ |
48 | a[n] = 0, 1, ..., a[n-1] + a[n-2] |
49 | 50 | | 51 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
54 | ⌂ |
55 | [n] = 0, 1, ..., a[n-1] + a[n-2] |
56 | 57 | | 58 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
61 | ⌂ |
62 | n] = 0, 1, ..., a[n-1] + a[n-2] |
63 | 64 | | 65 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
68 | ⌂ |
69 | ] = 0, 1, ..., a[n-1] + a[n-2] |
70 | 71 | | 72 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
75 | ⌂ |
76 | = 0, 1, ..., a[n-1] + a[n-2] |
77 | 78 | | 79 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
82 | ⌂ |
83 | 0, 1, ..., a[n-1] + a[n-2] |
84 | 85 | | 86 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
89 | ⌂ |
90 | 0, 1, ..., a[n-1] + a[n-2] |
91 | 92 | | 93 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
96 | ⌂ ⌂ |
97 | , 1, ..., a[n-1] + a[n-2] |
98 | 0 |
99 | 100 | |
| 103 | 注意： 这有两个 `⌂` ，因为下个输入标记既能匹配 重复元素间的分隔符逗号，也能匹配 标志重复结束的逗号。宏系统将同时追踪这两种可能，直到决定具体选择为止。 104 | | 105 ||||
a[n] = $($inits:expr),+ , ... , $recur:expr
108 | ⌂ ⌂ |
109 | 1, ..., a[n-1] + a[n-2] |
110 | 0 |
111 | 112 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
115 | |
116 | , ..., a[n-1] + a[n-2] |
117 | 0, 1 |
118 | 119 | |
| 122 | 注意：第一个被划掉的记号表明， 123 | 基于上个被消耗的标记，宏系统排除了一项先前存在的可能。 124 | | 125 ||||
a[n] = $($inits:expr),+ , ... , $recur:expr
128 | ⌂ |
129 | ..., a[n-1] + a[n-2] |
130 | 0, 1 |
131 | 132 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
135 | ⌂ |
136 | , a[n-1] + a[n-2] |
137 | 0, 1 |
138 | 139 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
142 | ⌂ |
143 | a[n-1] + a[n-2] |
144 | 0, 1 |
145 | 146 | |
a[n] = $($inits:expr),+ , ... , $recur:expr
149 | ⌂ |
150 | 151 | | 0, 1 |
152 | a[n-1] + a[n-2] |
153 |
| 156 | 注意：这一步表明，类似 $recur:expr 157 | 的绑定将消耗一个完整的表达式。 158 | 究竟什么算是一个完整的表达式，将由编译器决定。 159 | 稍后我们会谈到语言其它部分的类似行为。 160 | | 161 ||||
macro_rules! using_a {
($e:expr) => {
{
let a = 42;
$e
}
}
}
let four = using_a!(a / 10);
28 |
29 | 我们将采用背景色来表示句法上下文。现在，将上述宏调用展开如下：
30 |
31 | let four = { let a = 42; a / 10 };32 | 33 | 首先，回想一下，在展开的期间调用声明宏，实际是空（因为那是一棵待补全的语法树）。 34 | 35 | 其次，如果我们现在就尝试编译上述代码，编译器将报如下错误： 36 | 37 | ```rust,ignore 38 | error[E0425]: cannot find value `a` in this scope 39 | --> src/main.rs:13:21 40 | | 41 | 13 | let four = using_a!(a / 10); 42 | | ^ not found in this scope 43 | ``` 44 | 45 | 注意到宏在展开后背景色（即其句法上下文）发生了改变。 46 | 每处宏展开均赋予其内容一个新的、独一无二的上下文。 47 | 故而，在展开后的代码中实际上存在 *两个* 不同的 `a`，它们分别有不同的句法上下文。 48 | 即，第一个 `a` 与第二个 `a` 并不相同，即使它们便看起来很像。 49 | 50 | 也就是说，被替换进宏展开中的标记仍然 **保持** 着它们原有的句法上下文。 51 | 52 | 因为它们是被传给这宏的，并非这宏本身的一部分。因此，我们作出如下修改： 53 | 54 |
macro_rules! using_a {
($a:ident, $e:expr) => {
{
let $a = 42;
$e
}
}
}
let four = using_a!(a, a / 10);
55 |
56 | 展开如下：
57 |
58 | let four = { let a = 42; a / 10 };59 | 60 | 因为只用了一个 `a`（显然 `a` 在此处是局部变量），编译器将欣然接受此段代码。 61 | 62 | ## `$crate` 元变量 63 | 64 | 当声明宏需要其定义所在的 (defining) crate 65 | 的其他 items 时，由于“卫生性”，我们需要使用 `$crate` 元变量。 66 | 67 | 这个特殊的元变量所做的事情是，它展开成宏所定义的 crate 的绝对路径。 68 | 69 | ```rust,ignore 70 | //// 在 `helper_macro` crate 里定义 `helped!` 和 `helper!` 宏 71 | #[macro_export] 72 | macro_rules! helped { 73 | // () => { helper!() } // 这行可能导致 `helper` 不在作用域的错误 74 | () => { $crate::helper!() } 75 | } 76 | 77 | #[macro_export] 78 | macro_rules! helper { 79 | () => { () } 80 | } 81 | 82 | //// 在另外的 crate 中使用这两个宏 83 | // 注意：`helper_macro::helper` 并没有导入进来 84 | use helper_macro::helped; 85 | 86 | fn unit() { 87 | // 这个宏能运行通过，因为 `$crate` 正确地展开成 `helper_macro` crate 的路径（而不是使用者的路径） 88 | helped!(); 89 | } 90 | ``` 91 | 92 | 请注意，`$crate` 用在指明非宏的 items 时，它必须和完整且有效的模块路径一起使用。如下： 93 | 94 | ```rust 95 | pub mod inner { 96 | #[macro_export] 97 | macro_rules! call_foo { 98 | () => { $crate::inner::foo() }; 99 | } 100 | 101 | pub fn foo() {} 102 | } 103 | ``` 104 | -------------------------------------------------------------------------------- /src/decl-macros/minutiae/identifiers.md: -------------------------------------------------------------------------------- 1 | # 非标识符的“标识符” 2 | 3 | > 译者注：这里需要记住的重点是 4 | > 5 | > 1. `self` 可以使用 [`ident`] 或者 [`tt`] 分类符来匹配； 6 | > 7 | > 2. `_` 只能在模式中使用，不能用 [`ident`] 分类符匹配，而是用 [`pat`] 或者 8 | > [`tt`] 分类符匹配。 9 | 10 | 有两个标记，当你最终撞见时，很有可能认为它们是标识符 ([`ident`])，但实际上它们不是。 11 | 12 | 然而正是这些标记，在某些情况下又的确是标识符。 13 | 14 | ## `self` 15 | 16 | 第一个是 `self`。毫无疑问，它是一个 **关键词** ([keyword])。在一般的 Rust 17 | 代码中，不可能出现把它解读成标识符的情况；但在宏中这种情况则有可能发生： 18 | 19 | [keyword]: https://doc.rust-lang.org/reference/keywords.html 20 | 21 | ```rust,editable 22 | macro_rules! what_is { 23 | (self) => {"the keyword `self`"}; 24 | ($i:ident) => {concat!("the identifier `", stringify!($i), "`")}; 25 | } 26 | 27 | macro_rules! call_with_ident { 28 | ($c:ident($i:ident)) => {$c!($i)}; 29 | } 30 | 31 | fn main() { 32 | println!("{}", what_is!(self)); 33 | println!("{}", call_with_ident!(what_is(self))); 34 | } 35 | ``` 36 | 37 | 上述代码的输出将是： 38 | 39 | ```text 40 | the keyword `self` 41 | the keyword `self` 42 | ``` 43 | 44 | 但这说不通啊！`call_with_ident!` 要求一个标识符，而且它的确匹配到了，还成功替换了！所以， 45 | `self` 同时是一个关键词，但又不是。你可能会想，好吧，但这鬼东西哪里重要呢？看看这个： 46 | 47 | ```rust,editable 48 | macro_rules! make_mutable { 49 | ($i:ident) => {let mut $i = $i;}; 50 | } 51 | 52 | struct Dummy(i32); 53 | 54 | impl Dummy { 55 | fn double(self) -> Dummy { 56 | make_mutable!(self); 57 | self.0 *= 2; 58 | self 59 | } 60 | } 61 | 62 | fn main() { 63 | println!("{:?}", Dummy(4).double().0); 64 | } 65 | ``` 66 | 67 | 编译它会失败，并报错： 68 | 69 | ```rust,ignore 70 | error: `mut` must be followed by a named binding 71 | --> src/main.rs:2:24 72 | | 73 | 2 | ($i:ident) => {let mut $i = $i;}; 74 | | ^^^^^^ help: remove the `mut` prefix: `self` 75 | ... 76 | 9 | make_mutable!(self); 77 | | -------------------- in this macro invocation 78 | | 79 | = note: `mut` may be followed by `variable` and `variable @ pattern` 80 | ``` 81 | 82 | 所以说，宏在匹配的时候，会欣然把 `self` 当作标识符接受，进而允许你把 `self` 83 | 带到那些实际上没办法使用的情况中去。但是，也成吧，既然得同时记住 `self` 84 | 既是关键词又是标识符，那下面这个讲道理应该可行，对吧？ 85 | 86 | ```rust,editable 87 | macro_rules! make_self_mutable { 88 | ($i:ident) => {let mut $i = self;}; 89 | } 90 | 91 | struct Dummy(i32); 92 | 93 | impl Dummy { 94 | fn double(self) -> Dummy { 95 | make_self_mutable!(mut_self); 96 | mut_self.0 *= 2; 97 | mut_self 98 | } 99 | } 100 | 101 | fn main() { 102 | println!("{:?}", Dummy(4).double().0); 103 | } 104 | ``` 105 | 106 | 实际上也不行，编译错误变成： 107 | 108 | ```rust,ignore 109 | error[E0424]: expected value, found module `self` 110 | --> src/main.rs:2:33 111 | | 112 | 2 | ($i:ident) => {let mut $i = self;}; 113 | | ^^^^ `self` value is a keyword only available in methods with a `self` parameter 114 | ... 115 | 8 | / fn double(self) -> Dummy { 116 | 9 | | make_self_mutable!(mut_self); 117 | | | ----------------------------- in this macro invocation 118 | 10 | | mut_self.0 *= 2; 119 | 11 | | mut_self 120 | 12 | | } 121 | | |_____- this function has a `self` parameter, but a macro invocation can only access identifiers it receives from parameters 122 | | 123 | ``` 124 | 125 | 这同样也说不通。这简直就像是在抱怨说，它看见的两个 `self` 不是同一个 `self` 126 | ... 就搞得像关键词 `self` 就像标识符一样，也有卫生性。 127 | 128 | ```rust,editable 129 | macro_rules! double_method { 130 | ($body:expr) => { 131 | fn double(mut self) -> Dummy { 132 | $body 133 | } 134 | }; 135 | } 136 | 137 | struct Dummy(i32); 138 | 139 | impl Dummy { 140 | double_method! {{ 141 | self.0 *= 2; 142 | self 143 | }} 144 | } 145 | 146 | fn main() { 147 | println!("{:?}", Dummy(4).double().0); 148 | } 149 | ``` 150 | 151 | 还是报同样的错。那这个如何： 152 | 153 | ```rust,editable 154 | macro_rules! double_method { 155 | ($self_:ident, $body:expr) => { 156 | fn double(mut $self_) -> Dummy { 157 | $body 158 | } 159 | }; 160 | } 161 | 162 | struct Dummy(i32); 163 | 164 | impl Dummy { 165 | double_method! {self, { 166 | self.0 *= 2; 167 | self 168 | }} 169 | } 170 | 171 | fn main() { 172 | println!("{:?}", Dummy(4).double().0); 173 | } 174 | ``` 175 | 176 | 终于管用了。所以说，`self` 是关键词，但如果想它变成标识符，那么同时也能是一个标识符。 177 | 178 | 那么，相同的道理对类似的其它东西有用吗？ 179 | 180 | ## `_` 181 | 182 | ```rust,editable 183 | macro_rules! double_method { 184 | ($self_:ident, $body:expr) => { 185 | fn double($self_) -> Dummy { 186 | $body 187 | } 188 | }; 189 | } 190 | 191 | struct Dummy(i32); 192 | 193 | impl Dummy { 194 | double_method! {_, 0} 195 | } 196 | 197 | fn main() { 198 | println!("{:?}", Dummy(4).double().0); 199 | } 200 | ``` 201 | 202 | ```rust,ignore 203 | error: no rules expected the token `_` 204 | --> src/main.rs:12:21 205 | | 206 | 1 | macro_rules! double_method { 207 | | -------------------------- when calling this macro 208 | ... 209 | 12 | double_method! {_, 0} 210 | | ^ no rules expected this token in macro call 211 | ``` 212 | 213 | 哈，当然不行。即便它 **如同** `self` 一样从定义上讲是标识符，但 [`_`][_] 214 | 在模式以及表达式中是一个合法的 (valid) 关键词，而不是一个标识符。 215 | 216 | [_]: https://doc.rust-lang.org/reference/patterns.html#wildcard-pattern 217 | 218 | --- 219 | 220 | 你可能觉得，既然 `_` 在模式中有效，那换成 `$self_:pat` 是不是就能一石二鸟了呢？ 221 | 222 | 可惜了，也不行，因为 `self` 不是一个有效的模式。 223 | 224 | 如果你真想同时匹配这两个标记，仅有的办法是换用 `tt` 来匹配。 225 | 226 | [`tt`]:./fragment-specifiers.html#tt 227 | [`ident`]:./fragment-specifiers.html#ident 228 | [`pat`]:./fragment-specifiers.html#pat 229 | [片段分类符]:./fragment-specifiers.html 230 | -------------------------------------------------------------------------------- /src/decl-macros/minutiae/import-export.md: -------------------------------------------------------------------------------- 1 | # 导入/导出 2 | 3 | 在 Rust 的 2015 和 2018 版本中，导入 `macro_rules!` 宏是不一样的。 4 | 仍然建议阅读这两部分，因为 2018 版使用的结构在 2015 版中做出了解释。 5 | 6 | ## 2015 版本 7 | 8 | ### `#[macro_use]` 9 | 10 | [作用域][scoping chapter] 一章中介绍的 `#[macro_use]` 属性 11 | 适用于模块或者 `external crates` 。例如： 12 | 13 | ```rust 14 | #[macro_use] 15 | mod macros { 16 | macro_rules! X { () => { Y!(); } } 17 | macro_rules! Y { () => {} } 18 | } 19 | 20 | X!(); 21 | # 22 | # fn main() {} 23 | ``` 24 | 25 | ### `#[macro_export]` 26 | 27 | 可通过 `#[macro_export]` 将宏从当前`crate`导出。注意，这种方式 **无视** 所有可见性设定。 28 | 29 | 定义 lib 包 `macs` 如下： 30 | 31 | ```rust,ignore 32 | mod macros { 33 | #[macro_export] macro_rules! X { () => { Y!(); } } 34 | #[macro_export] macro_rules! Y { () => {} } 35 | } 36 | 37 | // X! 和 Y! 并非在此处定义的，但它们 **的确** 被导出了（在此处可用） 38 | // 即便 `macros` 模块是私有的 39 | ``` 40 | 41 | 下面（在使用 `macs` lib 的 crate 中）的代码会正常工作： 42 | 43 | ```rust,ignore 44 | X!(); // X 在当前 crate 中被定义 45 | #[macro_use] extern crate macs; // 从 `macs` 中导入 X 46 | X!(); // 这里的 X 是最新声明的 X，即 `macs` crate 中导入的 X 47 | # 48 | # fn main() {} 49 | ``` 50 | 51 | 正如 [作用域][scoping chapter] 一章所说，`#[macro_use]` 作用于 `extern crate` 时， 52 | 会强制把导出的宏提到 crate 的顶层模块（根模块），所以这里无须使用 `macs::macros` 路径。 53 | 54 | > 注意：只有在根模组中，才可将 `#[macro_use]` 用于 `extern crate`。 55 | 56 | 在从 `extern crate` 导入宏时，可显式控制导入 **哪些** 宏。 57 | 从而利用这一特性来限制命名空间污染，或是覆盖某些特定的宏。就像这样： 58 | 59 | ```rust,ignore 60 | // 只导入 `X!` 这一个宏 61 | #[macro_use(X)] extern crate macs; 62 | 63 | // X!(); // X! 已被定义，但 Y! 未被定义。X 与 Y 无关系。 64 | 65 | macro_rules! Y { () => {} } 66 | 67 | X!(); // X 和 Y 都被定义 68 | 69 | fn main() {} 70 | ``` 71 | 72 | 当导出宏时，常常出现的情况是，宏定义需要其引用所在 `crate` 内的非宏符号。 73 | 由于 `crate` 可能被重命名等，我们可以使用一个特殊的替换变量 [`$crate`] 。 74 | 它总将被扩展为宏定义所在的 `crate` 的绝对路径（比如 `:: macs` ）。 75 | 76 | 如果你的编译器版本小于 1.30（即 2018 版之前），那么这招并不适用于宏。 77 | 也就是说，你没办法采用类似 `$crate::Y!` 的代码来引用自己 `crate` 里的定义的宏。 78 | 这表示结合 `#[macro_use]` 来选择性导入会无法保证某个名称的宏在另一个 crate 导入同名宏时依然可用。 79 | 80 | 推荐的做法是，在引用非宏名称时，总是采用绝对路径。 81 | 这样可以最大程度上避免冲突，包括跟标准库中名称的冲突。 82 | 83 | [`$crate`]:./hygiene.html#crate-元变量 84 | 85 | ## 2018 版本 86 | 87 | 2018 版本让使用 `macro_rules!` 宏更简单。 88 | 因为新版本设法让 Rust 中某些特殊的东西更像正常的 items 。 89 | 这意味着我们能以命名空间的方式正确导入和使用宏！ 90 | 91 | 因此，不必使用 `#[macro_use]` 来导入 来自 extern crate 导出的宏 到全局命名空间， 92 | 现在我们这样做就好了： 93 | 94 | ```rust,ignore 95 | use some_crate::some_macro; 96 | 97 | fn main() { 98 | some_macro!("hello"); 99 | // as well as 100 | some_crate::some_other_macro!("macro world"); 101 | } 102 | ``` 103 | 104 | 可惜，这只适用于导入外部 crate 的宏； 105 | 如果你使用在自己 crate 定义的 `macro_rules!` 宏， 106 | 那么依然需要把 `#[macro_use]` 添加到宏所定义的模块上来引入模块里面的宏。 107 | 因而 [作用域规则][scoping chapter] 就像之前谈论的那样生效。 108 | 109 | > [`$crate`] 前缀（元变量）在 2018 版中可适用于任何东西， 110 | > 在 1.31 版之后，宏 和类似 item 的东西都能用 `$crate` 导入了。 111 | 112 | [scoping chapter]:./scoping.html 113 | -------------------------------------------------------------------------------- /src/decl-macros/minutiae/metavar-and-expansion.md: -------------------------------------------------------------------------------- 1 | # 再谈元变量与宏展开 2 | 3 | ## 书写宏规则的顺序 4 | 5 | 一旦语法分析器开始消耗标记以匹配某捕获，整个过程便 **无法停止或回溯** 。 6 | 这意味着，无论输入是什么样的，下面这个宏的第二项规则将永远无法被匹配到： 7 | 8 | ```rust,editable 9 | macro_rules! dead_rule { 10 | ($e:expr) => { ... }; 11 | ($i:ident +) => { ... }; 12 | } 13 | 14 | fn main() { 15 | dead_rule!(x+); 16 | } 17 | ``` 18 | 19 | 考虑当以 `dead_rule!(x+)` 形式调用此宏时，将会发生什么。 20 | 解析器将从第一条规则开始试图进行匹配：它试图将输入解析为一个表达式。 21 | 第一个标记 `x` 作为表达式是有效的，第二个标记——作为二元加符号 `+` 的节点——在表达式中也是有效的。 22 | 23 | 由此你可能会以为，由于输入中并不包含二元加号 `+` 的右侧元素， 24 | 分析器将会放弃尝试这一规则，转而尝试下一条规则。 25 | 实则不然：分析器将会 panic 并终止整个编译过程，最终返回一个语法错误。 26 | 27 | 由于分析器的这一特点，下面这点尤为重要： 28 | 一般而言，在书写宏规则时，**应从最具体的开始写起，依次写直到最不具体的** 。 29 | 30 | ## 片段分类符的跟随限制 31 | 32 | 为防止将来的语法变动影响宏输入的解析方式， 33 | `macro_rules!` 对紧接元变量后的内容施加了限制。 34 | 在 Rust 1.52 中，能够紧跟片段分类符后面的内容具有如下限制[^Follow-set Ambiguity Restrictions]： 35 | 36 | * [`stmt`] 和 [`expr`]：`=>`、`,`、`;` 之一 37 | * [`pat`]：`=>`、`,`、`=`、`if`、`in` 之一[^pat-edition] 38 | * [`pat_param`]：`=>`、`,`、`=`、`|`、`if`、`in` 之一 39 | * [`path`] 和 [`ty`]：`=>`、`,`、`=`、`|`、`;`、`:`、`>`、`>>`、`[`、`{`、`as`、`where` 之一； 40 | 或者 [`block`] 型的元变量 41 | * [`vis`]：`,`、除了 `priv` 之外的标识符、任何以类型开头的标记、 42 | [`ident`] 或 [`ty`] 或 [`path`] 型的元变量 43 | * 其他片段分类符所跟的内容无限制 44 | 45 | [^pat-edition]: 使用 2021 edition 之前的 Rust，`pat` 依然可以跟随 `|`。 46 | 47 | 反复匹配的情况也遵循这些限制[^Follow-set Ambiguity Restrictions]，也就是说： 48 | 49 | 1. 如果一个重复操作符（`*` 或 `+`）能让一类元变量重复数次， 50 | 那么反复出现的内容就是这类元变量，反复结束之后所接的内容遵照上面的限制。 51 | 52 | 2. 如果一个重复操作符（`*` 或 `?`）让一类元变量重复零次， 53 | 那么元变量之后的内容遵照上面的限制。 54 | 55 | [^Follow-set Ambiguity Restrictions]: 内容来自于 *Reference* 56 | [follow-set-ambiguity-restrictions](https://doc.rust-lang.org/reference/macros-by-example.html#follow-set-ambiguity-restrictions) 一节。 57 | 58 | ## 编译器拒绝模糊的规则 59 | 60 | 解析器不会预先运行代码，这意味着如果编译器不能一次就唯一地确定如何解析宏调用， 61 | 那么编译器就带着模糊的报错信息而终止运行。 62 | 一个触发终止运行的例子是： 63 | 64 | ```rust,editable 65 | macro_rules! ambiguity { 66 | ($($i:ident)* $i2:ident) => { }; 67 | } 68 | 69 | // error: 70 | // local ambiguity: multiple parsing options: built-in NTs ident ('i') or ident ('i2'). 71 | fn main() { ambiguity!(an_identifier); } 72 | ``` 73 | 74 | 编译器不会提前看到传入的标识符之后是不是一个 `)`，如果提前看到的话就会解析正确。 75 | 76 | ## 不基于标记的代换 77 | 78 | 关于代换元变量 (substitution，这里指把已经进行宏解析的 token 再次传给宏) ， 79 | 常常让人惊讶的一面是，尽管 **很像** 是根据标记 (token) 进行代换的，但事实并非如此 80 | ——代换基于已经解析的 AST 节点。 81 | 82 | 思考下面的例子： 83 | 84 | ```rust,editable 85 | macro_rules! capture_then_match_tokens { 86 | ($e:expr) => {match_tokens!($e)}; 87 | } 88 | 89 | macro_rules! match_tokens { 90 | ($a:tt + $b:tt) => {"got an addition"}; 91 | (($i:ident)) => {"got an identifier"}; 92 | ($($other:tt)*) => {"got something else"}; 93 | } 94 | 95 | fn main() { 96 | println!("{}\n{}\n{}\n", 97 | match_tokens!((caravan)), 98 | match_tokens!(3 + 6), 99 | match_tokens!(5)); 100 | println!("{}\n{}\n{}", 101 | capture_then_match_tokens!((caravan)), 102 | capture_then_match_tokens!(3 + 6), 103 | capture_then_match_tokens!(5)); 104 | } 105 | ``` 106 | 107 | 其结果： 108 | 109 | ```text 110 | got an identifier 111 | got an addition 112 | got something else 113 | 114 | got something else 115 | got something else 116 | got something else 117 | ``` 118 | 119 | 通过解析已经传入 AST 节点的输入，代换的结果变得 *很稳定*：你再也无法检查其内容了， 120 | 也不再匹配内容。 121 | 122 | 另一个例子可能也会很令人困惑： 123 | 124 | ```rust,editable 125 | macro_rules! capture_then_what_is { 126 | (#[$m:meta]) => {what_is!(#[$m])}; 127 | } 128 | 129 | macro_rules! what_is { 130 | (#[no_mangle]) => {"no_mangle attribute"}; 131 | (#[inline]) => {"inline attribute"}; 132 | ($($tts:tt)*) => {concat!("something else (", stringify!($($tts)*), ")")}; 133 | } 134 | 135 | fn main() { 136 | println!( 137 | "{}\n{}\n{}\n{}", 138 | what_is!(#[no_mangle]), 139 | what_is!(#[inline]), 140 | capture_then_what_is!(#[no_mangle]), 141 | capture_then_what_is!(#[inline]), 142 | ); 143 | } 144 | ``` 145 | 146 | 结果是： 147 | 148 | ```text 149 | no_mangle attribute 150 | inline attribute 151 | something else (#[no_mangle]) 152 | something else (#[inline]) 153 | ``` 154 | 155 | 避免这个意外情况的唯一方式就是使用 [`tt`]、[`ident`] 或者 [`lifetime`] 分类符。 156 | 每当你捕获到除此之外的分类符，结果将只能被用于直接输出。 157 | 比如这里使用的 `stringify!`[^stringify]，它是一条内置于编译器的语法拓展 158 | （[查看源码可知](https://doc.rust-lang.org/src/core/macros/mod.rs.html#974-978)）， 159 | 将所有输入标记结合在一起，作为单个字符串输出。 160 | 161 | 162 | [`item`]:./fragment-specifiers.html#item 163 | [`block`]:./fragment-specifiers.html#block 164 | [`stmt`]:./fragment-specifiers.html#stmt 165 | [`pat`]:./fragment-specifiers.html#pat 166 | [`expr`]:./fragment-specifiers.html#expr 167 | [`ty`]:./fragment-specifiers.html#ty 168 | [`ident`]:./fragment-specifiers.html#ident 169 | [`path`]:./fragment-specifiers.html#path 170 | [`tt`]:./fragment-specifiers.html#tt 171 | [`meta`]:./fragment-specifiers.html#meta 172 | [`lifetime`]:./fragment-specifiers.html#lifetime 173 | [`vis`]:./fragment-specifiers.html#vis 174 | [`literal`]:./fragment-specifiers.html#literal 175 | 176 | 177 | [^stringify]:这里未包含原作对 `stringify!` 用于替换 (substitution) 场景的 [解读](https://danielkeep.github.io/tlborm/book/mbe-min-captures-and-expansion-redux.html)，因为那个例子的结果有些变化。 178 | -------------------------------------------------------------------------------- /src/decl-macros/minutiae/metavar-expr.md: -------------------------------------------------------------------------------- 1 | # 元变量表达式 2 | 3 | > *RFC*: [rfcs#1584](https://github.com/rust-lang/rfcs/blob/master/text/3086-macro-metavar-expr.md) 4 | > *Tracking Issue*: [rust#83527](https://github.com/rust-lang/rust/issues/83527) 5 | > *Feature*: `#![feature(macro_metavar_expr)]` 6 | 7 | > 注意：示例代码片段非常简单，只试图展示它们是如何工作的。 8 | > 关于这些元变量表达式，如果你认为你有合适的、单独使用的小片段，请提交它们！ 9 | 10 | 正如在 [思路][methodical] 中提到的，Rust 有一些特殊的元变量表达式（以下简称表达式）：transcriber[^transcribe] 11 | 可以使用这些表达式来获取有关元变量的信息。如果没有这些表达式，它们所提供的信息就很难甚至不可能获得。 12 | 13 | 本章将结合用例对它们进行更深入的介绍。 14 | 15 | * [`$$`](#dollar-dollar-) 16 | * [`${count($ident, depth)}`](#countident-depth) 17 | * [`${index(depth)}`](#indexdepth) 18 | * [`${len(depth)}`](#lengthdepth) 19 | * [`${ignore(ident)}`](#ignoreident) 20 | 21 | [methodical]: ../macros-methodical.md 22 | [^transcribe]: 译者注：在专业的讨论中，尤其涉及元变量表达式，常用 transcribe(r) 一词而不使用 expand (expansion)。 23 | 24 | ## Dollar Dollar (`$$`) 25 | 26 | `$$` 表达式展开为单个 `$`，实际上使其成为转义的 `$`。这让声明宏宏生成新的声明宏。 27 | 28 | 因为以前的声明宏将无法转义 `$`，所以无法使用元变量、重复和元变量表达式。例如以下代码片段中不使用 `$$`，就无法使用 `bar!`： 29 | 30 | ```rust 31 | macro_rules! foo { 32 | () => { 33 | macro_rules! bar { 34 | ( $( $any:tt )* ) => { $( $any )* }; 35 | // ^^^^^^^^^^^ error: attempted to repeat an expression containing no syntax variables matched as repeating at this depth 36 | } 37 | }; 38 | } 39 | 40 | foo!(); 41 | # fn main() {} 42 | ``` 43 | 44 | 问题很明显， `foo!` 的 transcriber 看到有反复捕获的意图，并试图反复捕获，但它的作用域中没有 `$any` 45 | 元变量，这导致它产生错误。有了 `$$`，我们就可以解决这个问题[^foo-bar]，因为 `foo` 的 transcriber 不再尝试反复捕获。 46 | 47 | ```rust 48 | #![feature(macro_metavar_expr)] 49 | 50 | macro_rules! foo { 51 | () => { 52 | macro_rules! bar { 53 | ( $$( $$any:tt )* ) => { $$( $$any )* }; 54 | } 55 | }; 56 | } 57 | 58 | foo!(); 59 | bar!(); 60 | # fn main() {} 61 | ``` 62 | 63 | [^foo-bar]: 译者注：在没有 `$$` 之前，存在一种技巧绕过这里的问题：你可以使用 `$tt` 捕获 `$` 来进行转义，比如[这样][tt-$]。 64 | 65 | [tt-$]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=9ce18fc79ce17c77d20e74f3c46ee13c 66 | 67 | ## `count($ident, depth)` 68 | 69 | `count` 表达式展开成元变量 `$ident` 在给定反复深度的反复次数。 70 | 71 | * `ident` 参数必须是规则作用域中声明的元变量 72 | * `depth ` 参数必须是值小于或等于元变量 `$ident` 出现的最大反复深度的整型字面值 73 | * `count(ident, depth)` 展开成不带后缀的整型字面值标记 74 | * `count(ident)` 是 `count(ident, 0)` 的简写 75 | 76 | ```rust,editable 77 | #![feature(macro_metavar_expr)] 78 | 79 | macro_rules! foo { 80 | ( $( $outer:ident ( $( $inner:ident ),* ) ; )* ) => { 81 | println!("count(outer, 0): $outer repeats {} times", ${count($outer)}); 82 | println!("count(inner, 0): The $inner repetition repeats {} times in the outer repetition", ${count($inner, 0)}); 83 | println!("count(inner, 1): $inner repeats {} times in the inner repetitions", ${count($inner, 1)}); 84 | }; 85 | } 86 | 87 | fn main() { 88 | foo! { 89 | outer () ; 90 | outer ( inner , inner ) ; 91 | outer () ; 92 | outer ( inner ) ; 93 | }; 94 | } 95 | ``` 96 | 97 | ## `index(depth)` 98 | 99 | `index(depth)` 表达式展开为给定反复深度下，当前的迭代索引。 100 | 101 | * `depth` 参数表明在第几层反复，这个数字从最内层反复调用表达式开始向外计算 102 | * `index(depth)` 展开成不带后缀的整型字面值标记 103 | * `index()` 是 `index(0)` 的简写 104 | 105 | ```rust,editable 106 | #![feature(macro_metavar_expr)] 107 | 108 | macro_rules! attach_iteration_counts { 109 | ( $( ( $( $inner:ident ),* ) ; )* ) => { 110 | ( $( 111 | $(( 112 | stringify!($inner), 113 | ${index(1)}, // 这指的是外层反复 114 | ${index()} // 这指的是内层反复，等价于 `index(0)` 115 | ),)* 116 | )* ) 117 | }; 118 | } 119 | 120 | fn main() { 121 | let v = attach_iteration_counts! { 122 | ( hello ) ; 123 | ( indices , of ) ; 124 | () ; 125 | ( these, repetitions ) ; 126 | }; 127 | println!("{v:?}"); 128 | } 129 | ``` 130 | 131 | ## `len(depth)` 132 | 133 | `length(depth)` 表达式展开为在给定反复深度的迭代次数。 134 | 135 | * `depth` 参数表示在第几层反复，这个数字从最内层反复调用表达式开始向外计算 136 | * `length(depth)` 展开成不带后缀的整型字面值标记 137 | * `length()` 是 `length(0)` 的简写 138 | 139 | ```rust,editable 140 | #![feature(macro_metavar_expr)] 141 | 142 | macro_rules! lets_count { 143 | ( $( $outer:ident ( $( $inner:ident ),* ) ; )* ) => { 144 | $( 145 | $( 146 | println!( 147 | "'{}' in inner iteration {}/{} with '{}' in outer iteration {}/{} ", 148 | stringify!($inner), ${index()}, ${len()}, 149 | stringify!($outer), ${index(1)}, ${len(1)}, 150 | ); 151 | )* 152 | )* 153 | }; 154 | } 155 | 156 | fn main() { 157 | lets_count!( 158 | many (small , things) ; 159 | none () ; 160 | exactly ( one ) ; 161 | ); 162 | } 163 | ``` 164 | 165 | ## `ignore(ident)` 166 | 167 | `ignore(ident)` 表达式展开为空，这使得在无需实际展开元变量的时候，像元变量反复展开相同次数的某些内容。 168 | 169 | * `ident` 参数必须是规则作用域中声明的元变量 170 | 171 | ```rust,editable 172 | #![feature(macro_metavar_expr)] 173 | 174 | macro_rules! repetition_tuples { 175 | ( $( ( $( $inner:ident ),* ) ; )* ) => { 176 | ($( 177 | $( 178 | ( 179 | ${index()}, 180 | ${index(1)} 181 | ${ignore($inner)} // without this metavariable expression, compilation would fail 182 | ), 183 | )* 184 | )*) 185 | }; 186 | } 187 | 188 | fn main() { 189 | let tuple = repetition_tuples!( 190 | ( one, two ) ; 191 | () ; 192 | ( one ) ; 193 | ( one, two, three ) ; 194 | ); 195 | println!("{tuple:?}"); 196 | } 197 | ``` 198 | -------------------------------------------------------------------------------- /src/decl-macros/minutiae/scoping.md: -------------------------------------------------------------------------------- 1 | # 作用域 2 | 3 | > 这部分最新的内容可参考 *Reference* 的 4 | [scoping-exporting-and-importing](https://doc.rust-lang.org/nightly/reference/macros-by-example.html#scoping-exporting-and-importing) 5 | 一节。部分翻译内容引自 *Reference* 6 | [中文版](https://minstrel1977.gitee.io/rust-reference/macros-by-example.html#scoping-exporting-and-importing)。 7 | 8 | 函数式宏的作用域规则可能有一点反直觉。（函数式宏包括声明宏与函数式过程宏。） 9 | 由于历史原因，宏的作用域并不完全像各种程序项那样工作。 10 | 11 | 有两种形式的作用域：文本作用域 (textual scope) 和 基于路径的作用域 (path-based scope)。 12 | 13 | 文本作用域：基于宏在源文件中（定义和使用所）出现的顺序，或是跨多个源文件出现的顺序， 14 | 文本作用域是默认的作用域。 15 | 16 | 基于路径的作用域：与其他程序项作用域的运行方式相同。 17 | 18 | 当声明宏被 非限定标识符（unqualified identifier，非多段路径段组成的限定性路径）调用时， 19 | 会首先在文本作用域中查找。 20 | 如果文本作用域中没有任何结果，则继续在基于路径的作用域中查找。 21 | 22 | 如果宏的名称由路径限定 (qualified with a path) ，则只在基于路径的作用域中查找。 23 | 24 | ## 文本作用域 25 | 26 | ### 宏在子模块中可见 27 | 28 | 与 Rust 语言其余所有部分都不同的是，函数式宏在子模块中仍然可见。 29 | 30 | ```rust,editable 31 | macro_rules! X { () => {}; } 32 | mod a { 33 | X!(); // defined 34 | } 35 | mod b { 36 | X!(); // defined 37 | } 38 | mod c { 39 | X!(); // defined 40 | } 41 | # fn main() {} 42 | ``` 43 | 44 | > 注意：即使子模组的内容处在不同文件中，这些例子中所述的行为仍然保持不变。 45 | 46 | ### 宏在定义之后可见 47 | 48 | 同样与 Rust 语言其余所有部分不同，宏只有在其定义 **之后** 可见。 49 | 下例展示了这一点。同时注意到，它也展示了宏不会“漏出” (leak) 其定义所在的作用域： 50 | 51 | ```rust,editable 52 | mod a { 53 | // X!(); // undefined 54 | } 55 | mod b { 56 | // X!(); // undefined 57 | macro_rules! X { () => {}; } 58 | X!(); // defined 59 | } 60 | mod c { 61 | // X!(); // undefined 62 | } 63 | # fn main() {} 64 | ``` 65 | 66 | 要清楚，即使你把宏移动到外层作用域，词法依赖顺序的规则依然适用。 67 | 68 | ```rust,editable 69 | mod a { 70 | // X!(); // undefined 71 | } 72 | 73 | macro_rules! X { () => {}; } 74 | 75 | mod b { 76 | X!(); // defined 77 | } 78 | mod c { 79 | X!(); // defined 80 | } 81 | # fn main() {} 82 | ``` 83 | 84 | ### 宏与宏之间顺序无关 85 | 86 | 然而对于宏自身来说，这种具有顺序的依赖行为不存在。 87 | 即被调用的宏可以先于调用宏之前声明： 88 | 89 | ```rust,editable 90 | mod a { 91 | // X!(); // undefined 92 | } 93 | 94 | macro_rules! X { () => { Y!(); }; } // 注意这里的代码运行通过 95 | 96 | mod b { 97 | // 注意这里 X 虽然被定义，但是 Y 不被定义，所以不能使用 X 98 | // X!(); // defined, but Y! is undefined 99 | } 100 | 101 | macro_rules! Y { () => {}; } 102 | 103 | mod c { 104 | X!(); // defined, and so is Y! 105 | } 106 | # fn main() {} 107 | ``` 108 | 109 | ### 宏可以被暂时覆盖 110 | 111 | 允许多次定义 `macro_rules!` 宏，最后声明的宏会简单地覆盖 (shadow) 上一个声明的同名宏； 112 | 如果最后声明的宏离开作用域，上一个宏在有效的作用域内还能被使用。 113 | 114 | ```rust,editable 115 | macro_rules! X { (1) => {}; } 116 | X!(1); 117 | macro_rules! X { (2) => {}; } 118 | // X!(1); // Error: no rule matches `1` 119 | X!(2); 120 | 121 | mod a { 122 | macro_rules! X { (3) => {}; } 123 | // X!(2); // Error: no rule matches `2` 124 | X!(3); 125 | } 126 | // X!(3); // Error: no rule matches `3` 127 | X!(2); 128 | 129 | fn main() { } 130 | ``` 131 | ### `#[macro_use]` 属性 132 | 133 | 这个属性放置在宏定义所在的模块前 或者 `extern crate` 语句前。 134 | 135 | 1. 在模块前加上 `#[macro_use]` 属性：导出该模块内的所有宏， 136 | 从而让导出的宏在所定义的模块结束之后依然可用。 137 | 138 | ```rust,editable 139 | mod a { 140 | // X!(); // undefined 141 | } 142 | 143 | #[macro_use] 144 | mod b { 145 | macro_rules! X { () => {}; } 146 | X!(); // defined 147 | } 148 | 149 | mod c { 150 | X!(); // defined 151 | } 152 | # fn main() {} 153 | ``` 154 | 155 | 注意，这可能会产生一些奇怪的后果，因为宏（包括过程宏）中的标识符只有在宏展开的过程中才会被解析。 156 | 157 | ```rust,editable 158 | mod a { 159 | // X!(); // undefined 160 | } 161 | 162 | #[macro_use] 163 | mod b { 164 | macro_rules! X { () => { Y!(); }; } 165 | // X!(); // defined, but Y! is undefined 166 | } 167 | 168 | macro_rules! Y { () => {}; } 169 | 170 | mod c { 171 | X!(); // defined, and so is Y! 172 | } 173 | # fn main() {} 174 | ``` 175 | 176 | 2. 给 `extern crate` 语句加上 `#[macro_use]` 属性： 177 | 把外部 crate 定义且导出的宏引入当前 crate 的根/顶层模块。（当前 crate 使用外部 crate） 178 | 179 | 假设在外部名称为 `mac` 的 crate 中定义了 `X!` 宏，在当前模块： 180 | 181 | ```rust,ignore 182 | //// 这里的 `X!` 与 `Y!` 无关，前者定义于外部 crate，后者定义于当前 crate 183 | 184 | mod a { 185 | // X!(); // defined, but Y! is undefined 186 | } 187 | 188 | macro_rules! Y { () => {}; } 189 | 190 | mod b { 191 | X!(); // defined, and so is Y! 192 | } 193 | 194 | #[macro_use] extern crate macs; 195 | mod c { 196 | X!(); // defined, and so is Y! 197 | } 198 | 199 | # fn main() {} 200 | ``` 201 | 202 | ### 当宏放在函数内 203 | 204 | 前四条作用域规则同样适用于函数。 205 | 至于第五条规则， `#[macro_use]` 属性并不直接作用于函数。 206 | 207 | ```rust,editable 208 | macro_rules! X { 209 | () => { Y!() }; 210 | } 211 | 212 | fn a() { 213 | macro_rules! Y { () => {"Hi!"} } 214 | assert_eq!(X!(), "Hi!"); 215 | { 216 | assert_eq!(X!(), "Hi!"); 217 | macro_rules! Y { () => {"Bye!"} } 218 | assert_eq!(X!(), "Bye!"); 219 | } 220 | assert_eq!(X!(), "Hi!"); 221 | } 222 | 223 | fn b() { 224 | macro_rules! Y { () => {"One more"} } 225 | assert_eq!(X!(), "One more"); 226 | } 227 | # 228 | # fn main() { 229 | # a(); 230 | # b(); 231 | # } 232 | ``` 233 | 234 | ### 关于宏声明的位置 235 | 236 | 由于前述种种规则，一般来说， 237 | 建议将所有应对整个 `crate` 均可见的宏的定义置于根模块的最顶部， 238 | 借以确保它们 **一直** 可用。 239 | 这个建议和适用于在文件 `mod` 定义的宏： 240 | 241 | ```rust,ignore 242 | #[macro_use] 243 | mod some_mod_that_defines_macros; 244 | mod some_mod_that_uses_those_macros; 245 | ``` 246 | 247 | 这里的顺序很重要，因为第二个模块依赖于第一个模块的宏， 248 | 所以改变这两个模块的顺序会无法编译。 249 | 250 | ## 基于路径的作用域 251 | 252 | Rust 的 `macro_rules!` 宏 默认并没有基于路径的作用域。 253 | 254 | 然而，如果这个宏被加上 `#[macro_export]` 属性，那么它就在 crate 的根作用域里被定义， 255 | 而且能直接使用它。 256 | 257 | [导入/导出宏][Import and Export] 一章会更深入地探讨这个属性。 258 | 259 | 260 | [Import and Export]: ./import-export.html 261 | 262 | -------------------------------------------------------------------------------- /src/decl-macros/patterns.md: -------------------------------------------------------------------------------- 1 | # 模式 2 | 3 | 解析和展开模式。 4 | -------------------------------------------------------------------------------- /src/decl-macros/patterns/callbacks.md: -------------------------------------------------------------------------------- 1 | # 回调 2 | 3 | ```rust,editable 4 | macro_rules! call_with_larch { 5 | ($callback:ident) => { $callback!(larch) }; 6 | } 7 | 8 | macro_rules! expand_to_larch { 9 | () => { larch }; 10 | } 11 | 12 | macro_rules! recognize_tree { 13 | (larch) => { println!("#1, the Larch.") }; 14 | (redwood) => { println!("#2, the Mighty Redwood.") }; 15 | (fir) => { println!("#3, the Fir.") }; 16 | (chestnut) => { println!("#4, the Horse Chestnut.") }; 17 | (pine) => { println!("#5, the Scots Pine.") }; 18 | ($($other:tt)*) => { println!("I don't know; some kind of birch maybe?") }; 19 | } 20 | 21 | fn main() { 22 | recognize_tree!(expand_to_larch!()); // 无法直接使用 `expand_to_larch!` 的展开结果 23 | call_with_larch!(recognize_tree); // 回调就是给另一个宏传入宏的名称 (`ident`)，而不是宏的结果 24 | } 25 | 26 | // 打印结果： 27 | // I don't know; some kind of birch maybe? 28 | // #1, the Larch. 29 | ``` 30 | 31 | 由于宏展开的机制限制，（至少在最新的 Rust 中） 32 | 不可能做到把一例宏的展开结果作为有效信息提供给另一例宏。 33 | 这为宏的模块化工作施加了难度。 34 | 35 | 使用递归并传递回调 (callbacks) 是条出路。 36 | 作为演示，上例两处宏调用的展开过程如下： 37 | 38 | ```rust,ignore 39 | recognize_tree! { expand_to_larch ! ( ) } 40 | println! { "I don't know; some kind of birch maybe?" } 41 | // ... 42 | 43 | call_with_larch! { recognize_tree } 44 | recognize_tree! { larch } 45 | println! { "#1, the Larch." } 46 | // ... 47 | ``` 48 | 49 | 可以反复匹配 `tt` 来将任意参数转发给回调： 50 | 51 | ```rust,editable 52 | macro_rules! callback { 53 | ($callback:ident( $($args:tt)* )) => { 54 | $callback!( $($args)* ) 55 | }; 56 | } 57 | 58 | fn main() { 59 | callback!(callback(println("Yes, this *was* unnecessary."))); 60 | } 61 | ``` 62 | 63 | 如果需要的话，当然还可以在参数中增加额外的标记 (tokens) 。 64 | -------------------------------------------------------------------------------- /src/decl-macros/patterns/internal-rules.md: -------------------------------------------------------------------------------- 1 | # 内用规则 2 | 3 | ```rust 4 | #[macro_export] 5 | macro_rules! foo { 6 | (@as_expr $e:expr) => {$e}; 7 | 8 | ($($tts:tt)*) => { 9 | foo!(@as_expr $($tts)*) 10 | }; 11 | } 12 | # 13 | # fn main() { 14 | # assert_eq!(foo!(42), 42); 15 | # } 16 | ``` 17 | 18 | 内用规则可用在以下两种情况： 19 | 1. 将多个宏统一为一个； 20 | 2. 通过显式命名宏中调用的规则，来简化 [`TT` “撕咬机”][TT Munchers] 的读写。 21 | 22 | 那么为什么将多个宏统一为一个有用呢？ 23 | 主要原因是：在 2015 版本中，未对宏进行空间命名。这导致一个问题——必须重新导出内部定义的所有宏， 24 | 从而污染整个全局宏命名空间；更糟糕的是，宏与其他 crate 的同名宏发生冲突。 25 | 简而言之，这很造成很多麻烦。 26 | 幸运的是，在 rustc版本 >= 1.30 的情况下（即 2018 版本之后）， 27 | 这不再是问题了（但是内用规则可以减少不必要声明的宏）， 28 | 有关宏导出更多信息，请参阅本书 [导入/导出宏](../macros/minutiae/import-export.md) 。 29 | 30 | 好了，让我们讨论如何利用“内用规则” (internal rules) 来把多个宏统一为一个， 31 | 以及“内用规则”这项技术到底是什么吧。 32 | 33 | 这个例子有两个宏，一个常见的 [`as_expr!`](../building-blocks/ast-coercion.html) 宏 34 | 和 `foo!` 宏，后者使用了前者。如果分开写就是下面的形式： 35 | 36 | ```rust 37 | #[macro_export] 38 | macro_rules! as_expr { ($e:expr) => {$e} } 39 | 40 | #[macro_export] 41 | macro_rules! foo { 42 | ($($tts:tt)*) => { 43 | as_expr!($($tts)*) 44 | }; 45 | } 46 | # 47 | # fn main() { 48 | # assert_eq!(foo!(42), 42); 49 | # } 50 | ``` 51 | 52 | 这当然不是最好的解决办法，正如前面提到的，因为 `as_expr` 污染了全局宏命名空间。 53 | 在这个特定的例子里，`as_expr` 只是一个简单的宏，它只会被使用一次， 54 | 所以，利用内用规则，把它“嵌入”到 `foo` 这个宏里面吧！ 55 | 56 | 在 `foo` 仅有的一条规则前面添加一条新匹配模式（新规则）， 57 | 这个匹配模式由 `as_expr` 组成（和命名），然后附加上宏的输入参数 `$e:expr` ； 58 | 在展开里填写这个宏被匹配到时具体的内容。从而得到本章开头的代码： 59 | 60 | ```rust,editable 61 | #[macro_export] 62 | macro_rules! foo { 63 | (@as_expr $e:expr) => {$e}; 64 | 65 | ($($tts:tt)*) => { 66 | foo!(@as_expr $($tts)*) 67 | }; 68 | } 69 | # 70 | # fn main() { 71 | # assert_eq!(foo!(42), 42); 72 | # } 73 | ``` 74 | 75 | 可以看到，没有调用 `as_expr` 宏，而是递归调用在参数前放置了特殊标记树的 `foo!(@as_expr $($tts)*)`。 76 | 要是你看得仔细些，你甚至会发现这个模式能好地结合 [`TT` 撕咬机][TT Munchers] ！ 77 | 78 | 之所以用 `@` ，是因为在 Rust 1.2 下，该标记尚无任何在前缀位置的用法； 79 | 因此，这个语法定义在当时不会与任何东西撞车。 80 | 如果你想用别的符号或特有前缀都可以（比如试试 `#`、`!` ）， 81 | 但 `@` 的用例已被传播开来，因此，使用它可能更容易帮助读者理解你的代码。 82 | 83 | > 注意：`@` 符号很早之前曾作为前缀被用于表示被垃圾回收了的指针， 84 | 那时 Rust 还在采用各种记号代表指针类型。 85 | > 86 | > 而现在的 `@` 只有一种用法： 87 | 将名称绑定至模式中（譬如 `match` 的模式匹配中）。 88 | 在这种用法中它是中缀运算符，与我们的上述用例并不冲突。 89 | 90 | 还有一点要注意，内用规则通常应排在“真正的”规则之前。 91 | 这样做可避免 `macro_rules!` 错把内用规则调用解析成别的东西，比如表达式。 92 | 93 | [TT Munchers]:./tt-muncher.html 94 | 95 | # 性能建议 96 | 97 | 内用规则的一个缺点是它们会增加编译时间。 98 | 99 | 即便最终只有一条规则的宏可以匹配（有效的）宏调用，但编译器必须尝试按顺序匹配所有规则。 100 | 101 | 如果宏有许多规则，则可能会有许多匹配失败的情况，而使用内部规则会增加此类匹配失败的数量。 102 | 103 | 此外，`@as_expr` 方式的标识符使规则变得更长，这略微增加了编译器在匹配时必须做的工作量。 104 | 105 | 因此，为了获得最佳性能，**最好避免使用内部规则**。 106 | 107 | 避免使用它们通常也会使复杂的宏更易于阅读。 108 | -------------------------------------------------------------------------------- /src/decl-macros/patterns/push-down-acc.md: -------------------------------------------------------------------------------- 1 | # 下推累积 2 | 3 | ```rust 4 | macro_rules! init_array { 5 | (@accum (0, $_e:expr) -> ($($body:tt)*)) 6 | => {init_array!(@as_expr [$($body)*])}; 7 | (@accum (1, $e:expr) -> ($($body:tt)*)) 8 | => {init_array!(@accum (0, $e) -> ($($body)* $e,))}; 9 | (@accum (2, $e:expr) -> ($($body:tt)*)) 10 | => {init_array!(@accum (1, $e) -> ($($body)* $e,))}; 11 | (@accum (3, $e:expr) -> ($($body:tt)*)) 12 | => {init_array!(@accum (2, $e) -> ($($body)* $e,))}; 13 | (@as_expr $e:expr) => {$e}; 14 | [$e:expr; $n:tt] => { 15 | { 16 | let e = $e; 17 | init_array!(@accum ($n, e.clone()) -> ()) 18 | } 19 | }; 20 | } 21 | 22 | let strings: [String; 3] = init_array![String::from("hi!"); 3]; 23 | # assert_eq!(format!("{:?}", strings), "[\"hi!\", \"hi!\", \"hi!\"]"); 24 | ``` 25 | 26 | 在 Rust 中，所有宏最终 **必须** 展开为一个完整、有效的句法元素（比如表达式、条目等等）。 27 | 这意味着，不可能定义一个最终展开为残缺构造的宏。 28 | 29 | 有些人可能希望，上例中的宏能被更加直截了当地表述成： 30 | 31 | ```ignore 32 | macro_rules! init_array { 33 | (@accum 0, $_e:expr) => {/* empty */}; 34 | (@accum 1, $e:expr) => {$e}; 35 | (@accum 2, $e:expr) => {$e, init_array!(@accum 1, $e)}; 36 | (@accum 3, $e:expr) => {$e, init_array!(@accum 2, $e)}; 37 | [$e:expr; $n:tt] => { 38 | { 39 | let e = $e; 40 | [init_array!(@accum $n, e)] 41 | } 42 | }; 43 | } 44 | ``` 45 | 46 | 他们预期的展开过程如下： 47 | 48 | ```rust,ignore 49 | [init_array!(@accum 3, e)] 50 | [e, init_array!(@accum 2, e)] 51 | [e, e, init_array!(@accum 1, e)] 52 | [e, e, e] 53 | ``` 54 | 55 | 然而，这一思路中，每个中间步骤的展开结果都是一个不完整的表达式。 56 | 即便这些中间结果对外部来说绝不可见，Rust 仍然禁止这种用法。 57 | 58 | 下推累积 (push-down accumulation) 则使我们得以在完全完成之前毋需考虑构造的完整性， 59 | 进而累积构建出我们所需的标记序列。 60 | 本章开头给出的示例中，宏调用的展开过程如下： 61 | 62 | ```rust,ignore 63 | init_array! { String:: from ( "hi!" ) ; 3 } 64 | init_array! { @ accum ( 3 , e . clone ( ) ) -> ( ) } 65 | init_array! { @ accum ( 2 , e.clone() ) -> ( e.clone() , ) } 66 | init_array! { @ accum ( 1 , e.clone() ) -> ( e.clone() , e.clone() , ) } 67 | init_array! { @ accum ( 0 , e.clone() ) -> ( e.clone() , e.clone() , e.clone() , ) } 68 | init_array! { @ as_expr [ e.clone() , e.clone() , e.clone() , ] } 69 | ``` 70 | 71 | 可以修改一下代码，看到每次调用时 `$($body)*` 存储的内容变化： 72 | 73 | ```rust,editable 74 | macro_rules! init_array { 75 | (@accum (0, $_e:expr) -> ($($body:tt)*)) 76 | => {init_array!(@as_expr [$($body)*])}; 77 | (@accum (1, $e:expr) -> ($($body:tt)*)) 78 | => {init_array!(@accum (0, $e) -> ($($body)* $e+3,))}; 79 | (@accum (2, $e:expr) -> ($($body:tt)*)) 80 | => {init_array!(@accum (1, $e) -> ($($body)* $e+2,))}; 81 | (@accum (3, $e:expr) -> ($($body:tt)*)) 82 | => {init_array!(@accum (2, $e) -> ($($body)* $e+1,))}; 83 | (@as_expr $e:expr) => {$e}; 84 | [$e:expr; $n:tt $(; first $init:expr)?] => { 85 | { 86 | let e = $e; 87 | init_array!(@accum ($n, e.clone()) -> ($($init)?,)) 88 | } 89 | }; 90 | } 91 | 92 | fn main() { 93 | let array: [usize; 4] = init_array![0; 3; first 0]; 94 | println!("{:?}", array); 95 | } 96 | ``` 97 | 98 | 根据 [调试](../macros/minutiae/debugging.md) 一章的内容， 99 | 在 nightly Rust 中使用编译命令： 100 | `cargo rustc --bin my-project -- -Z trace-macros` ，即得到以下输出： 101 | 102 | ```rust,ignore 103 | note: trace_macro 104 | --> src/main.rs:20:31 105 | | 106 | 20 | let array: [usize; 4] = init_array![0; 3; first 0]; 107 | | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 108 | | 109 | = note: expanding `init_array! { 0 ; 3 ; first 0 }` 110 | = note: to `{ let e = 0 ; init_array! (@ accum(3, e.clone()) -> (0,)) }` 111 | = note: expanding `init_array! { @ accum(3, e.clone()) -> (0,) }` 112 | = note: to `init_array! (@ accum(2, e.clone()) -> (0, e.clone() + 1,))` 113 | = note: expanding `init_array! { @ accum(2, e.clone()) -> (0, e.clone() + 1,) }` 114 | = note: to `init_array! (@ accum(1, e.clone()) -> (0, e.clone() + 1, e.clone() + 2,))` 115 | = note: expanding `init_array! { @ accum(1, e.clone()) -> (0, e.clone() + 1, e.clone() + 2,) }` 116 | = note: to `init_array! 117 | (@ accum(0, e.clone()) -> (0, e.clone() + 1, e.clone() + 2, e.clone() + 3,))` 118 | = note: expanding `init_array! { @ accum(0, e.clone()) -> (0, e.clone() + 1, e.clone() + 2, e.clone() + 3,) }` 119 | = note: to `init_array! (@ as_expr [0, e.clone() + 1, e.clone() + 2, e.clone() + 3,])` 120 | = note: expanding `init_array! { @ as_expr [0, e.clone() + 1, e.clone() + 2, e.clone() + 3,] }` 121 | = note: to `[0, e.clone() + 1, e.clone() + 2, e.clone() + 3]` 122 | ``` 123 | 124 | 可以看到，每一步都在累积输出，直到规则完成，给出完整的表达式。 125 | 126 | 上述过程的关键点在于，使用 `$($body:tt)*` 来保存输出中间值， 127 | 而不触发其它解析机制。采用 `($input) -> ($output)` 128 | 的形式仅是出于传统，用以明示此类宏的作用。 129 | 130 | 由于可以存储任意复杂的中间结果， 131 | 下推累积在构建 [`TT` 撕咬机](./tt-muncher.md) 的过程中经常被用到。 132 | 当构造类似于这个例子的宏时，也会结合 [内用规则](./internal-rules.md)。 133 | 134 | # 性能建议 135 | 136 | 下推累积本质上是二次复杂度的。考虑一个包含 100 137 | 个标记树的累加器[^accumulator]，每次调用一个标记树： 138 | 139 | * 初始调用将匹配空的累加器 140 | * 调用第一个递归将匹配 1 个标记树累加器 141 | * 调用下一个递归将匹配 2 个标记树累加器 142 | * 以此类推，最多 100 个 143 | 144 | 这是一个典型的二次复杂度模式，长输入会导致宏延长编译时间。 145 | 146 | 此外，TT 撕咬机对其输入也是天生的二次复杂度，所以同时使用 147 | TT 撕咬机和下推累积的宏将是双倍二次的！ 148 | 149 | 所有关于 TT 撕咬机的[性能建议](./tt-muncher.md#performance)都适用于下推积累。 150 | 151 | 一般来说，避免过多地使用它们，并尽可能地让它们的简单。 152 | 153 | 最后，确保将累加器放在规则的末尾，而不是开头。 154 | 155 | 这样，如果匹配规则失败，编译器就不必匹配（可能很长的）累加器，从而避免遇到规则中不匹配的部分。这可能会对编译时间产生很大影响。 156 | 157 | [^accumulator]: 译者注：accumulator，即使用下推累积方式编写的声明宏。 158 | -------------------------------------------------------------------------------- /src/decl-macros/patterns/repetition-replacement.md: -------------------------------------------------------------------------------- 1 | # 反复替换 2 | 3 | ```rust,ignore 4 | macro_rules! replace_expr { 5 | ($_t:tt $sub:expr) => {$sub}; 6 | } 7 | ``` 8 | 9 | 在上面代码的模式中，匹配到的重复序列将被直接丢弃， 10 | 仅留用它所带来的长度信息（以及元素的类型信息）； 11 | 且原本标记所在的位置将被替换成某种重复元素。 12 | 13 | 举个例子，考虑如何为一个元素多于12个 （Rust 1.2 下的元组元素个数的最大值） 14 | 的 `tuple` 提供默认值。 15 | 16 | ```rust,editable 17 | macro_rules! tuple_default { 18 | ($($tup_tys:ty),*) => { 19 | ( 20 | $( 21 | replace_expr!( 22 | ($tup_tys) 23 | Default::default() 24 | ), 25 | )* 26 | ) 27 | }; 28 | } 29 | 30 | macro_rules! replace_expr { 31 | ($_t:tt $sub:expr) => { 32 | $sub 33 | }; 34 | } 35 | 36 | fn main() { 37 | assert_eq!(tuple_default!(i32, bool, String), 38 | (i32::default(), bool::default(), String::default())); 39 | } 40 | ``` 41 | 42 | > **仅对此例**： 43 | 我们其实可以直接用 `$tup_tys::default()` 。 44 | 45 | 上例中，我们 **并未真正使用** 匹配到的类型。 46 | 实际上，我们把它丢弃了，并用一个表达式重复替代 (repetition replacement) 。 47 | 换句话说，我们实际关心的不是有哪些类型，而是有多少个类型。 48 | -------------------------------------------------------------------------------- /src/decl-macros/patterns/tt-bundling.md: -------------------------------------------------------------------------------- 1 | # `TT` 捆绑 2 | 3 | ```rust,editable 4 | macro_rules! call_a_or_b_on_tail { 5 | ((a: $a:ident, b: $b:ident), call a: $($tail:tt)*) => { 6 | $a(stringify!($($tail)*)) 7 | }; 8 | 9 | ((a: $a:ident, b: $b:ident), call b: $($tail:tt)*) => { 10 | $b(stringify!($($tail)*)) 11 | }; 12 | 13 | ($ab:tt, $_skip:tt $($tail:tt)*) => { 14 | call_a_or_b_on_tail!($ab, $($tail)*) 15 | }; 16 | } 17 | 18 | fn compute_len(s: &str) -> Option