Rust宏：教程与示例

原文标题：Macros in Rust: A tutorial with examples

原文链接：https://blog.logrocket.com/macros-in-rust-a-tutorial-with-examples/

公众号： Rust 碎碎念

翻译 by： Praying

Rust 中的过程宏

过程宏（Procedural macros）^[1]是一种更为高级的宏。过程宏能够扩展 Rust 的现有语法。它接收任意输入并产生有效的 Rust 代码。

过程宏接收一个TokenStream作为参数并返回另一个TokenStream。过程宏对输入的TokenStream进行操作并产生一个输出。有三种类型的过程宏：

1. 属性式宏（Attribute-like macros）
2. 继承宏（Derive macros）
3. 函数式宏（Function-like macros）

接下来我们将会对它们进行详细讨论。

属性式宏

属性式宏能够让你创建一个自定义的属性，该属性将其自身关联一个项（item），并允许对该项进行操作。它也可以接收参数。

#[some_attribute_macro(some_argument)]
fn perform_task(){
// some code
}

在上面的代码中，some_attribute_macros是一个属性宏，它对函数perform_task进行操作。

为了编写一个属性式宏，我们先用cargo new macro-demo --lib来创建一个项目。创建完成后，修改Cargo.toml来通知 cargo，该项目将会创建过程宏。

# Cargo.toml
[lib]
proc-macro = true

现在，我们可以开始过程宏学习之旅了。

过程宏是公开的函数，接收TokenStream作为参数并返回另一个TokenStream。要想写一个过程宏，我们需要先实现能够解析TokenStream的解析器。Rust 社区已经有了很好的 crate——syn^[2]，用于解析TokenStream。

syn提供了一个现成的 Rust 语法解析器能够用于解析TokenStream。你可以通过组合syn提供的底层解析器来解析你自己的语法、

把syn和quote^[3]添加到Cargo.toml。

# Cargo.toml
[dependencies]
syn = {version="1.0.57",features=["full","fold"]}
quote = "1.0.8"

现在我们可以使用proc_macro在lib.rs中写一个属性式宏，proc_macro是编译器提供的用于写过程宏的一个 crate。对于一个过程宏 crate，除了过程宏外，不能导出其他任何东西，crate 中定义的过程宏不能在 crate 自身中使用。

// lib.rs
extern crate proc_macro;
use proc_macro::{TokenStream};
use quote::{quote};

// using proc_macro_attribute to declare an attribute like procedural macro

#[proc_macro_attribute]

// _metadata is argument provided to macro call and _input is code to which attribute like macro attaches

pub fn my_custom_attribute(_metadata: TokenStream, _input: TokenStream) -> TokenStream {

// returing a simple TokenStream for Struct

TokenStream::from(quote!{struct H{}})

}

为了测试我们添加的宏，我们需要创建一个测试。创建一个名为tests的文件夹然后在该文件夹添加文件attribute_macro.rs。在这个文件中，我们可以测试我们的属性式宏。

// tests/attribute_macro.rs

use macro_demo::*;

// macro converts struct S to struct H

#[my_custom_attribute]

struct S{}

#[test]

fn test_macro(){

// due to macro we have struct H in scope

let demo=H{};

}

使用命令cargo test来运行上面的测试。

现在，我们理解了过程宏的基本使用，让我们用syn来对TokenStream进行一些高级操作和解析。

为了理解syn是如何用来解析和操作的，让我们来看syn Github 仓库^[4]上的一个示例。这个示例创建了一个 Rust 宏，这个宏可以追踪变量值的变化。

首先，我们需要去验证，我们的宏是如何操作与其所关联的代码的

#[trace_vars(a)]
fn do_something(){
  let a=9;
  a=6;
  a=0;
}

trace_vars宏获取它所要追踪的变量名，然后每当输入变量（也就是a）的值发生变化时注入一条打印语句。这样它就可以追踪输入变量的值了。

首先，解析属性式宏所关联的代码。syn提供了一个适用于 Rust 函数语法的内置解析器。ItemFn将会解析函数，并且如果语法无效，它会抛出一个错误。

#[proc_macro_attribute]
pub fn trace_vars(_metadata: TokenStream, input: TokenStream) -> TokenStream {
// parsing rust function to easy to use struct
    let input_fn = parse_macro_input!(input as ItemFn);
    TokenStream::from(quote!{fn dummy(){}})
}

现在我们已经解析了input，让我们开始转移到metadata。对于metadata，没有适用的内置解析器，所以我们必须自己使用syn的parse模块写一个解析器。

#[trace_vars(a,c,b)] // we need to parse a "," seperated list of tokens
// code

要想syn能够工作，我们需要实现syn提供的Parse trait。Punctuated用于创建一个由,分割Indent的vector。

struct Args{
    vars:HashSet<Ident>
}

impl Parse for Args{

fn parse(input: ParseStream) -> Result<Self> {

// parses a,b,c, or a,b,c where a,b and c are Indent

let vars = Punctuated::<Ident, Token![,]>::parse_terminated(input)?;

Ok(Args {

vars: vars.into_iter().collect(),

})

}

}

一旦我们实现Parse trait，我们就可以使用parse_macro_input宏来解析metadata。

#[proc_macro_attribute]
pub fn trace_vars(metadata: TokenStream, input: TokenStream) -> TokenStream {
    let input_fn = parse_macro_input!(input as ItemFn);
    // using newly created struct Args
    let args= parse_macro_input!(metadata as Args);
    TokenStream::from(quote!{fn dummy(){}})
}

现在，我们准备修改input_fn以便于在当变量值变化时添加println!。为了完成这项修改，我们需要过滤出有复制语句的代码，并在那行代码之后插入一个 print 语句。

