rust-course/contents/advance/macro.md

# Macro宏编程
在编程世界可以说是谈“宏”色变，原因在于 C 语言中的宏是非常危险的东东，但并不是所有语言都像 C 这样，例如对于古老的语言 Lisp 来说，宏就是就是一个非常强大的好帮手。

那话说回来，在 Rust 中宏到底是好是坏呢？本章将带你揭开它的神秘面纱。

事实上，我们虽然没有见过宏，但是已经多次用过它，例如在全书的第一个例子中就用到了：`println!("你好，世界")`，这里 `println!` 就是一个最常用的宏，可以看到它和函数最大的区别是：它在调用时多了一个 `!`，除此之外还有 `vec!` 、`assert_eq!` 都是相当常用的，可以说**宏在 Rust 中无处不在**。

细心的读者可能会注意到 `println!` 后面跟着的是 `()`，而 `vec!` 后面跟着的是 `[]`，这是因为宏的参数可以使用 `()`、`[]` 以及 `{}`:
```rust
fn main() {
    println!("aaaa");
    println!["aaaa"];
    println!{"aaaa"}
}
```

虽然三种使用形式皆可，但是 Rust 内置的宏都有自己约定俗成的使用方式，例如 `vec![...]`、`assert_eq!(...)` 等。

在 Rust 中宏分为两大类：声明式宏 `macro_rules!` 和三种过程宏( *procedural macros* ):
- `#[derive]`，在之前多次见到的派生宏，可以为目标结构体或枚举派生指定的代码，例如 `Debug` 特征
- 属性宏(Attribute-like macro)，用于为目标添加自定义的属性
- 函数宏(Function-like macro)，看上去就像是函数调用

如果感觉难以理解，也不必担心，接下来我们将逐个看看它们的庐山真面目，在次之前，先来看下为何需要宏，特别是 Rust 的函数明明已经很强大了。

## 宏和函数的区别
宏和函数的区别并不少，而且对于宏擅长的领域，函数其实是有些无能为力的。

#### 元编程
从根本上来说，宏是通过一种代码来生成另一种代码，如果大家熟悉元编程，就会发现两者的共同点。

