过程宏（和自定义导出）

procedural-macros.md


commit 399708cf7bb12f593ad4bb403e94466d146e743e

在本书接下来的部分，你将看到 Rust 提供了一个叫做“导出（derive）”的机制来轻松的实现 trait。例如，

  1. #[derive(Debug)]
  2. struct Point {
  3.     x: i32,
  4.     y: i32,
  5. }

is a lot simpler than

  1. struct Point {
  2.     x: i32,
  3.     y: i32,
  4. }
  6. use std::fmt;
  8. impl fmt::Debug for Point {
  9.     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  10.         write!(f, "Point {{ x: {}, y: {} }}", self.x, self.y)
  11.     }
  12. }

Rust 包含很多可以导出的 trait，不过也允许定义你自己的 trait。我们可以通过一个叫做“过程宏”的 Rust 功能来实现这个效果。最终，过程宏将会允许 Rust 所有类型的高级元编程，不过现在只能自定义导出。

Hello World

首先需要做的就是为我们的项目新建一个 crate。

  1. $ cargo new --bin hello-world

我们想要实现的就是能够在导出的类型上调用hello_world()。就想这样：

  1. #[derive(HelloWorld)]
  2. struct Pancakes;
  4. fn main() {
  5.     Pancakes::hello_world();
  6. }

再来一些给力的输出，比如“Hello, World! 我叫煎饼（←_←）。”

继续并从用户的角度编写我们的宏。在src/main.rs中：

  1. #[macro_use]
  2. extern crate hello_world_derive;
  4. trait HelloWorld {
  5.     fn hello_world();
  6. }
  8. #[derive(HelloWorld)]
  9. struct FrenchToast;
  11. #[derive(HelloWorld)]
  12. struct Waffles;
  14. fn main() {
  15.     FrenchToast::hello_world();
  16.     Waffles::hello_world();
  17. }

好的。现在我们只需实际编写我们的过程宏。目前，过程宏需要位于它自己的 crate 中。最终这个限制会解除，不过现在是必须的。为此，有一个惯例是，对于一个叫foo的 crate，一个自定义的过程宏叫做foo-derive。让我们在hello-world项目中新建一个叫做hello-world-derive的 crate。

  1. $ cargo new hello-world-derive

为了确保hello-world crate 能够找到这个新创建的 crate 我们把它加入到项目 toml 文件中：

  1. [dependencies]
  2. hello-world-derive = { path = "hello-world-derive" }

这里是一个hello-world-derive crate 源码的例子：

  1. extern crate proc_macro;
  2. extern crate syn;
  3. #[macro_use]
  4. extern crate quote;
  6. use proc_macro::TokenStream;
  8. #[proc_macro_derive(HelloWorld)]
  9. pub fn hello_world(input: TokenStream) -> TokenStream {
  10.     // Construct a string representation of the type definition
  11.     let s = input.to_string();
  13.     // Parse the string representation
  14.     let ast = syn::parse_derive_input(&s).unwrap();
  16.     // Build the impl
  17.     let gen = impl_hello_world(&ast);
  19.     // Return the generated impl
  20.     gen.parse().unwrap()
  21. }

这里有很多内容。我们引入了两个新的 crate：syn和quote。你可能注意到了，input: TokenSteam直接就被转换成了一个String。这个字符串是我们要导出的HelloWorldRust 代码的字符串形式。现在，能对TokenStream做的唯一的事情就是把它转换为一个字符串。将来会有更丰富的 API。

所以我们真正需要做的是能够把 Rust 代码解析成有用的东西。这正是syn出场机会。syn是一个解析 Rust 代码的 crate。我们引入的另外一个 crate 是quote。它本质上与syn是成双成对的，因为它可以轻松的生成 Rust 代码。也可以自己编写这些功能，不过使用这些库会更加轻松。编写一个完整 Rust 代码解析器可不是一个简单的工作。

这些代码注释提供了我们总体策略的很好的解释。我们将为导出的类型提供一个String类型的 Rust 代码，用syn解析它，（使用quote）构建hello_world的实现，接着把它传递回给 Rust 编译器。

