[易学易懂系列|rustlang语言|零基础|快速入门|（22）|宏Macro]

[易学易懂系列|rustlang语言|零基础|快速入门|（22）|宏Macro]

实用知识

宏Macro

我们今天来讲讲Rust中强大的宏Macro。

Rust的宏macro是实现元编程的强大工具。

宏主要作用为：

1.减少重复代码。

2.编写DSL(Domain-specific languages。

3.可变参数接口定义。

在Rust主要分两种宏：

1. 声明式宏declarative macros （一般用macro_rules!定义）

2. 过程式宏 procedural macros，像一个过程函数，更易懂。它主要功能是把属性代码作为输入，作用于现有代码，并生成新的代码，从而实现特定功能。过程式宏又分为三种：

   2.1自定义派生宏custom derive，主要用于给结构体或枚举增加派生属性#[derive]。

   2.2自定义属性(属性风格宏Attribute-like)，主要用于给任意元素增加属性。

   2.3 函数宏(函数风格宏Function-like)，主要用于AST抽象语法树的操作。

这里简单说明 一下，如果要理解宏，就要简单了解下编译原理，一般来说现代化的编译器的编译过程如下 ：

编译过程

分词（词条流）→解析（抽象语法树）→简化（高级中间语言）→简化（中级中间语言）→转译（LLVM中间语言）→优化（机器码）

简单来说，编译器就像一个翻译者，它把程序代码，一步步翻译成机器码，让机器能理解并执行人类的代码。

先来看看声明式宏，macro_rules! 是使用递归和模式匹配、字符串替换的函数式风格定义宏。

我们来看看简单的宏定义：

// 宏名字为：`say_hello`.
macro_rules! say_hello {
    // `()` 这里括号里没有任何表达式，表示这个宏不用接受任何参数.
    () => {
        // 宏将把上面的括号（）内的表达式展开到这个大括号{}中的代码。
        println!("Hello!");
    };
}

fn main() {
    // 调用这个宏，将直接把这个宏展开为代码： `println!("Hello");`
    say_hello!()
}

我们再来看看稍微有点复杂的宏定义：

macro_rules! create_function {
    // 这个宏定义有两个参数：ident为标识符，主要用来标识变量或函数，表明宏展开为变量或函数;
    //而$func_name则为宏代码中代码展开的参数名，这里为函数名.
    ($func_name:ident) => {
        fn $func_name() {
            //这里的宏 `stringify!`直接把函数名字转换成字符串。
            println!("You called {:?}()", stringify!($func_name));
        }
    };
}

macro_rules! print_result {
    //这个宏把一个表达式，并把表达式的字符串和表达式结果一起打印出来。 
    //而标识符expr,主要用来标识表达式。
    ($expression:expr) => {
        // `stringify!` 宏将把表达式转换成字符串形式
        println!("{:?} = {:?}", stringify!($expression), $expression);
    };
}

fn main() {
    // 用上面的宏create_function!分别创建foo和bar函数
    create_function!(foo);
    create_function!(bar);

    foo();//调用foo函数，即调用代码：println!("You called {:?}()", stringify!(foo));
    bar();/调用foo函数，即调用代码：println!("You called {:?}()", stringify!(bar));
    
//用上面宏print_result!，将把代码展开为：
//println!("{:?} = {:?}", stringify!(1u32 + 1), 1u32 + 1);
    print_result!(1u32 + 1);

    // 同样，将大括号的代码当成表达式参数传给上面的宏print_result!
    print_result!({
        let x = 1u32;

        x * x + 2 * x - 1
    });
}

运行上面的代码，打印结果为：

You called "foo"()
You called "bar"()
"1u32 + 1" = 2
"{ let x = 1u32; x * x + 2 * x - 1 }" = 2

我们从上面的代码来一一分析，一般来说宏定义用：macro_rules! 开头，表明这是个宏。

基本形式为：() => { };

其中小括号为宏定义的参数：主要用来定义宏的参数，其中参数有个标识符，主要用来表明宏定义的表达式展开的参数类型。

有以下标识符：

• item，语言项，比如模块、声明、函数定义、类型定义、结构体定义、impl实现等。

  block，代码块，由花括号限定的代码；

  stmt，语句，一般是指以分号结尾的代码；

  expr，表达式，会生成具体的值；

  pat，模式；

  ty，类型；

  ident，标识符；

  path，路径，比如foo、std::iter等；

  meta，元信息，包含在#[...]或者#![...]属性内的信息；

  tt，TokenTree的缩写，词条树；

  vis，可见性，比如pub；

  lifetime，生命周期参数。

代码重载

宏可以像模式匹配一样，可以根据参数不同，匹配不同的宏定义代码，如下例子：

/ `test!` 宏主要用来比较 `$left` 和 `$right`
// 它会根据你调用时的参数自动匹配不一样的代码:
macro_rules! test {
    // 参数之间不一定要用逗号隔开
    // 任何形式的模板代码都可以
    ($left:expr; and $right:expr) => {
        println!("{:?} and {:?} is {:?}",
                 stringify!($left),
                 stringify!($right),
                 $left && $right)
    };
    // 每个left参数必须以分号结尾
    ($left:expr; or $right:expr) => {
        println!("{:?} or {:?} is {:?}",
                 stringify!($left),
                 stringify!($right),
                 $left || $right)
    };
}

fn main() {
    test!(1i32 + 1 == 2i32; and 2i32 * 2 == 4i32);
    test!(true; or false);
}

运行上面代码，结果为：

"1i32 + 1 == 2i32" and "2i32 * 2 == 4i32" is true
"true" or "false" is true

重复调用

宏定义可以用加号+来表示，可以传入一个或多个参数；同样，也可以星号*来表示可以传入零个或多个参数。

我们看看简单例子：

// `min!` 宏主要用来求多个表达式结果中的最小值.
macro_rules! find_min {
    //一个参数的情况:
    ($x:expr) => ($x);
    // 参数`$x` 和至少一个参数 `$y,`的情况
    ($x:expr, $($y:expr),+) => (
        // 调用标准库中的最小值求值函数 ，并且让`find_min!`作用于参数  `$y`和更多其它参数
        std::cmp::min($x, find_min!($($y),+))
    )
}

fn main() {
    println!("{}", find_min!(1u32));
    println!("{}", find_min!(1u32 + 2, 2u32));
    println!("{}", find_min!(5u32, 2u32 * 3, 4u32));
}

运行结果：

1
2
4

当然，宏最大的用法，就是DSL（Domain Specific Languages），即领域特定语言。我们来看看简单例子：

macro_rules! calculate {
    (eval $e:expr) => {{
        {
            let val: usize = $e; // 强制类型转换成integer
            println!("{} = {}", stringify!{$e}, val);//打印结果
        }
    }};
}

fn main() {
    calculate! {
        eval 1 + 2 // 还好 `eval`不是Rust的关键词！
    }

    calculate! {
        eval (1 + 2) * (4 / 4)
    }
}

结果为：

1 + 2 = 3
(1 + 2) * (4 / 4) = 3

可变参数接口

很多时候，我们的接口可能要适应一个或多个参数的情况，也就是可变参数接口。那这样的宏又如何实现呢？我们来扩展下上面的宏，代码如下：

macro_rules! calculate {
    // The pattern for a single `eval`
    (eval $e:expr) => {{
        {
            let val: usize = $e; // Force types to be integers
            println!("{} = {}", stringify!{$e}, val);
        }
    }};

    // Decompose multiple `eval`s recursively
    (eval $e:expr, $(eval $es:expr),+) => {{
        calculate! { eval $e }
        calculate! { $(eval $es),+ }
    }};
}

fn main() {
    calculate! { // Look ma! Variadic `calculate!`!
        eval 1 + 2,
        eval 3 + 4,
        eval (2 * 3) + 1
    }
}

运行结果为：

1 + 2 = 3
3 + 4 = 7
(2 * 3) + 1 = 7

导入导出

#[macro_export]表示下面的宏定义对其他包也是可见的。#[macro_use]可以导入宏。

在宏定义中使用$crate，可以在被导出时，让编译器根据上下文推断包名，避免依赖问题。

我们再来看看过程宏，过程宏有三个：1.自定义派生宏custom derive 2.自定义属性 3.函数宏

1.自定义派生宏custom derive

所谓自定义derive属性，即可自动为结构体或枚举类型进行语法扩展。

我们来看看例子。

先用命令生成目录：test_derive_macro

cargo new test_derive_macro

新建一个lib.rs文件和目录tests，并创建一个test.rs文件，目录结构如下：

|-Cargo.toml
|-src
    |- lib.rs
|-tests
    |- test.rs

我们先更新Cargo.toml ，完整代码如下：

[package]
name = "test_derive_macro"
version = "0.1.0"
authors = ["gyc567 <gyc567@126.com>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
#设置lib的类型，这个一定要加上
[lib]
proc_macro = true
[dependencies]

test.rs的代码：

#[macro_use]
extern crate test_derive_macro;

#[derive(A)]
struct A;
#[test]
fn test_derive_a() {
    assert_eq!("hello from impl A".to_string(), A.a());
}

lib.rs代码：

extern crate proc_macro;
use self::proc_macro::TokenStream;

// 自定义派生属性
#[proc_macro_derive(A)]
pub fn derive(input: TokenStream) -> TokenStream {
    let _input = input.to_string();
    assert!(_input.contains("struct A;"));
    r#"
        impl A {
            fn a(&self) -> String{
               format!("hello from impl A")
           }
       }
   "#
    .parse()
    .unwrap()
}

我们在当前工程目录下运行：cargo test

显示测试通过 。

我们再来看看独立crate工程的例子（这个官方案例代码更全面）：

我们先用命令创建一个工程：hello_macro：

$ cargo new hello_macro --lib

我在当前工程下的src/lib.rs，定义一个公共特征，写入如下代码：

pub trait HelloMacro {
    fn hello_macro();
}

然后我们在当前工程目录创建另一个工程：hello_macro_derive，用如下命令：

$ cargo new hello_macro_derive --lib

修改在这个工程目录下文件：hello_macro_derive/Cargo.toml，主要增加 两个库syn和quote：

[lib]
proc-macro = true

[dependencies]
syn = "0.14.4"
quote = "0.6.3"

然后在文件：hello_macro_derive/src/lib.rs，写入如下代码：

extern crate proc_macro;

use crate::proc_macro::TokenStream;
use quote::quote;
use syn;

#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    // Construct a representation of Rust code as a syntax tree
    // that we can manipulate
    //从Rust代码构造出我们可以操作的语法树ast
    //文档：https://docs.rs/syn/0.14.4/syn/struct.DeriveInput.html
    let ast: syn::DeriveInput = syn::parse(input).unwrap();

    // 实现特征方法 Build the trait implementation
    impl_hello_macro(&ast)
}

// 实现特征方法 
fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
    let name = &ast.ident;
    let gen = quote! {//主要用来替换相关字符串，生成特定代码,
        //文档：https://docs.rs/quote/1.0.2/quote/
        impl HelloMacro for #name {
            fn hello_macro() {
                println!("Hello, Macro! My name is {}", stringify!(#name));
            }
        }
    };
    gen.into()
}

然后在目录hello_macro，运行命令：

cargo build

现在退出当前工程，当前工程的上一级目录下创建一个新工程，用命令：

cargo new pancakes

更新工程文件：pancakes/Cargo.toml文件下的依赖：

[dependencies]
hello_macro = { path = "../hello_macro" }
hello_macro_derive = { path = "../hello_macro/hello_macro_derive" }

更新main文件pancakes/src/main.rs,完整代码如下 ：

use hello_macro::HelloMacro;
use hello_macro_derive::HelloMacro;
// struct Pancakes;

#[derive(HelloMacro)]
struct Pancakes;

fn main() {
    Pancakes::hello_macro();
}

运行以上代码，正常情况下，会打印正确结果：

Hello, Macro! My name is Pancakes

我们再来看看后两种过程宏：

2.自定义属性(属性风格宏Attribute-like)

我们来看看代码例子，首先生成目录：

cargo new test_macro_attribute

然后到工程目录test_macro_attribute下直接生成lib crate目录，用命令：

cargo new my_macro --lib

生成的目录结构为：

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

然后我们在当着工程目录test_macro_attribute下的Cargo.toml文件，新增一行，如下：

[package]
name = "test_macro_attribute"
version = "0.1.0"
authors = ["gyc567 <gyc567@126.com>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
#新增一行，自定义宏lib依赖，这里就是：my_macro
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文件，新增一行宏的属性定义，完整代码:

[package]
name = "my_macro"
version = "0.1.0"
authors = ["gyc567 <gyc567@126.com>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[lib]
#新增一行，定义为宏的lib
proc-macro = true
[dependencies]

my_macro/src/lib.rs代码如下 ：

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")
}

保存好代码，直接用cargo run运行，结果为：

entering
args tokens: 3
input tokens: 7
exiting

我们再来看看函数宏，在my_macro/src/lib.rs新增如下代码：

#[proc_macro]
pub fn hw(input: TokenStream) -> TokenStream {
    // r#"println!("Hello, World!----in pm");"#.parse().unwrap()
    println!("in pm ----{:?}", input);

    TokenStream::new()
}

回到工程目录下的main.rs,新增一行调用代码：

#[macro_use]
extern crate my_macro;

#[log_entry_and_exit(hello, "world")]
fn this_will_be_destroyed() -> i32 {
    42
}
my_macro::hw!();//新增一行调用代码，注意，一定要放在这里才不报错
fn main() {
    dummy()
}

cargo run的最终运行结果为：

PS E:code ustProject est_macro_attribute> cargo run
Compiling test_macro_attribute v0.1.0 (E:code ustProject est_macro_attribute)
in pm ----TokenStream []
Finished dev [unoptimized + debuginfo] target(s) in 0.75s
Running targetdebug est_macro_attribute.exe
entering
args tokens: 3
input tokens: 7
exiting

我们发现，新增的代码：my_macro::hw!();

在编译的时候打印相关信息，说明它是在操作在编译期。

新增代码一定要写在main函数上面，否则报错：error[E0658]: procedural macros cannot be expanded to statements。见：https://stackoverflow.com/questions/54174361/cannot-call-a-function-like-procedural-macro-cannot-be-expanded-to-statements

这可能主要是因为现在的宏还在进化和完善中，还没有最终稳定下来。

所以，在Rust，宏是很强大的工具，但要用好，要好好深入掌握相关知识，才能写更好的代码。

本篇宏的专题，先到这里吧，以后有更好的案例，我会慢慢加入进来。

以上，希望对你有用。

如果遇到什么问题，欢迎加入：rust新手群，在这里我可以提供一些简单的帮助，加微信：360369487，注明：博客园+rust

参考文章：

https://doc.rust-lang.org/stable/rust-by-example/macros.html

https://danielkeep.github.io/tlborm/book/index.html

https://xr1s.me/2018/12/08/introduction-to-rust-proc-macro/

https://tinkering.xyz/introduction-to-proc-macros/

https://github.com/dtolnay/proc-macro-workshop#attribute-macro-sorted

https://blog.x5ff.xyz/blog/easy-programming-with-rust-macros/

https://stackoverflow.com/questions/52585719/how-do-i-create-a-proc-macro-attribute?noredirect=1

https://stackoverflow.com/questions/54174361/cannot-call-a-function-like-procedural-macro-cannot-be-expanded-to-statements