[易学易懂系列|rustlang语言|零基础|快速入门|（22）|宏Macro]
[易学易懂系列|rustlang语言|零基础|快速入门|（22）|宏Macro]
实用知识
宏Macro
我们今天来讲讲Rust中强大的宏Macro。
Rust的宏macro是实现元编程的强大工具。
宏主要作用为：
1.减少重复代码。
2.编写DSL(Domain-specific languages。
3.可变参数接口定义。
在Rust主要分两种宏：
-
声明式宏declarative macros （一般用
macro_rules!定义） -
过程式宏 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\rustProject\test_macro_attribute> cargo run
Compiling test_macro_attribute v0.1.0 (E:\code\rustProject\test_macro_attribute)
in pm ----TokenStream []
Finished dev [unoptimized + debuginfo] target(s) in 0.75s
Running target\debug\test_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