在[附录 D 中](https://course.rs/appendix/derive.html)讲到的 `derive` 属性，就会自动为结构体派生出相应特征所需的代码，例如 `#[derive(Debug)]`，还有熟悉的 `println!` 和 `vec!`，所有的这些宏都会展开成相应的代码，且很可能是长得多的代码。

总之，元编程可以帮我们减少所需编写的代码，也可以一定程度上减少维护的成本，虽然函数复用也有类似的作用，但是宏依然拥有自己独特的优势。

#### 可变参数
Rust 的函数签名是固定的：定义了两个参数，就必须传入两个参数，多一个少一个都不行，对于从 JS/TS 过来的同学，这一点其实是有些恼人的。

而宏就可以拥有可变数量的参数，例如可以调用一个参数的 `println!("hello")`，也可以调用两个参数的 `println!("hello {}", name)`。

#### 宏展开
由于宏会被展开成其它代码，且这个展开过程是发生在编译器对代码进行解释之前。因此，宏可以为指定的类型实现某个特征：先将宏展开成实现特征的代码后，再被编译。

而函数就做不到这一点，因为它直到运行时才能被调用，而特征需要在编译期被实现。

#### 宏的缺点
相对函数来说，由于宏是基于代码再展开成代码，因此实现相比函数来说会更加复杂，再加上宏的语法更为复杂，最终导致定义宏的代码相当地难读，也难以理解和维护。

## 声明式宏 `macro_rules!`
在 Rust 中使用最广的就是声明式宏，它们也有一些其它的称呼，例如示例宏( macros by example )、`macro_rules!` 或干脆直接称呼为**宏**。

声明式宏允许我们写出类似 `match` 的代码。`match` 表达式是一个控制结构，其接收一个表达式，然后将表达式的结果与多个模式进行匹配，一旦匹配了某个模式，则该模式相关联的代码将被执行:
```rust
match target {
    模式1 => 表达式1,
    模式2 => {
        语句1;
        语句2;
        表达式2
    },
    _ => 表达式3
}
```

而**宏也是将一个值跟对应的模式进行匹配，且该模式会与特定的代码相关联**。但是与 `match` 不同的是，**宏里的值是一段 Rust 源代码**(字面量)，模式用于跟这段源代码的结构相比较，一旦匹配，传入宏的那段源代码将被模式关联的代码所替换，最终实现宏展开。值得注意的是，**所有的这些都是在编译期发生，并没有运行期的性能损耗**。

#### 简化版的 vec!
在[动态数组 Vector 章节](https://course.rs/basic/collections/vector.html#vec)中，我们学习了使用 `vec!` 来便捷的初始化一个动态数组:
```rust
let v: Vec<u32> = vec![1, 2, 3];
```

最重要的是，通过 `vec!` 创建的动态数组支持任何元素类型，也并没有限制数组的长度，如果使用函数，我们是无法做到这一点的。

好在我们有 `macro_rules!`，来看看该如何使用它来实现 `vec!`，以下是一个简化实现：
```rust
#[macro_export]
macro_rules! vec {
    ( $( $x:expr ),* ) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}
```

简化实现版本？这也太难了吧！！只能说，欢迎来到宏的世界，在这里你能见到优雅 Rust 的另一面:) 标准库中的 `vec!` 还包含了预分配内存空间的代码，如果引入进来，那大家将更难以接受。

`#[macro_export]` 注释将宏进行了导出，这样其它的包就可以将该宏引入到当前作用域中，然后才能使用。可能有同学会提问：我们在使用标准库 `vec!` 时也没有引入宏啊，那是因为 Rust 已经通过 [`std::prelude`](https://course.rs/appendix/prelude.html) 的方式为我们自动引入了。

紧接着，就使用 `macro_rules!` 进行了宏定义，需要注意的是宏的名称是 `vec`，而不是 `vec!`，后者的感叹号只在调用时才需要。

`vec` 的定义结构跟 `match` 表达式很像，但这里我们只有一个分支，其中包含一个模式 `( $( $x:expr ),* )`，跟模式相关联的代码就在 `=>` 之后。一旦模式成功匹配，那这段相关联的代码就会替换传入的源代码。

由于 `vec` 宏只有一个模式，因此它只能匹配一种源代码，其它类型的都将导致报错，而更复杂的宏往往会拥有更多的分支。

虽然宏和 `match` 都称之为模式，但是前者跟[后者](https://course.rs/basic/match-pattern/all-patterns.html)的模式规则是不同的。如果大家想要更深入的了解宏的模式，可以查看[这里](https://doc.rust-lang.org/reference/macros-by-example.html)。

#### 模式解析
而现在，我们先来简单讲解下 `( $( $x:expr ),* )` 的含义。

首先，我们使用圆括号 `()` 将整个宏模式包裹其中。紧随其后的是 `$()`，跟括号中模式相匹配的值(传入的 Rust 源代码)会被捕获，然后用于代码替换。在这里，模式 `$x:expr` 会匹配任何 Rust 表达式并给予该模式一个名称：`$x`。

`$()` 之后的逗号说明在 `$()` 所匹配的代码的后面会有一个可选的逗号分隔符，紧随逗号之后的 `*` 说明 `*` 之前的模式会被匹配一次或任意多次(类似正则表达式)。

当我们使用 `vec![1, 2, 3]` 来调用该宏时，`$x` 模式将被匹配三次，分别是 `1`、`2`、`3`。为了帮助大家巩固，我们再来一起过一下：

1. `$()` 中包含的是模式 `$x:expr`，该模式中的 `expr` 表示会匹配任何 Rust 表达式，并给予该模式一个名称 `$x`
2. 因此 `$x` 模式可以跟整数 `1` 进行匹配，也可以跟字符串 "hello" 进行匹配: `vec!["hello", "world"]`
3. `$()` 之后的逗号，意味着`1` 和 `2` 之间可以使用逗号进行分割，也意味着 `3` 既可以没有逗号，也可以有逗号：`vec![1, 2, 3,]`
4. `*` 说明之前的模式可以出现一次也可以任意次，这里出现了三次

接下来，我们再来看看与模式相关联、在 `=>` 之后的代码：
```rust
{
    {
        let mut temp_vec = Vec::new();
        $(
            temp_vec.push($x);
        )*
        temp_vec
    }
};
```

这里就比较好理解了，`$()` 中的 `temp_vec.push()` 将根据模式匹配的次数生成对应的代码，当调用 `vec![1, 2, 3]` 时，下面这段生成的代码将替代传入的源代码，也就是替代 `vec![1, 2, 3]` :
```rust
{
    let mut temp_vec = Vec::new();
    temp_vec.push(1);
    temp_vec.push(2);
    temp_vec.push(3);
    temp_vec
}
```

如果是 `let v = vec![1, 2, 3]`，那生成的代码最后返回的值 `temp_vec` 将被赋予给变量 `v`，等同于 :
```rust
let v = {
    let mut temp_vec = Vec::new();
    temp_vec.push(1);
    temp_vec.push(2);
    temp_vec.push(3);
    temp_vec
}
```

至此，我们定义了一个宏，它可以接受任意类型和数量的参数，并且理解了其语法的含义。

#### 未来将被替代的 `macro_rules`
对于 `macro_rules` 来说，它是存在一些问题的，因此，Rust 计划在未来使用新的声明式宏来替换它：工作方式类似，但是解决了目前存在的一些问题，在那之后，`macro_rules` 将变为 `deprecated` 状态。

由于绝大多数 Rust 开发者都是宏的用户而不是编写者，因此在这里我们不会对 `macro_rules` 进行更深入的学习，如果大家感兴趣，可以看看这本书 [ “The Little Book of Rust Macros”](https://veykril.github.io/tlborm/)。

## 用过程宏为属性标记生成代码
第二种常用的宏就是[*过程宏*]( *procedural macros* )，从形式上来看，过程宏跟函数较为相像，但过程宏是使用源代码作为输入参数，基于代码进行一系列操作后，再输出一段全新的代码。**注意，过程宏输出的代码并不会替换之前的代码，这一点与声明宏有很大的不同！**

至于前文提到的过程宏的三种类型(自定义 `derive`、属性宏、函数宏)，它们的工作方式都是类似的。

当**创建过程宏**时，它的定义必须要放入一个独立的包中，且包的类型也是特殊的，这么做的原因相当复杂，大家只要知道这种限制在未来可能会有所改变即可。

假设我们要创建一个 `derive` 类型的过程宏：
```rust
use proc_macro;

#[proc_macro_derive(HelloMacro)]
pub fn some_name(input: TokenStream) -> TokenStream {
}
```

用于定义过程宏的函数 `some_name` 使用 `TokenStream` 作为输入参数，并且返回的也是同一个类型。`TokenStream` 是在 `proc_macro` 包中定义的，顾名思义，它代表了一个 `Token` 序列。

该宏所标记的代码块会被解析为一个树型结构：树上的节点就是一个 `Token`，以此类推，`some_name` 返回的 `TokenStream` 也是一个树形结构，基于它，就可以生成最终的展开代码。

在理解了过程宏的基本定义后，我们再来看看该如何创建三种类型的过程宏，首先，从大家最熟悉的 `derive` 开始。

## 自定义 `derive` 过程宏
假设我们有一个特征 `HelloMacro`，现在有两种方式让用户使用它：

- 为每个类型手动实现该特征，就像之前[特征章节](https://course.rs/basic/trait/trait.html#为类型实现特征)所做的
- 使用过程宏来统一实现该特征，这样用户只需要对类型进行标记即可：`#[derive(HelloMacro)]`

以上两种方式并没有孰优孰劣，主要在于不同的类型是否可以使用同样的默认特征实现，如果可以，那过程宏的方式可以帮我们减少很多代码实现: 
```rust
use hello_macro::HelloMacro;
use hello_macro_derive::HelloMacro;

#[derive(HelloMacro)]
struct Sunfei;

#[derive(HelloMacro)]
struct Sunface;

fn main() {
    Sunfei::hello_macro();
    Sunface::hello_macro();
}
```

简单吗？简单！不过为了实现这段代码展示的功能，我们还需要创建相应的过程宏才行。 首先，创建一个新的 `lib` 类型的包(工程):
```shell
$ cargo new hello_macro --lib
```

接下来，定义宏所需的 `HelloMacro` 特征和其关联函数:

## 额外的学习资料
https://www.reddit.com/r/rust/comments/s3mm8m/macro_hygiene/




https://www.reddit.com/r/rust/comments/rjumsg/any_good_resources_for_learning_rust_macros/

https://www.reddit.com/r/rust/comments/roaofg/procedural_macros_parsing_custom_syntax/