impl Args {
    fn should_print_expr(&self, e: &Expr) -> bool {
        match *e {
            Expr::Path(ref e) => {
 // variable shouldn't start wiht ::
                if e.path.leading_colon.is_some() {
                    false
// should be a single variable like `x=8` not n::x=0
                } else if e.path.segments.len() != 1 {
                    false
                } else {
// get the first part
                    let first = e.path.segments.first().unwrap();
// check if the variable name is in the Args.vars hashset
                    self.vars.contains(&first.ident) && first.arguments.is_empty()
                }
            }
            _ => false,
        }
    }

// used for checking if to print let i=0 etc or not

fn should_print_pat(&self, p: &Pat) -> bool {

match p {

// check if variable name is present in set

Pat::Ident(ref p) => self.vars.contains(&p.ident),

_ => false,

}

}

// manipulate tree to insert print statement

fn assign_and_print(&mut self, left: Expr, op: &dyn ToTokens, right: Expr) -> Expr {

// recurive call on right of the assigment statement

let right = fold::fold_expr(self, right);

// returning manipulated sub-tree

parse_quote!({

#left #op #right;

println!(concat!(stringify!(#left), " = {:?}"), #left);

})

}

// manipulating let statement

fn let_and_print(&mut self, local: Local) -> Stmt {

let Local { pat, init, .. } = local;

let init = self.fold_expr(*init.unwrap().1);

// get the variable name of assigned variable

let ident = match pat {

Pat::Ident(ref p) => &p.ident,

_ => unreachable!(),

};

// new sub tree

parse_quote! {

let #pat = {

#[allow(unused_mut)]

let #pat = #init;

println!(concat!(stringify!(#ident), " = {:?}"), #ident);

#ident

};

}

}

}

在上面的示例中，quote宏用于模板化和生成 Rust 代码。#用于注入变量的值。

现在，我们将会在input_fn上进行 DFS，并插入 print 语句。syn提供了一个Foldtrait 可以用来对任意Item实现 DFS。我们只需要修改与我们想要操作的 token 类型所对应的 trait 方法。

impl Fold for Args {
    fn fold_expr(&mut self, e: Expr) -> Expr {
        match e {
// for changing assignment like a=5
            Expr::Assign(e) => {
// check should print
                if self.should_print_expr(&e.left) {
                    self.assign_and_print(*e.left, &e.eq_token, *e.right)
                } else {
// continue with default travesal using default methods
                    Expr::Assign(fold::fold_expr_assign(self, e))
                }
            }
// for changing assigment and operation like a+=1
            Expr::AssignOp(e) => {
// check should print
                if self.should_print_expr(&e.left) {
                    self.assign_and_print(*e.left, &e.op, *e.right)
                } else {
// continue with default behaviour
                    Expr::AssignOp(fold::fold_expr_assign_op(self, e))
                }
            }
// continue with default behaviour for rest of expressions
            _ => fold::fold_expr(self, e),
        }
    }

// for let statements like let d=9

fn fold_stmt(&mut self, s: Stmt) -> Stmt {

match s {

Stmt::Local(s) => {

if s.init.is_some() && self.should_print_pat(&s.pat) {

self.let_and_print(s)

} else {

Stmt::Local(fold::fold_local(self, s))

}

}

_ => fold::fold_stmt(self, s),

}

}

}

Fold trait 用于对一个Item进行 DFS。它使得你能够针对不同的 token 类型采取不同的行为。

现在我们可以使用fold_item_fn在我们解析的代码中注入 print 语句。

#[proc_macro_attribute]
pub fn trace_var(args: TokenStream, input: TokenStream) -> TokenStream {
// parse the input
    let input = parse_macro_input!(input as ItemFn);
// parse the arguments
    let mut args = parse_macro_input!(args as Args);
// create the ouput
    let output = args.fold_item_fn(input);
// return the TokenStream
    TokenStream::from(quote!(#output))
}

这个代码示例来自于syn 示例仓库^[5]，该仓库也是关于过程宏的一个非常好的学习资源。

自定义继承宏

Rust 中的自定义继承宏能够对 trait 进行自动实现。这些宏通过使用#[derive(Trait)]自动实现 trait。

syn对derive宏有很好的支持。

#[derive(Trait)]
struct MyStruct{}

要想在 Rust 中写一个自定义继承宏，我们可以使用DeriveInput来解析继承宏的输入。我们还将使用proc_macro_derive宏来定义一个自定义继承宏。

#[proc_macro_derive(Trait)]
pub fn derive_trait(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

let name = input.ident;

    let expanded = quote! {

impl Trait for #name {

fn print(&self) -> usize {

println!("{}","hello from #name")

}

}

};

proc_macro::TokenStream::from(expanded)

}

使用syn可以编写更为高级的过程宏，请查阅syn仓库中的这个示例^[6]。

函数式宏

函数式宏类似于声明式宏，因为他们都通过宏调用操作符!来执行，并且看起来都像是函数调用。它们都作用于圆括号里的代码。

下面是如何在 Rust 中写一个函数式宏：

#[proc_macro]
pub fn a_proc_macro(_input: TokenStream) -> TokenStream {
    TokenStream::from(quote!(
            fn anwser()->i32{
                5
            }
))
}

函数式宏在编译期而非在运行时执行。它们可以在 Rust 代码的任何地方被使用。函数式宏同样也接收一个TokenStream并返回一个TokenStream。

使用过程宏的优势包括：

• 使用span获得更好的错误处理
• 更好的控制输出
• 社区已有syn和quote两个 crate
• 比声明式宏更为强大

总结

在这篇 Rust 教程中，我们涵盖了 Rust 中关于宏的基本内容，声明式宏和过程宏的定义，以及如果使用各种语法和社区的 crate 来编写这两种类型的宏。我们还总结了每种类型的 Rust 宏所具有优势。

参考资料