rust日记: 写宏!

认识宏

宏是什么喵! 宏跟函数差在哪喵!

简单点说, 宏就是咱在编译时执行/展开的一段代码喵, 可以是添加, 也可以是删减(代码在自己写代码.jpg)! 泥可以很轻易的自定义何时生成,

何时不生成!

warning:

>

1. 本文章作者边学边写, 有错误请指出(>д<)

2. 本文章中包含大量小剧场, 烂梗, 口癖等等, 不喜欢的可以直接panic!() 或是找ds去其糟粕

展开细说

让我们认识一下rust中的三大宏吧!

  1. 函数宏(function-like-macro)

- 当成函数用的宏, 你的宏怎么写编译出来就长怎么样, 例如println!()

- 可以是声明宏也可以是过程宏

  1. 派生宏(derive-macro)

- 根据你写的结构体/enum/union生成动态代码的, 自动生成trait, 例如 #[derive(Debug)]

  1. 属性宏(attribute-macro)

- 可以完全控制代码流的, 例如 #[test]

手写宏!

tips: 派生宏与属性宏只能在Cargo.toml 中被标记成proc-macro 的库中编写(避免循环依赖喵)

>

记得在你的Cargo.toml 中添加这段代码

>

`toml

[lib]

proc-macro = true

`

声明宏

语法

咱首先认识一下macro_rules!, macro_rules 是用来声明一个宏的, 如下

macro_rules! macro_name {
    ($designator_name: ident) => {
        //your code
    };
}


在这个范例里面咱声明了一个叫做macro_name 的宏,元变量为designator_name , 捕获类型是一个ident , 诶说到捕获类型咱就来展开一下都有那些吧,

报菜名, 开始!

  • block 代码块
  • expr 表达式
  • ident 标识符
  • item 顶层声明(函数/ 结构体等等)
  • lifetime 生命周期标识符
  • literal 字面量
  • meta 属性
  • pat 模式
  • pat_param 也是模式,没搞清跟pat 差在哪(>д<)
  • path 路径
  • stmt 语句
  • tt token tree (可以暂时理解为任意代码)
  • ty 类型
  • vis 可见性

看得懂吗? 看不懂吧, 来个实例!

#[cfg(test)]
mod tests {
    macro_rules! create_fn {
        ($vis:vis, $fn_name:ident, $result_ty:ty , $block:block) => {
            $vis fn $fn_name() -> $result_ty $block
        };
    }

    create_fn!(,zc,i32,{325});

    #[test]
    fn test() {
        assert_eq!(zc(), 325)
    }
}


在这个案例中咱先创建了一个叫做create_fn 的宏, 参数为: 一个可见性, 一个标识符, 一个类型, 一个代码块,

所以咱就依次传入这些参数create_fn!(,zc,i32,{325}); , 宏展开后会变成

fn zc() -> i32 { 325 }


在后面的测试中咱直接调用了这个宏创建的函数zc() 他的输出就是325 , 测试通过(可喜可贺)

tips: meta 属性在接收的时候记得改成这样

>

`rust

macro_rules! meta {

(#[$meta:meta]) => {

//your code

};

}

`

诶¿ 什么, 泥居然问那println!() 怎么接收多个参数的¿ 好问题!

想要接收多个参数其实很简单的:> 用这三个运算符!

  • * 0 次或多次
  • + 至少1 次
  • ? 0 或 1 次

依旧来个范例

macro_rules! multiple_param {
    ($($lit:literal), *) => {{
        let s = String::new();
        s $( + $lit)*
    }};
}

#[test]
fn multiple() {
    let result = multiple_param!("qwq", "awa");
    assert_eq!(result, "qwqawa")
}


简单理解一下喵, $($lit:literal), * 这玩意是个迭代器, 用$()* 来迭代, 元素名就是$lit

传奇删减版本迭代器, 这tm是人我吃

卫生性(hygiene)

ok嗷, 这时候经常试错的小猫猫们就会问了: 鹿呀鹿呀, 窝写了这样一段代码

macro_rules! test {
    ($ident:ident) => {{
        let x = "local";
        let $ident = "external";
        x
    }};
}

fn test() {
    let result = test!(x);
    println!("{}", result);
}


宏展开以后会变成

fn test() {
    let result = {
        let x = "local";
        let x = "external";
        x
    }
    println!("{}", result)
}


这不是一眼shadow 了吗w(゚Д゚)w

