Rust Macro

[jackalchenxu]

Rust宏设计

从最常见到的vec![]到substrait中各种宏来帮助用户完成pallet基本功能

#[pallet::storage]
pub(super) type Something<T: Config> = StorageValue<_, _>;

Rust中的宏，最重要的是帮助开发者少写boilerplate代码，快速且心智简单地完成基础设置和基本功能，从而让开发者更专注在业务逻辑上。

Rust中的宏，大致可分为

• “声明宏”（Declare Macros）
• “过程宏”（Procedural Macros）

最开始学习rust时，熟悉的两个语句：

• let mut v = vec![];中的做Vec类型构建的宏，就是 声明宏
• #[derive(Debug)]Struct MyStruct { ... }，自动给MyStruct添加Debug trait实现，这里就是过程宏的一种（derived macro）

如果要编写自己的宏，或者深入看懂其他的宏，就需要学习Rust中的宏，设计和实现，所幸的是，大神[dtolnay](https://github.com/dtolnay)为我们搞了一个学习路径 - proc-macro-workshop，认真完成这里的多个任务/关卡，之后你就可以说对于Rust Macro的编写就达到了中等程度

我目前做完了builder和customDebug，如下是我的一些思路和线索，大概的方向对了，剩下的是细节。

1. rust宏编写，基本上是在跟ST- syntax tree打交道，其被包装程度介于字符和AST之间；当宏内的语句被解析为DeriveInput，你可以去看它的各个成员变量，并顺着跟下去，或者打印出来，你就会发现有一些字符已经被包装为抽象的节点，比如一个Ident结构，但也会看到类似 -， >这样的字符（Punct），编写宏，就是要跟这些东西打交道，添加，修改，删除，做出一个新的TokenStream

   从宏观角度看，rust宏处理就是把一个输入的ST，经过添删改等处理，变成一个新的ST，并返回给编译器做后续处理。

     input ST ---> procedural macro ---> Ok(new_st) 
                                    |--->Err(compile error)
   

2. 以derive宏处理为例，有如下的流程：
   
   在宏处理过程中，有Syn crate，提供parse等相关函数，把Token Stream，转成ST数据类型，如常见的标识符Ident，符号:: Colon2, 等等各种数据结构，

   有Quote crate，再把这些数据类型转换回TokenStream

3. 宏编写必须掌握的四个crate

   • syn
   • quote
   • proc_macro2
   • proc_macro

   syn和quote在上图中已经看到；

   proc_macro中主要是定义TokenStream结构，出现时间最早，编译器依赖它；

   proc_macro2出现时间晚于proc_macro，proc_macro2提供了更多的结构和功能，syn，quote都与之配合。
   proc_macro2还提供了TokenTree等，这些都会在declare macro中被使用到。
   proc_macro2::TokenStream具有From/Into trait到proc_macro::TokenStream

   一般的开发套路是：

   • 流程中起始传入，和最后输出的TokenStream是proc_macro::TokenStream；
   • 中间过程都使用proc_macro2::TokenStream，最后在使用into()转成proc_macro::TokenStream

参考

1. 过程宏的基本介绍
2. syn, proc_macro2等中出现的结构定义（比如Ident，Path，PathSegment）是什么，在这里有详细介绍

[jackalchenxu]

Seq任务

task1

能parse 如下信息

seq!(N in 0..8 {
   // nothing here but will be filled later, to be replace N with number
});
fn main() {}  

先说明一下，后续会从N，in 0..8, {...} 这三处做文章，所以建立Seq结构体，把这些信息都放入成员变量中。
并调用parse_macro_input!()来得到Seq实例，同时要求Seq实现parse trait

#[proc_macro]
pub fn seq(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     //前面的任务都直接使用parse_macro_input(input as DeriveInput)，其实是实现了parse trait
    let seq = parse_macro_input!(input as Seq); 
    eprintln!("seq:{:?}", seq);
}

#[derive(Debug)]
struct Seq {
    ident: Ident,    //保存N
    start: isize,    //这里先暂时用start，end来表示，后续题目会增加0..=8这样的样式，我们在后面会用MyRange来替换
    end: isize,
    body: TokenStream,   //最复杂的body放这里，后续题目会在body中出现N，并根据pattern：~N或者N来做替换
}

impl Parse for Seq {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let ident: Ident = input.parse()?;
        input.parse::<syn::Token!(in)>()?;

        let start: LitInt = input.parse()?;
        input.parse::<syn::Token!(..)>()?;
        let end: LitInt = input.parse()?;

        let body_buf;
        syn::braced!(body_buf in input);
        let body = body_buf.parse::<TokenStream>()?;

        Ok(Seq { ident, start, end, body })
    }
}

task 2

增加body中的内容，出现N，不过当前题目不需要解析，可以直接过

task 3

把如下：

seq!(N in 0..4 {
    compile_error!(concat!("error number ", stringify!(N)));
});

变成：

compile_error!(concat!("error number ", stringify!(0)));
compile_error!(concat!("error number ", stringify!(1)));
compile_error!(concat!("error number ", stringify!(2)));
compile_error!(concat!("error number ", stringify!(3)));

我们要做body内容的解析，同时在body的上面，根据seq的start...end来一个for展开，类似：

let mut ret = TokenStream::new();

for n in self.start..self.end {
   ret.extend(self.expand(&self.body, n));
}

关键点在fn expand(&self, body: &TokenStream, n: isize) -> TokenStream
我这里直接上syn和proc_macro2的三件套：

在这里我们只需要body的token stream转成Vec，然后对Vec做枚举，遍历token；同时push token到ret中；当碰到N这个ident时，换成n；
即所谓旧token stream进来，新token stream出去，rust宏处理就是这么个流程。