最后一个要点：这里有一些unwrap()，如果你要为过程宏提供一个错误，那么你需要panic!并提供错误信息。这里，我们从简实现。

好的，让我们编写impl_hello_world(&ast)。

  1. fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens {
  2.     let name = &ast.ident;
  3.     quote! {
  4.         impl HelloWorld for #name {
  5.             fn hello_world() {
  6.                 println!("Hello, World! My name is {}", stringify!(#name));
  7.             }
  8.         }
  9.     }
  10. }

这里就是quote出场的地方。ast参数是一个代表我们类型（可以是一个struct或enum）的结构体。查看文档。这里有一些有用的信息。我们可以通过ast.ident获取类型的信息。quote!宏允许我们编写想要返回的 Rust 代码并把它转换为Tokens。quote!让我们可以使用一些炫酷的模板机制；简单的使用#name，quote!就会把它替换为叫做name的变量。你甚至可以类似常规宏那样进行一些重复。请查看这些文档，这里有一些好的介绍。

应该就这些了。噢，对了，我们需要在hello-world-derive crate 的cargo.toml中添加syn和quote的依赖。

  1. [dependencies]
  2. syn = "0.10.5"
  3. quote = "0.3.10"

这样就 OK 了。尝试编译hello-world。

  1. error: the `#[proc_macro_derive]` attribute is only usable with crates of the `proc-macro` crate type
  2.  --> hello-world-derive/src/lib.rs:8:3
  3.   |
  4. 8 | #[proc_macro_derive(HelloWorld)]
  5.   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

好吧，看来我们需要把hello-world-derive crate 声明为proc-macro类型。怎么做呢？像这样：

  1. [lib]
  2. proc-macro = true

现在好了，编译hello-world。现在执行cargo run将会输出：

  1. Hello, World! My name is FrenchToast
  2. Hello, World! My name is Waffles

我们成功了！

自定义 attribute（Custom Attributes）

在一些情况下允许用户进行一些配置是合理的。例如，用户可能想要重载hello_world()方法打印出的名字的值。

这可以通过自定义 attribute 来实现：

  1. #[derive(HelloWorld)]
  2. #[HelloWorldName = "the best Pancakes"]
  3. struct Pancakes;
  5. fn main() {
  6.     Pancakes::hello_world();
  7. }

但是如果我们尝试编译它，编译器会返回一个错误：

  1. error: The attribute `HelloWorldName` is currently unknown to the compiler and may have meaning added to it in the future (see issue #29642)

编译器需要知道我们处理了这个 attribute 才能不返回错误。这可以通过在hello-world-derive crate 中对proc_macro_derive attribute 增加attributes来实现：

  1. #[proc_macro_derive(HelloWorld, attributes(HelloWorldName))]
  2. pub fn hello_world(input: TokenStream) -> TokenStream

可以一同样的方式指定多个 attribute。

引发错误

让我们假设我们并不希望在我们的自定义导出方法中接受枚举作为输入。

这个条件可以通过syn轻松的进行检查。不过我们如何告诉用户，我们并不接受枚举呢？在过程宏中报告错误的传统做法是 panic：

  1. fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens {
  2.     let name = &ast.ident;
  3.     // Check if derive(HelloWorld) was specified for a struct
  4.     if let syn::Body::Struct(_) = ast.body {
  5.         // Yes, this is a struct
  6.         quote! {
  7.             impl HelloWorld for #name {
  8.                 fn hello_world() {
  9.                     println!("Hello, World! My name is {}", stringify!(#name));
  10.                 }
  11.             }
  12.         }
  13.     } else {
  14.         //Nope. This is an Enum. We cannot handle these!
  15.        panic!("#[derive(HelloWorld)] is only defined for structs, not for enums!");
  16.     }
  17. }

如果用户尝试从一个枚举导出HelloWorld，他们会收到如下希望有帮助的错误信息：

  1. error: custom derive attribute panicked
  2.   --> src/main.rs
  3.    |
  4.    | #[derive(HelloWorld)]
  5.    |          ^^^^^^^^^^
  6.    |
  7.    = help: message: #[derive(HelloWorld)] is only defined for structs, not for enums!