那结果是什么呢? 结果是 local 呢, 多新鲜呀, 猜对的猫猫准许起飞奖励自己一下✔

那么为什么会这样呢? 很简单的喵, 咱rustc 在展开宏的时候会帮变量做标记, 像是一开始写在宏里面的x , 那就是纯纯正正的本地人,

至于那个$ident 进来的x 嘛, 臭外地的, 你自己玩去吧! 这也就是咱声明宏的卫生性!

这时候又有小猫猫问了: 窝一身反骨! 我要在宏里面用宏外面的变量! 说! 这办得到吗!¿

可以的可以的, 但是泥能有这种想法我也只能说泥是这个了👍, 但是这里有个硬性要求, 泥宏调用处要能看见这个变量

#[test]
fn six_seven() {
    let six = String::from("6");
    macro_rules! six_seven {
            () => {{
                let seven = "7";
                six + seven
            }};
        }

    let result = six_seven!();
    assert_eq!(result, "67")
}


6767676767 嘿嘿嘿

好的, 现在咱优秀的五字神人同学写了一个宏, 他非常希望让大家使用, 于是在他的宏上面写了这样一段代码

macro_rules! add_this_crate {
    () => { use crate::c2qwq; };
}

pub mod c2qwq {}


但是大家使用之后却无法找到c2qwq 这个mod !? 不要慌不要怕, 这是因为宏里面crate 路径指向的是泥的包, 而不是五字神人同学的包,

那么应该怎么办呢, 答案就是把我们的crate 变成$crate 这样路径指向的就是五字神人同学的包了!

macro_rules! add_this_crate {
    () => { use $crate::c2qwq; };
}

pub mod c2qwq {}


卫生性这一段很建议再去参考文献里面"宏的卫生性讲解" 那篇文章看看喵.

好了, 最简单的声明宏结束了, 让我们继续走起

过程宏

对的对的, 现在讲到过程宏了, 在咱文章的一开始有提到, 过程宏分三种, 这三种怎么声明呢¿ 请看

  1. 函数宏

`rust

#[proc_macro]

fn macro_name(_:TokenStream) -> TokenStream{

//your code

}

`

  1. 属性宏

`rust

#[proc_macro_attribute]

fn macro_name(_:TokenStream, _:TokenStream) -> TokenStream{

//your code

}

`

  1. 派生宏

`rust

#[proc_macro_derive(MacroName)]

fn fn_name(_:TokenStream) -> TokenStream{

//your code

}

`

那看到这里注意力惊人的小猫猫就会问了: 小鹿小鹿, 这个TokenStream 3个方法里面出现了7次, 参团率达到了惊人的233.33%

他是什么w (゚Д゚)w

不急不急, 让我们细说一下这个TokenStream

TokenStream

TokenStream 顾名思义, 他是一种流, 什么的流呢, 代码的流, 咱用proc_macro 举个例子喵

当泥在使用proc_macro 的时候是这样的

macro_name!(token);


诶¿ 这样一看是不是就眉清目秀了, 这不正是咱传入的代码吗!¿ 那剩下两个宏传入的TokenStream应该就看得懂了吧

#[macro_name()]
fn fn_name() {}


proc_macro_attribute 两个TokenStream 分别是宏后面的() 以及下方的item

#[derive(MacroName)]
struct StructName {}


proc_macro_derive() 的那一个TokenStream 就是咱的struct 或是enum 等等.

好的, 现在TokenStream 在咱面前的伪装已经如同无能的丈夫了, 咱可以开始使用他了.

quote 与 syn

在很久很久以前~ Rust 的宏有两座绕不开的大山~ 他们分别是: syn 负责处理TokenStream 的输入, 以及 quote 负责处理

TokenStream的生成,

现在就让我们走进这两座大山里面吧!

过程宏

好的, 现在已经有迫不及待的猫猫们向前冲锋了, 他们首先做了什么!¿

