如何创建proc_macro_attribute？

Question

现在，proc_macros have been stabilized，怎么创造这样的东西？

从我所看到的，可以选择在#[proc_macro_attribute]上放置一个fn whatsitsname(attrs: TokenStream, code: TokenStream) -> TokenStream注释，但我该如何注册呢？如何添加自定义属性？

Answer 1

Rust编译器有一个相当完整的test suite。在寻找新引入功能的示例时，我经常从那里开始：

$ rg -c proc_macro_attribute
src/test/run-pass-fulldeps/auxiliary/proc_macro_def.rs:2
src/test/ui-fulldeps/auxiliary/attr_proc_macro.rs:1
[... 35 other matches ...]

这是一个完整的例子：

$ tree
.
├── Cargo.toml
├── my_macro
│   ├── Cargo.toml
│   ├── src
│   │   └── lib.rs
└── src
    └── main.rs

Cargo.toml

我们在宏定义包中添加依赖项。

[package]
name = "foo"
version = "0.1.0"
authors = ["An Devloper <[email protected]>"]

[dependencies]
my_macro = { path = "my_macro" }

SRC / main.rs

我们导入属性宏并将其添加到函数中。

#[macro_use]
extern crate my_macro;

#[log_entry_and_exit(hello, "world")]
fn this_will_be_destroyed() -> i32 {
    42
}

fn main() {
    dummy()
}

my_macro / Cargo.toml

我们将crate_type指定为proc_macro。

[package]
name = "my_macro"
version = "0.1.0"
authors = ["An Devloper <[email protected]>"]

[lib]
crate_type = ["proc-macro"]

my_macro / SRC / lib.rs

我们将#[proc_macro_attribute]添加到应该是宏的每个函数中。

extern crate proc_macro;

use proc_macro::*;

#[proc_macro_attribute]
pub fn log_entry_and_exit(args: TokenStream, input: TokenStream) -> TokenStream {
    let x = format!(r#"
        fn dummy() {{
            println!("entering");
            println!("args tokens: {{}}", {args});
            println!("input tokens: {{}}", {input});
            println!("exiting");
        }}
    "#,
            args = args.into_iter().count(),
            input = input.into_iter().count(),
    );

    x.parse().expect("Generated invalid tokens")
}

货运

entering
args tokens: 3
input tokens: 7
exiting

“硬”部分正在将TokenStream争论成有用的东西，然后输出同样有用的东西。板条箱syn和quote是这两项任务的当前黄金标准。 TokenStream以及macros chapter of The Rust Programming Language涵盖了与API documentation的交易。

还有#[proc_macro]，它具有以下形式的功能：

#[proc_macro]
pub fn the_name_of_the_macro(input: TokenStream) -> TokenStream

并可以作为the_name_of_the_macro!(...)调用。

Answer 2

如果我正确理解RFC 1566，你：

• 创建一个proc_macro类型的箱子，即它的Cargo.toml应该包含

  [lib]
  proc-macro = true

• 在该包中，创建使用#[proc_macro_attribute]注释的实现。函数式宏的#[proc_macro]和自定义派生的#[proc_macro_derive]工作方式相同，只是它们只有一个TokenStream参数。这些是在proc_macro箱中定义的。 第一个令牌流是属性中的参数，第二个是带注释的项的主体。
• 然后在想要使用宏的包中，只需依赖proc_macro crate并使用#[macro_use]属性（#[macro_use] extern crate ...）导入它。

那应该够了。

appendix in Book应扩展为提及#[proc_macro_derive]之外的其他proc宏类型。它不是一个错误。