这边暂时是检测ident，如果等于N，就直接做替换，这是比较简单的流程。
但后面的任务，会对token tree做match判断，并在当前token处，再往后token探查一下，看是什么情况，再决定流程该什么走，类似如下：

 let mut index: usize = 0;
 while index < buf.len() {
   .....
   ..................
   TokenTree::Ident(id) => {
        //这里是检测~N, 然后对"当前token~N"这种样式做替换，为"当前token0", "当前token1"这样的
	if let Some(TokenTree::Punct(p)) = &buf.get(index + 1) {
		if p.as_char() == '~' {
			if let Some(TokenTree::Ident(match_id)) = &buf.get(index + 2) {
				if match_id == &self.ident {
					let func_name = Ident::new(&format!("{}{}", id, n), id.span());
					ret.extend(quote!(#func_name));
					index += 3;
					continue;
				}
			}
		}
	}
        
        //这里的是本任务的处理方法
	if id == &self.ident {
		let n_str = LitInt::new(&format!("{}", n), tree_node.span());
		ret.extend(quote!(#n_str));
		index += 1;
		continue;
	}
    }
   
    ret.extend(quote!(#tree_node));
    index +=1;
}

另外，对group的处理，需要使用到递归，比如对于(abc(def))：
检测最外层是TokenTree::Group(g)，接着继续expand(g.stream()), g.stream为abc(def);
处理到(def)的时候一样递归，直至def处理完成，返回处理后的token - def， 接着再返回abc(def) - 此处一定要使用g.delimiter()来做一层包裹；直至返回最上层，这样深入遍历后，返回tokenstream，还仍保持之前的层次结构。
核心代码如下：

 while index < buf.len() {
            let tree_node = &buf[index];
            match tree_node {
                TokenTree::Group(g) => {
                    let new_stream = self.expand(&g.stream(), n);
                    let wrap_in_group = Group::new(g.delimiter(), new_stream);
                    ret.extend(quote!(#wrap_in_group));
                    index += 1;
                    continue;
                }
                ......
         }
}

task 4

现在做替换的样式变了一点

seq!(N in 1..4 {
    fn f~N () -> u64 {
        N * 2
    }
});

要把f~N变成 f1（f2，f3等），函数体中的N变成对应的1,2 等

fn f1 -> u64 {
   1 * 2
}

任务3的一部分代码已经写了，这边就是要注意while循环，如果token已经处理，如push到ret中了，记得一定要index+1，然后continue；不匹配的就走default流程(也是push ret，并index+1)，总之要安排好。
因为如果出问题，比如token处理了，但index+1，就会出现死循环，此时cargo check（IDE会自动触发）和cargo test等都会一直跑，无法终结，以为是死机了。

Task 5

本次在body中引入了新的扩展方式。

seq!(N in 0..16 {
    #[derive(Copy, Clone, PartialEq, Debug)]
    enum Interrupt {
        #(
            Irq~N,
        )*
    }
});

之前的扩展方式是类似for n in self.start..self.end { 扩展 }
现在是要在body中的#()*处才进行扩展。

两者扩展方式无法统一在一起，因此需要：

• 事先进行遍历扫描，如果发现#()*样式，则开启ExpandAsterik模式（起一个概念名字即可）
• 如果没有发现#()*样式，则为ExpandInPlace模式，跟以前一样。

enum ExpandMode {
    ExpandInPlace,
    ExpandAsterik,
}

let expand_mode = {
     if search_repeat_tag(&seq.body) {
         ExpandMode::ExpandAsterik
     } else {
         ExpandMode::ExpandInPlace
     }
};

search_repeat_tag(ts: &TokenStream) -> bool
是由（ts）-> TokenBuffer-->Cursor c
c.token_tree() -> (当前token， 指向下一个token的cursor)
这边有一点便利条件的是，在TokenTree的范畴内， #( ... )*仅仅是三个Token: #, (...), *，所以可以很方便的判断是否存在
#()*模式
如下是该函数核心判断：

while let Some((token, cur)) = cursor.token_tree() {
        match token {
            TokenTree::Punct(p) if p.as_char() == '#' => {
                if let Some((TokenTree::Group(g), c_star)) = cur.token_tree() {
                    if g.delimiter() == proc_macro2::Delimiter::Parenthesis {
                        match c_star.punct() {
                            Some((p, _)) if p.as_char() == '*' => {
                                return true;
                            }
                            _ => {}
                        }
                    }
                }
            }
            TokenTree::Group(g) => {
                if search_repeat_tag(&g.stream()) {
                    return true;
                }
            }
            _ => {}
        }

        cursor = cur;
    }

有了模式判断，就先运行判断是否有#()*：

• 如果没有，就走以前的函数
• 如果有，走新加的expand_asterisk()函数

Task 6

用Proc结构体来验证之前的代码是否正确，如果task1-5代码处理得当，此处可以顺利执行

Task 7

之前说过的：

seq!(N in 16..=20  { ... } 

这次变成了16..=20
在Rust中，16..20对应结构体std::ops::Range；而16..=20对应结构体RangeInclusive；两者是不同的结构体

为了能统一保存在Seq结构体中，我们声明了新的结构MyRange：

#[derive(Debug, Clone)]
enum MyRange {
    NonInclusive(Range<isize>),
    Inclusive(RangeInclusive<isize>),
}
impl Iterator for MyRange {
    type Item = isize;

    fn next(&mut self) -> Option<Self::Item> {
        match self {
            MyRange::NonInclusive(n) => n.next(),
            MyRange::Inclusive(i) => i.next(),
        }
    }
}
impl From<Range<isize>> for MyRange {
    fn from(r: Range<isize>) -> Self {
        MyRange::NonInclusive(r)
    }
}
impl From<RangeInclusive<isize>> for MyRange {
    fn from(r: RangeInclusive<isize>) -> Self {
        MyRange::Inclusive(r)
    }
}

因为需要range遍历，我们为MyRange添加了Iterator trait

Task 8

检测之前的代码是否有处理好变量生成

seq!(N in 0..1 {
    fn main() {
        let _ = Missing~N;
    }
});

处理后的ident应该是Missing0， Missing1，这样，报错时会提示Missing~N 这个span找不到定义
如果之前的代码有正确处理，此任务可以顺利通过

Task 9

只是通过例子演示，宏处理如何跟macro rules宏（我们称之为macro by example）结合一起，做到”一处定义，多处引用“
一处定义：

macro_rules! pass_nproc {
    ($mac:ident) => {
        $mac! { 256 }
    };
}

任何pass_nproc!( A )， A宏的接收参数都会收到一个256的literal参数

多处引用：

const NPROC: usize = pass_nproc!(literal_identity_macro);
macro_rules! make_procs_array {
    ($nproc:literal) => {
        seq!(N in 0..$nproc { [#(Proc::new(),)*] })
    }
}

// Expands to: `static PROCS: [Proc; NPROC] = [Proc::new(), ..., Proc::new()];`
static PROCS: [Proc; NPROC] = pass_nproc!(make_procs_array);

总结一下

Seq任务中熟悉了Declare Macro，期间我们使用到了

• ParseStream（parse + peek），解析为我们自定义的结构体；
• TokenBuffer + Cursor，做快速内容扫描找寻我们想要发现的内容
• TokenStream -> Vec<TokenTree> -> 遍历TokenTree节点，做节点的添加，删除，修改，生成新的TokenStream

[jackalchenxu]

Parse trait

对于任何TokenStream，想把信息转换为结构性信息，如Seq，或者是DeriveInput, 又或者是syn::Item
都需要我们调用parse()

如下是可用的几种形式：

input: TokenStream;

let structured_info = parse_macro_input!(input as Structured_Info_Type);
//or
let structured_info = syn::parse::<Structured_Info_Type>(input).exepect("parse error");

[jackalchenxu]

Sorted任务

回顾一下，之前的Debug, Builder任务，我们熟悉了派生宏：

#[derive(CustomDebug)]
pub struct Field {
    ...
    #[debug = "0b{:08b}"]
    bitmask: u8,
}

#[derive(Builder)]
pub struct Command {
   executable: String,
   ...
}

之前的Seq任务，我们熟悉了声明式宏：

seq!(N in 1..4 {
   fn f~N () -> ... {
      ...
   }
}

本任务开启了属性宏

#[sorted]
enum Conference {
   RustBeltRust,
   RustConf,
   ...
}

impl Display for Error {
   #[sorted::check]
   fn fmt ... {
      ...
   }
}

task 1

构建解析属性式样宏的框架
源文件中如下：

#[sorted]
pub enum Conference {
    RustBeltRust,
    RustConf,
    RustFest,
    RustLatam,
    RustRush,
}

对应解析要写

#[proc_macro_attribute]
fn sorted(args: TokenStream, input: TokenStream) -> TokenStream { ... }

而在函数体内，还是一样用parse_macro_input!(input as syn::Item)， Item中包含上述的enum格式。
本任务不需要额外做处理，所以返回input就够了

task 2

限定#[sorted]只能加在enum上，不能放Struct上。
只需要对解析后的数据类型，做match，只能是enum，如果其它则报错：”expected enum or match expression“
类似：

match parse_macro_input!(input as Item) {
   Item::Enum(sorted) => { ... }
   _ => syn::Error::new(
         proc_macro2::Span::call_site(),     // 这边call_site()会把错误标志定位到#【sorted】宏这里
         "expected enum or match expression")    //之所以也要match expression，是因为后面会要求在match expression上加
      .to_compile_error()
      .into()
}

task 3

现在对加在enum上的#[sorted]要发挥功能了，enum中的成员变量名字需要按照字母顺序排序好.

#[sorted]
pub enum Error {
    ThatFailed,
    ThisFailed,
    SomethingFailed,
    WhoKnowsWhatFailed,
}

如果没有排序，则针对未排序的成员处报错：

error: SomethingFailed should sort before ThatFailed
  --> tests/03-out-of-order.rs:20:5
   |
20 |     SomethingFailed,
   |     ^^^^^^^^^^^^^^^

这个任务，主要还是要对enum内成员变量做解析，取出变量ident之后，检查顺序是否正确（与排序后的顺序一致）。
一种做法是let vv = v.clone(), 然后vv.sort(); 然后再把两者放一起逐个比对：

• 如果不一致就报错退出当前比较
• 如果一致，则返回代表enum本体的TokenStream

需要添加一个类似fn expand_enum_def(item_enum: &ItemEnum) -> syn::Result<TokenStream> { ... }
顺序一致的话，返回item_enum.to_token_stream()是很重要的，不然解析后的程序代码少了这一块，报语法错误。

if a != b {
   return syn::Error::new(b.span(), format!("{b} should sort before {a}"))
}

其实这里面有一个注意点： 在这个任务上，如果发现未排序，此时实际上可以有两种做法：

1. 生成错误，并只返回错误

for(....) {
   .....
   if a != b {
       return Err(syn::Error::new(b.span(), ".....")).into_compile_error());
   }
}

Ok(item_enum.to_token_stream())

2. 生成错误，把它变成token stream，和其余正常数据生成的token stream放一起返回，类似：

let mut ret = TokenStream::new();
......
ret.extend(syn::Error::new(b.span(), ".....")).into_compile_error());
ret.extend(item_enum.to_token_stream());
Ok(ret)

在本例中，选择（1）相对直观，但实际上这样有可能会导致除宏之外的代码缺失，不完整；
（2）的做法，在后面的任务中有使用到，它的优点在于，可以完整保留解析后的代码信息，同时又携带了compile error，这样返回后，编译器会显示compile error； 同时也因为代码信息完整，而不会报代码因缺失导致的错误。

属性宏会修改代码

这里引出一个很重要的概念，就是属性宏的处理跟之前我们学习的派生宏有一处很大的区别：

• 派生宏：在原来代码的基础上，添加其处理和生产的代码；也就是说，如果派生宏不产生输出，则最后的结果是原来代码
• 属性宏：输入原来的代码，如果属性宏不产生输出，则最后的结果是空；所以属性宏很常见的套路会把原来代码存一份放入输出中，额外产生的部分再添加到输出中去。
  这也是（2）的做法的由来，在本例中，如果换用（2）的做法也是同样可以通过测试的。

syn::Error::new()出来的错误变量，调用into_compile_error()，可以得到对应的TokenStream类型

task 4

现在enum里面的信息不只是id了，还有类似"Fmt(fmt::Error)"这样的。不过之前我们的代码也只是比较ident，所以这里可以直接过

task 5

来到了相对最麻烦的task；现在属性宏出现在了函数体上：

#[sorted]
pub enum Error {
    Fmt(fmt::Error),
    Io(io::Error),
}

impl Display for Error {
    #[sorted::check]
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        use self::Error::*;

        #[sorted]
        match self {
            Io(e) => write!(f, "{}", e),
            Fmt(e) => write!(f, "{}", e),
        }
    }
}

这里，还记得我们之前说过的吗？ 属性宏会吃掉原有的代码，再生成一个新的代码给编译器。
此处，有三件事情要做：

1. 确保出现#[sorted::check]后，在其修饰的block内，有#[sorted]修饰的match中，做match项目的排序
2. 确保最后生成的代码，不能包含有 #[sorted::check] 和 #[sorted]，因为这样会让代码无法通过编译
3. 最后生成的代码，不仅仅要有原生代码，还要有错误信息（如果match内的元素（称之为match arm）没有正确排序的话)

dontley提到了VisitMut；我们之前在Debug任务中使用到了Visit，用来在Syntax Tree中做搜索，根据搜索结果做一些判定/设定。
我们在这个任务，要使用VisitMut，不仅要搜索，而且要做修改，包括删除#[sorted] (#[sorted::check]不需要额外做处理，只要不包含在生成代码中即可)
VisitMut()中，如果我们什么都不做，则默认会维持原来的代码内容输出为新内容。

实现这些大概需要：

1. 定义处理入口

#[proc_macro_attribute]
pub fn check(
    _args: proc_macro::TokenStream,
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    // eprintln!("input:{:#?}", input);
    let mut func = parse_macro_input!(input as ItemFn);

    // returned token stream should contain function body
    // with #[sorted] attribute removed
    let mut t = TokenStream::new();
    if let Err(e) = check_match_sort_in_fn(&mut func) {    //不依赖check_match_sort_in_fn()返回值返回语法正确的代码
        // if any error, put it into returned tokenstream
        t.extend(e.to_compile_error());
    }
    t.extend(func.to_token_stream());   //func已经在check_match_sort_in_fn()中被修改，为语法正确的代码（token stream）

    t.into()
}

check_match_sort_in_fn()，其中处理删除#[sorted]并检测match arms中各个arm的顺序，如果顺序有问题，则保存入实现VisitMut的结构体中

#[derive(Default)]
struct SortCheck {
    err: Option<syn::Error>,
}

impl VisitMut for SortCheck {
    fn visit_expr_match_mut(&mut self, node: &mut ExprMatch) {
        // if fucntion body contains attribute: sorted
        if node.attrs.iter().any(|n| {
            n.path
                .segments
                .iter()
                .any(|segment| segment.ident == "sorted")
        }) {
            // remove the "sorted" attribute from function body
            // it will cause syntax error
            node.attrs.retain(|n| {
                n.path
                    .segments
                    .iter()
                    .all(|segment| segment.ident != "sorted")
            });

            let mut v = vec![];
            for arm in node.arms.iter() {
                match &arm.pat {
                    syn::Pat::TupleStruct(t) => {
                        let b = concat_path_string(&t.path.segments);

                        if v.last().is_some() {
                            let a: &String = v.last().unwrap();
                            if a.cmp(&b) == Ordering::Greater && self.err.is_none() {
                                self.err = Some(syn::Error::new_spanned(
                                    t.path.clone(),
                                    format!("{b} should sort before {a}"),
                                ));
                            }
                        }
                        v.push(b);
                    }
                    syn::Pat::Ident(id) => {
                        let b = id.ident.to_string();
                        if v.last().is_some() {
                            let a: &String = v.last().unwrap();
                            if a.cmp(&b) == Ordering::Greater && self.err.is_none() {
                                self.err = Some(syn::Error::new_spanned(
                                    id.clone(),
                                    format!("{b} should sort before {a}"),
                                ));
                            }
                        }
                        v.push(b);
                    }
                    syn::Pat::Wild(w) => {
                        if arm != node.arms.last().unwrap() {
                            self.err = Some(syn::Error::new_spanned(
                                w.clone(),
                                "_ should be the last one of the match",
                            ));
                        }
                    }
                    _ => {
                        // eprintln!("else:{:#?}", arm.pat);
                        // 只保留第一笔错误消息
                        if self.err.is_none() {
                           self.err =
                               Some(syn::Error::new(arm.pat.span(), "unsupported by #[sorted]"));
                        }
                    }
                }
            }
        }

        visit_mut::visit_expr_match_mut(self, node);
    }
}

如上的代码，后面的task 6（match的类型有一点变化）,7（match类型中有一些不能做比较的），8（_只能作为match的最后一项） 也都能过了。

[jackalchenxu]

Builder

今天才后知后觉看了dtolnay/proc-macro-workshop的任务介绍，他建议任务顺序是Builder，然后是【CustomeDebug，sorted，seq】，最后是bitfield - 做这个任务要看一下它的任务简介，不然不知道它讲什么）

Builder有很像Clap中的宏，Builder任务主要是派生宏，和其附属的inert attributes，我举个例子：

#[derive(Builder)]               <--derive宏
pub struct Command {
    executable: String,
    #[builder(each = "arg")]      <-- inert属性builder，只能依附于derive Builder内被使用
    args: Vec<String>,
    #[builder(each = "env")]
    env: Vec<String>,
    current_dir: Option<String>,
}

// 设置成员值，调用build()来最后生成Command实例
let mut builder = Command::builder();
builder.executable("cargo".to_owned());
builder.args(vec!["build".to_owned(), "--release".to_owned()]);
builder.env(vec![]);
builder.current_dir("..".to_owned());

let command = builder.build().unwrap();

派生宏中我们要自动生成：

1. 为CommandBuilder添加builder()方法，来生成CommandBuilder实例

2. 添加同名函数executable(), args(), env(), current_dir()来为CommandBuilder成员赋值

3. 添加build()来最后生成Command实例

4. CommandBuilder结构体

   • 结构体中需要executable, args, env, current_dir成员
   • builder()方法生成CommandBuilder之后，此时CommandBuilder内成员变量只是有默认初始值

5. 为CommandBuilder添加arg()方法，设置值push到args中（意味着arg()实际上可以调用多次）；env也一样

6. 如果所有必要的成员变量（非Option类型成员）已经被设置了值，build()应该可以成功，build()返回一个Result<Command, String>

Builder中的各个任务，基本上也就是在回答和设计以上几个问题。

整体实现上，可以遵循如下两个步骤：

1. 获取结构定义信息，包括字段名，字段类型，inert属性等
2. 依照如下几个部分来组装实现代码
   • CommandBuilder定义
   • builder()方法实现
   • CommandBuilder的方法（成员变量同名函数）实现
   • arg和env方法实现
   • build()方法实现
     把以上几个部分拼接在一起就完成了整个任务

类似：

#[proc_macro_derive(Builder, attributes(builder))]
pub fn derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    match do_expand(&input) {
        Ok(token_stream) => token_stream.into(),
        Err(e) => e.to_compile_error().into(),
    }
}

/// Reference pattern
//  #[derive(Builder)]               <--derive宏
/// pub struct Command {
///     executable: String,
///     #[builder(each = "arg")]      <-- inert属性builder，只能依附于derive Builder内被使用
///     args: Vec<String>,
///     #[builder(each = "env")]
///     env: Vec<String>,
///     current_dir: Option<String>,
/// }
#[derive(Debug)]
struct FieldInfo {
    f_name: Ident,
    f_type: TypePath,
    inner_type: Option<Ident>,
    optional: bool,
    each_ident: Option<Ident>,
}

fn do_expand(input: &DeriveInput) -> syn::Result<TokenStream> {
    let struct_name = &input.ident;
    let data = &input.data;

    let field_infos = get_fields_info(data)?;

    let mut code_generated = TokenStream::new();
    let builder_def = generate_builder_def(struct_name, &field_infos)?;
    let builder_impl = generate_builder_impl(struct_name, &field_infos)?;
    let setters = generate_setters(struct_name, &field_infos)?;
    let attribute_setters_fn = generate_attribute_setters(struct_name, &field_infos)?;
    let build_fn = generate_build(struct_name, &field_infos)?;

    code_generated.extend(builder_def);
    code_generated.extend(builder_impl);
    code_generated.extend(setters);
    code_generated.extend(attribute_setters_fn);
    code_generated.extend(build_fn);
    Ok(code_generated)
}

/// get field info from struct
fn get_fields_info(data: &Data) -> syn::Result<Vec<FieldInfo>> {
    let mut v = vec![];
    if let syn::Data::Struct(syn::DataStruct { fields, .. }) = data {
        for field in fields {
            if let syn::Type::Path(ty) = &field.ty {
                let inner_type = get_inner_type(ty.path.segments.first().unwrap());
                let optional = is_wrapped_by_option(&ty.path.segments);
                let each_ident = get_field_attr(field)?;

                let f = FieldInfo {
                    f_name: field.ident.clone().expect("field_name cannot be empty"),
                    f_type: ty.clone(),
                    inner_type,
                    optional,
                    each_ident,
                };

                v.push(f);
            } else {
                return Err(syn::Error::new(
                    field.span(),
                    "only parse TypePath for field type",
                ));
            }
        }
    } else {
        return Err(syn::Error::new(
            proc_macro2::Span::call_site(),
            "only parse Builder for struct",
        ));
    }

    Ok(v)
}

个人感觉，因为是第一个任务，所以很多精力应该是放在熟悉其套路，数据类型和如何操作上。

不过在任务进行中，你会逐渐意识到宏编程，其很大程度是“非语法性“，而是”字符性“的操作。
举一个例子：检测一个path::segment，是Punctuated<PathSegment, Colon2>类型，其是否由std::option::Option来包裹的；但是用户可能有如下写法：

• Option<T>
• option::Option<T>
• std::option::Option<T>
• ::std::option::Option<T>
• MyLikeButNot::Option<T>
  在宏编程框架下，这些检测和处理都只能基于字符样式匹配来写，构建完备检测各种条件的函数，实在有点难；比较切实的方法是按照测试用例来构建代码或者代码只支持几种写法。

[jackalchenxu]

Debug/CustomDebug

依然范围在派生宏和iner attribute上，不过涉及了更多的类型概念，如PhantomData，范型。
本任务是利用派生宏来为结构体实现Debug Trait，并在一些字段上使用指定的特殊格式，例子如下：

type S = String;

#[derive(CustomDebug)]         //为Field<T>实现Debug Trait
pub struct Field<T> {
    marker: PhantomData<T>,          //PhantomData<T>本身已经为任何T实现Debug
    string: S,                                       //用户alias类型
    #[debug = "0b{:08b}"]                 //inert attribute指定Debug格式
    bitmask: u8,
}

fn assert_debug<F: Debug>() {}

fn main() {
    // Does not implement Debug.
    struct NotDebug;

    assert_debug::<PhantomData<NotDebug>>();
    assert_debug::<Field<NotDebug>>();
}

实现Debug Trait，代码类似：

impl<T> std::fmt::Debug for Field<T>    //要考虑范型， 考虑where子句内容怎么写
where
   T: std::fmt::Debug,
{
   fn fmt(&self, f:&mut std::fmt::Formatter<'_>) -> std::fmt::Result {
      write!(...);
   }
}  

整体的设计仍然可以沿用Builder例子的结构，而crate上也主要是syn，quote；但本例子中解析数据结构更为复杂，if let，for循环嵌套在一起好多层。
这个任务的设计参见下图：

程序流程的套路，大致也是首先获取结构体中的各个成员变量信息，不过这次只需要获取成员变量名和debug format

#[derive(Debug)]
struct FieldInfo {
    f_name: Ident,
    output_format: Option<LitStr>,
}

let fields_info = get_fields_info(&input.data)?;

/// get field_name and inet attribute of "debug" output format
fn get_fields_info(data: &syn::Data) -> syn::Result<Vec<FieldInfo>> {
    let mut v = vec![];

    if let syn::Data::Struct(syn::DataStruct {
        fields: syn::Fields::Named(syn::FieldsNamed { named, .. }),
        ..
    }) = data
    {
        for name in named.iter() {
            let mut output_format = None;
            for field_attr in name.attrs.iter() {
                if let Ok(syn::Meta::NameValue(m)) = field_attr.parse_meta() {
                    if m.path.is_ident("debug") {
                        if let syn::Lit::Str(debug_format) = m.lit {
                            output_format = Some(debug_format);
                            break;
                        }
                    } else {
                        return Err(syn::Error::new_spanned(m, "expected `debug(..)`"));
                    }
                }
            }

            v.push(FieldInfo {
                f_name: name.ident.clone().expect("in get_struct_field"),
                output_format,
            });
        }
    }

    Ok(v)
}

其余部分还需要单独写函数，获取：

1. hatch_escape信息（作者在任务中为该信息起的名字）
2. 成员变量中的范型
3. 结构体范型信息（input.generics）

这里结构体范型信息相当有用，可以调用split_for_impl()来分别得到impl, Field, Where子句三个部分的基础框架，我们可以在上面添加更多信息来组成最后的语句。
大致代码如下：

fn do_expand(input: &DeriveInput) -> syn::Result<TokenStream> {
    let struct_name = &input.ident;
    let attrs = &input.attrs;

    let hatch_escape = get_attribute_debug_bound(attrs)?;

    let fields_info = get_fields_info(&input.data)?;

    let field_generics: Vec<syn::Path> = get_struct_field_types(input)
        .iter()
        .map(|ty| ty.path.clone())
        .collect();

    let debug_impl = generate_debug_trait(
        struct_name,
        &fields_info,
        &input.generics,
        &field_generics,
        hatch_escape,
    )?;

    let mut token_steam = TokenStream::new();
    token_steam.extend(debug_impl);

    Ok(token_steam)
}

在本任务中，第一次介绍了syn::Visit module，让我们为遍历syntax tree加上hook，方便找寻PhantomData和数据成员的范型参数T

struct TypePathVisitor {
    v: Vec<syn::TypePath>,
}
impl Visit<'_> for TypePathVisitor {
    fn visit_type_path<'ast>(&mut self, node: &'_ syn::TypePath) {
        if node
            .path
            .segments
            .pairs()
            .any(|a| a.value().ident != "PhantomData")
        {
            if node.path.segments[0].arguments == syn::PathArguments::None && !self.v.contains(node)
            {
                self.v.push(node.clone());
            }

            visit::visit_type_path(self, node);
        }
    }
}

fn get_struct_field_types(st: &syn::DeriveInput) -> Vec<syn::TypePath> {
    let mut visitor = TypePathVisitor { v: vec![] };
    visitor.visit_derive_input(st);
    visitor.v
}

[jackalchenxu]

Bitfield

任务介绍

这个任务有一点特别，因为这个任务要求开发者熟悉“位运算”；另外，该任务对设计有要求，直观简单的设计到后面的任务会遇到非常多的问题；我这里把设计先交个底。
该项任务是通过宏定义来为结构体/enum中的数据成员实现一个类型定义，B1，B3，Bxx这样的类型，如下结构体定义:

#[bitfield]
struct MyFourBytes {
   a: B1,
   b: B3,
   c: B4,
   d: B24,
}

该结构体占4个字节((1+3+4+24）/ 8 = 4），b成员变量的类型为B3，表示该成员变量所对应的bit位宽为3个bit，在4个字节变量中的位置在a（占b0）之后，即b1，b2，b3。

在testcase中，需要支持对结构体MyFourBytes中的a，b，c，d，赋值并get它们的值。

从设计上来说，需要B1,B2,...B24都是透过宏定义类型实现，一种实现是enum B3 {}；没错，它根本不占空间。
而类型MyFourBytes，实际生成为：struct MyFourBytes { data: [u8; 4] } -- 这样才能通过第2个testcase测试。
结构体MyFourBytes也需要实现一些方法函数，比如get_a(), set_b()，来存/取成员变量。

所有Bx类型都实现了Specifier trait，该trait实现了Bx类型的位宽BITS，还提供了对应的GET、SET操作返回的rust整形类型，如u8，u16，u32等。
类型系统
本任务需要开发者为trait定义关联类型（associate type），如下是为bool类型实现该trait的结果：

impl Specifier for bool {
    const BITS: u8 = 1;
    type SetterType = bool;
    type GetterType = bool;

    fn from_u64(val: u64) -> Self::GetterType {
        val > 0
    }

    fn into_u64(val: Self::SetterType) -> u64 {
        val as u64
    }
}

如下是为BitField5类型实现该trait的结果:

impl Specifier for BitField5 {
    const BITS: u8 = 5;
    type SetterType = u8;
    type GetterType = u8;

    fn from_u64(val: u64) -> Self::GetterType {
        val as Self::GetterType
    }

    fn into_u64(val: Self::SetterType) -> u64 {
        val as u64
    }
}

BITS=5代表该类型占5个bit；
GetterType和SetterType为u8表示get该类型的变量，返回值为u8类型（依次更大空间是u16，u32和u64）
宏代码实际运行时，会使用宏来一次性为Bit0到Bit64都生成定义；
我们在实际使用这些类型时，会使用该类型BitField5的一个短名字类型：B5

但是为什么要搞类型系统呢？原因在这里：
testcase 04 - multiple-of-8bits

type A = B1;
type B = B3;
type C = B4;
type D = B23;

#[bitfield]
pub struct NotQuiteFourBytes {
    a: A,
    b: B,
    c: C,
    d: D,
}

a，b，c等类型是通过type alias来定义的，该部分代码已经超出bitfield宏的范围；开发者可以另搞一套解析系统，把最终的B1等类型实际替换过来，但这不是proc macro的范畴（rustc compiler的领域？）

解决这个问题最好的方式就是：

1. 定义好Specifier Trait
2. 定义好BitField0..BitField64类型，并为它们实现Specifier Trait
3. 所有类似类型A，B，C，D都::属性/方法来统一处理

但这样的类型系统也有缺点，首先它的类型实际上只是摆弄TokenStream，举一个例子，B1在BitFieldSpecifier的Trait中的关联常量BITS=1，但是这里的BITS，不能真的与rust proc macro中的rust代码中的u8等类型做加减运算，唯一只能用于quote!()中写入，转而让rust编译器做计算，所以cargo expand时你会看到如下：

MyFourBytes {
data: [0; (<B1 as ::bit_field::BitFieldSpecifier>::FIELD_WIDTH as usize
         + <B3 as ::bit_field::BitFieldSpecifier>::FIELD_WIDTH as usize
         + <B4 as ::bit_field::BitFieldSpecifier>::FIELD_WIDTH as usize
         + <B24 as ::bit_field::BitFieldSpecifier>::FIELD_WIDTH as usize) / 8],
}

这样给我们的宏代码，比如做位运算时，计算offset，计算width，生成bit mask等，带来了比较多的困难。

位操作(bitwise)

所有的位操作，都涉及到两个关键信息：

1. 操作的位在当前字节的偏移量(bits_offset)
2. 操作的位的位宽（bits_width）

我们拿get_b()和set_b()为例子说明，假设它们的原型如下：
get_b(&self) -> u8
set_b(&mut self, val: u8)

通常的get_b(&self)包含如下步骤：

1. 生成b_mask，即b对应data数据位置bit位置为1，其余位置位为0的值；
2. data数据 & b_mask，这里&是按位与 （bit and operation）
3. 上一步骤得到的值右移bits_offset，返回该值

set_b(&mut self, val)包含的步骤稍微复杂一点：

1. b_mask，取反 => b_hollow（b的位置为0，其他位置都为1）
2. b_hollow & data => data_b_hollow（b的位置为0，其他位置为data其余bit）
3. val，右移b的 bits_offset => val_shift (b的位置为val，其他位置为0)
4. val_shift | data_b_hollow

但如果按照这样的方式来书写，由于上面提到的类型系统的问题，会遇到很多麻烦。比较好的设计如下：
get_b()：

• 获取b变量在结构体的offset: b_offset
• 设置初始值val为0
• 生成一个0..B3位宽的iterator i，在循环内
  • self.get_bit(b_offset + i) | val
  • val左移1位
• 返回val

set_b(&mut self, set_val)：

• 获取b变量在结构体的offset: b_offset
• 生成一个0..B3位宽的iterator i，在循环内
  • mask = 1左移i
  • bit = (mask == mask & set_val）） <--得到该set_val的i位的bit值
  • self.set_bit(b_offset + i, bit)

我们需要额外实现两个辅助函数set_bit(), get_bit。
这个实现虽然效率上稍低，但对于宏书写是相当有利的。

BitField任务一，二

检查B1,...B24是否定义好Specifier Trait（assert_eq!(<B24 as Specifier>::BITS, 24);），并检测MyFourBytes结构体实际定义，是否只包括data：[u8; 4]成员（assert_eq!(std::mem::size_of::<MyFourBytes>(), 4);）
如果按照上面的设计实现，可以轻松通过检查

BitField任务三

检查是否实现好get_a(), set_b()等操作函数
按照上面的设计，实现好

let fields = get_field_info(&ts.fields)?;

let helper_fn = gen_helper(&fields)?;
let getter = gen_getters(&fields)?;
let setter = gen_setters(&fields)?;

现在BitField任务的基本流程框架函数应该是这样：

#[proc_macro_attribute]
pub fn bitfield(
    _args: proc_macro::TokenStream,
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let ts = parse_macro_input!(input as ItemStruct);

    let mut token_stream = TokenStream::new();

    match expand(&ts) {
        Ok(ret) => {
            token_stream.extend(ret);
            token_stream.into()
        }
        Err(e) => e.to_compile_error().into(),
    }
}

下接expand函数

fn expand(ts: &ItemStruct) -> syn::Result<TokenStream> {
    let struct_name = &ts.ident;
    let field_type = get_field_type(&ts.fields)?;

    let total_bits = quote!(
        #(
            <#field_type as ::bitfield::Specifier>::BITS as usize
        )+*
    );

    let struct_def = gen_struct_def(struct_name, &total_bits);  <--- 定义MyFourBytes结构体

    let mut checks = vec![];        <---未来会有的一些关于字段的额外检查等
    checks.push(..............);
    checks.extend(......);

    // make struct impl template, add new() fn
    let struct_new_impl = quote!(
        fn new() -> Self {
            #(#checks)*
            Self { data: [0u8; (#total_bits) / 8] }
        }
    );

    let fields = get_field_info(&ts.fields)?;

    let helper_fn = gen_helper(&fields)?;
    let getter = gen_getters(&fields)?;
    let setter = gen_setters(&fields)?;

    let token_stream = quote!(
        #struct_def
        impl #struct_name {
            #struct_new_impl
            #helper_fn
            #getter
            #setter
        }
    );

    Ok(token_stream)
}

调试起来细心一些，这个任务就可以完成

BitField任务四

需要我们为MyFourBytes结构体加入字段累计Bits总和检查

type A = B1;
type B = B3;
type C = B4;
type D = B23;

#[bitfield]
pub struct NotQuiteFourBytes {
    a: A,
    b: B,
    c: C,
    d: D,
}

ABCD类型的累计bit数为31，要求报错类似如下：

error[E0277]: the trait bound `bitfield::checks::SevenMod8: bitfield::checks::TotalSizeIsMultipleOfEightBits` is not satisfied
  --> tests/04-multiple-of-8bits.rs:53:1
   |
53 | #[bitfield]
   | ^^^^^^^^^^^ the trait `bitfield::checks::TotalSizeIsMultipleOfEightBits` is not implemented for `bitfield::checks::SevenMod8`
   |
   = help: the trait `bitfield::checks::TotalSizeIsMultipleOfEightBits` is implemented for `bitfield::checks::ZeroMod8`

特别有一点要提醒的就是rust的trait是impl for 类型，而不是for 某类型的特别的值，因此有如下的设计：

mod checks {
    pub trait TotalSizeIsMultipleOfEightBits {}
    impl TotalSizeIsMultipleOfEightBits for [u8; 0] {}
}

pub struct CheckTotalSizeIsMultipleOfEightBits<T: checks::TotalSizeIsMultipleOfEightBits> {
    phantom: std::marker::PhantomData<T>,
}

在实际生成做检查时：保证total_bits为结构体总的占bit位数和即可。

let total_bits = quote!(
#(
     <#field_type as ::bitfield::Specifier>::BITS as usize   //<--对结构体成员类型做bits占位加和
  )+*
);
................
..............................
checks.push(quote!(
let _: ::bitfield::CheckTotalSizeIsMultipleOfEightBits<[u8; (#total_bits) % 8]>;
));

如果total_bits不能被8整除，则余数为1，对应的类型为[u8; 1]，不满足TotalSizeIsMultipleOfEightBits的要求。这种套路，在后面的任务中还会被用到。

不过这里唯一的毛病在于报错信息：
the trait bitfield::checks::TotalSizeIsMultipleOfEightBits is not implemented for [u8; 7]
把底层的类型[u8; 7]给显示出来了，不太满足原本任务的要求；如果要100%满足的话，还要再经过繁琐的其他处理（类型包装），我觉得可能任务先到这里就算暂时ok了。

BitField任务五

这里是检查我们的get_a()是否有正确的返回值类型设定

#[bitfield]
pub struct MyFourBytes {
    a: B1,
    b: B3,
    c: B4,
    d: B24,
}

fn get_a(&self) -> u8 { ... }，返回类型的应该是“B1最接近的字节数长度”，即u8；而不能是u16，u32或者是u64。
在这里为Trait Speicifier定义如下：

pub trait Specifier {
    const BITS: usize;
    type SetterType;
    type GetterType;

    fn from_u64(val: u64) -> Self::GetterType;
    fn into_u64(val: Self::SetterType) -> u64;
}

get,set输入和输出用GetterType和SetterType，之后用u64做中间类型参与位运算。

BitField任务六

之前我们的#[bitfield]宏对应修改struct，现在加入新的derive for enum：

#[derive(BitfieldSpecifier, Debug, PartialEq, Copy, Clone)]
pub enum DeliveryMode {
    Fixed = 0b000,
    Lowest = 0b001,
    SMI = 0b010,
    ...........,
}

#[bitfield]
pub struct RedirectionTableEntry {
    .............,
    trigger_mode: TriggerMode,
}

而且要求get_trigger_mode()返回值也要能与TriggerMode类型值做比较：
assert_eq!(entry.get_trigger_mode(), TriggerMode::Edge);
这要求我们也要为enum实现Specifier Trait，并提供与u64类型的转换函数
至此，大概的流程框架应该如:

#[proc_macro_derive(BitfieldSpecifier)]
pub fn derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    match build_spec(&input) {
        Ok(token_stream) => {
            token_stream.into()
        }
        Err(e) => e.to_compile_error().into(),
    }
}
...................
...............................
fn build_spec(input: &DeriveInput) -> syn::Result<TokenStream> {
    match &input.data {
        syn::Data::Enum(enum_input) => {
            let name = &input.ident;
            let cnt = enum_input.variants.iter().count();
            ..................
            ..........................
            let width = (cnt as f32).log2() as usize;
            let fields: Vec<Ident> = enum_input
                .variants
                .iter()
                .map(|v| v.ident.clone())
                .collect();

            let name_str = format!("{}", name);

            Ok(quote!(
                impl Specifier for #name {
                    const BITS: usize = #width;
                    type GetterType = #name;
                    type SetterType = #name;

                    #[inline]
                    fn from_u64(val: u64) -> Self::GetterType {
                        match val{
                            #(x if x == Self::#fields as u64 => Self::#fields),*,
                            _ => {
                                panic!("error when convert {} from u64 to {}", val, #name_str);
                            }
                        }
                    }

                    #[inline]
                    fn into_u64(val: Self::SetterType) -> u64 {
                        val as u64
                    }
                }
				  ..............
                .....................
            ))
        }
        _ => Err(syn::Error::new_spanned(
            input,
            "only parse enum for BitfieldSpecifier",
        )),
    }
}

出于简化任务设计的原因，我记得额外添加了Copy, Clone trait

BitField任务七

如果任务六顺利完成，任务七也可以自然完成，本任务是提醒我们enum中赋部分的初值，有可能会让enum中某些成员的值会超出我们的设想值，举一个例子：

enum A {
   alpha,
   beta,
   ceta = 10,
   delta,
}

Rust中默认enum中成员值从0开始累加1，但中途可以额外设定某成员值为其他值，其后成员值为该新值的基础上继续累加，即A::delta的值位11。
任务作者提醒我们，如果赋予的初值不正确，会造成问题（将在任务9中展现）；

BitField任务八

加入检测enum中的某些成员数量应为2的幂（2,4,8,16...）
这个相对简单：

let cnt = enum_input.variants.iter().count();
if !cnt.is_power_of_two() {
   return Err(syn::Error::new(
      proc_macro2::Span::call_site(),
      "BitfieldSpecifier expected a number of variants which is a power of 2",
   ));
} 

BitField任务九

加入检测enum中的某些成员值超出范围

#[derive(BitfieldSpecifier)]
pub enum DeliveryMode {
    Fixed = 1,
    Lowest,
    SMI,
    RemoteRead,
    NMI,
    Init,
    Startup,
    External,   <--- 因为Fixed手动设定值从1开始，导致External的值为8，而不是正常的7
}

这里有一个相对简单的检测方法，上述DeliveryMode的成员数量为8个，2^3次方；则成员变量的值，无论怎么变化，都是在3bit内变化，如果enum中的成员的值有如下等式成立:
(DeliveryMode::Fixed | DeliveryMode::Lowest |.... ) & (0xF8) == 0

只是报错的时候跟任务四一样，信息没有被包装，跟题目要求的有一些不符合。

BitField任务十/十一

给被#[bitfield]修饰的结构体的一些字段加入 "#[bits=N]"的属性 （ineted attribute），指定该成员变量类型占用bits位数，如：

#[bitfield]
pub struct RedirectionTableEntry {
    #[bits = 1]
    trigger_mode: TriggerMode,
    #[bits = 3]
    delivery_mode: DeliveryMode,
    reserved: B4,
}

需要实际为有bits=N修饰的成员类型加入bits位数占用检测，CheckOccupiedAsItsDeclare；实作套路跟之前的任务类似；同样的也是报错信息不那么符合题目要求

BitField任务十二

之前任务如果完成正确，则本任务可顺利通过。

Bitfield任务的代码，详见这里