#[proc_macro]
pub fn write_in_macro(ts: TokenStream) -> TokenStream {
    let ident = syn::parse_macro_input!(ts as syn::Ident);
    let ident_name = ident.to_string();
    let r = quote::quote! {
       println!("ast ident is: {}", #ident_name);
    };
    r.into()
}


诶¿ 他们怎么倒地了, 让咱看看可爱的Ferris 说了什么吧: use of unresolved module or unlinked crate 哦天啊, 这两个其实不是官方的包,

记得引入哦, 好了, 没有时间为冲锋手们作哀了, 让我们看看这段代码什么意思吧!

首先, 咱先用syn::parse_macro_input!() 这个宏把传入的ts 给变成了一个syn::Ident 类型, 获得了一个Abstract Syntax Tree

(AST) ,紧接着咱把拿到的ast 给变成String了, 接下来咱用quote!() 宏创建了一个proc_macro2::TokenStream,

在这个宏里面咱引用了宏展开之外的变量, 需要加上# (#ident_name), 最后咱用了into() 把proc_macro2::TokenStream

变成了过程宏要的TokenStream.

好的, 宝宝巴士结束了, 现在向你走来的是大运(>д<)

属性宏

鹿疲惫的身躯已经被属性宏击败(otto音)了, 没有小剧场了, 现在迎面向泥创来的是一个计算方法耗时的宏

#[proc_macro_attribute]
pub fn print_time_cost(_args: TokenStream, item: TokenStream) -> TokenStream {
    // let _args = syn::parse_macro_input!(args as syn::Ident);
    let item = syn::parse_macro_input!(item as syn::ItemFn);
    let syn::ItemFn {
        attrs,
        vis,
        modifiers: _modifiers,
        sig,
        block,
    } = item;
    let fn_name = sig.ident.clone().to_string();
    let r = quote::quote! {
        #(#attrs)*
        #vis #sig {
            let __start = ::std::time::Instant::now();
            let __r = (move ||{
                #block
            })();
            ::std::println!("fn \"{}\" cost : {} ms",#fn_name, __start.elapsed().as_millis());
            __r
        }
    };
    r.into()
}


好的, 看完这段代码很多小猫猫应该已经发出尖锐的爆鸣声重伤倒地了(戳一戳), 诶¿ 他们的代码怎么红红的`在此作用域内找不到类型

ItemFn [E0412]` 好的喵, 还活着的勇士们记得把syn 的features 改成full 哦.

因为这个宏里面不会用到args 所以咱就先把他给忽略了喵, 第一行代码咱先把ts 变成了一个syn::Item 对象,

有了这个包装对象咱就可以取出:

  • attrs 属性们
  • vis 可见性
  • modifiers 修饰符
  • sig 签名
  • block 代码块

之后咱把签名中的函数名给取出复制备用了(let fn_name = sig.ident.clone().to_string();)

接下来是重头戏了喵! 把你们的耳朵竖起来!

在这段quote! 宏中咱先用传奇删减版iter 把所有属性摆在最上面#(#attrs)*, 接下来是函数的声明, 咱也是把可见性跟签名放了上去

#vis #sig 接下来是最简单的一串声明了开始的计时器let __start = ::std::time::Instant::now();,

下面咱采取了一个闭包的策略防止函数提早返回无法触发结束计时, 在这个闭包里面也是大胆的把代码块给塞了进去,

剩下两行就是打印跟返回值了!

看懂了吗? 嗯嗯, 相信泥已经看懂了! 诶, 后面那个爱问问题的猫猫说什么¿ 哦! 为什么咱的标识符前面要有__ 吗,

为什么咱包不用引入的而且前面要加::吗¿

好问题, 其实这都是因为咱过程宏不是卫生的呢, 标识符前面加__ 是防止被shadow 呢, 至于包呢, 因为咱不知道使用咱包的人会不会有同名包,

所以采用绝对路径, 前面的:: 表示这个要从root 开始找这个包呢!

嗯呢, 让咱展开这个宏看看结果吧!

  • 原版

`rust

#[print_time_cost(qwq)]

fn test(str: String) -> String {

println!("qwq");

str

}

`

  • 展开

`rust

fn test(str: String) -> String {

let __start = ::std::time::Instant::now();

let __r = (move || {{

println!("qwq");

str

}})();

println!("fn \"{0}\" cost : {1} ms",

"test",

__start.elapsed().as_millis()

);

__r

}

`

完美!

派生宏

好的, 想必看到此处的小猫猫们应该都已经略懂一二了, 接下来向咱走来的是最终大BOSS 派生宏, 让我们直接进入正题, 直接实现一个自己的

Display !

首先在泥主要的包里面先新建这个trait (有proc-macro = true 的包是没办法导出trait 的哦)

trait MyPrint {
    fn print_self(&self);
}


接下来就是写宏的时间了

#[proc_macro_derive(MyPrint)]
pub fn print(ts: TokenStream) -> TokenStream {
    let input = syn::parse_macro_input!(ts as syn::DeriveInput);
    let ident = &input.ident;
    let struct_name = ident.clone().to_string();
    let mut string_vec: Vec<String> = Vec::new();
    let mut ident_vec: Vec<Ident> = Vec::new();
    let compile_err: fn(&str) -> TokenStream = |err| {
        let err = format!("compile err with: {err}");
        let r = quote::quote! {
            compile_error!(#err);
        };
        return r.into();
    };
    match input.data {
        Data::Struct(input) => match input.fields {
            Fields::Named(field) => {
                for field in field.named.iter() {
                    let ident = field.ident.clone().unwrap();
                    ident_vec.push(ident.clone());
                    string_vec.push(ident.to_string())
                }
            }
            _ => return compile_err("only support named struct"),
        },
        _ => return compile_err("only support named struct"),
    }
    let r = quote::quote! {
        impl MyPrint for #ident {
            fn print_self(&self){
                println!("{}: {{", #struct_name);
                #(println!("\t{}: {},", #string_vec, self.#ident_vec);)*
                println!("}}");
            }
        }
    };
    r.into()
}


好的, 这里如果跟着之前的宏已经配置完了的话应该是不会出什么小意外的了qwq, 接下来让我们看怎么实践的!

首先最上面的6 个let 非常简单, 第1 个是解析TokenStream, 第2 个是获取结构名, 第3 个是获取结构名的字符串, 第4 个是创建item

的string 集合, 第5 个是创建item 的ident 集合, 第6 个是创建了一个编译器错误闭包, 方便咱直接使用.

接下来咱写了一个大的match 这个是用来匹配syn::DeriveInput 的, syn::DeriveInput 里面有三个enum 我们这里只做了结构体的打印,

所以其他的(enum/嵌合体) 直接compile_error!() 给丢出去, 在结构体里面咱又做了一次match 这里过滤掉tuple 与 unit

只做named (不是窝喜欢的类型直接不做), 已经取出named 后咱把这些field 给遍历一下, 拿到每个属性的ident 放到已经备好的vec中,

最后的最后就是拼接咱的代码并且返回了, 相信看到这里的小猫猫也可以理解quote 里面写的啥awa, 最后让我们展开看看

  • 结构

`rust

#[derive(MyPrint)]

struct QwQ {

ident: String,

int: i32,

}

`

  • 展开

`rust

impl MyPrint for QwQ {

fn print_self(&self) {

println!("{0}: {{", "QwQ");

println!("\t{0}: {1},", "ident", self.ident);

println!("\t{0}: {1},", "int", self.int);

println!("}}
");

}

}

`

debug 小技巧

老实写宏很枯燥吧¿ 没关系, 咱使用cargo expand 来debug! 这个工具让我们可以轻易的看到宏展开以后都是一坨什么玩意了, 怎么用呢¿

往下看就知道了!

安装

好的, 这么好的工具想必一定是cargo 自带的吧, 并非, 这玩意完完全全是个第三方库, 想要使用咱要先cargo install cargo-expand

使用

cargo expand 使用起来非常简单, 在你的项目所在文件夹下直接输入即可使用, 如果泥的项目是[workspace] 需要加上

-p member_name 来展开, 如果泥只希望展开一个module 就在后面加上路径即可

例如我的项目结构是这样的

macro
    main
        main.rs
        tests.rs
    macros
        lib.rs
    expand.txt


macros 文件夹下的lib.rs 是咱写宏的地方, 咱只想想测试main.rs 里面的main函数使用这个宏的效果, 并且输出到expand.txt 里面,

那咱就使用

cargo expand -p main main > expand.txt

后记

现在rust 的宏已经瘫坐眩晕在.rs 文件里面了, 那一刻就像看到原子弹爆炸, 他没有任何手段阻止泥玩弄他了, 去吧猫猫们,

尽情地使用他吧, 尽情地玩弄他吧, 啊哈哈哈哈哈哈哈哈哈~

<font color="light-blue">点赞</font>

<font color="pink">投币</font>

<font color="white">灌注</font>

<font color="pink">收藏</font>

<font color="light-blue">贴贴!</font>

参考文献

>

官方宏范例

>

官方宏范例2

>

宏的卫生性讲解

>

Rust 学习笔记

>

syn Crate 文档

>

quote Crate 文档

>

cargo expand

>

cargo expand github

>

新手写宏就上路

发布评论
全部评论(0)