Rust宏扩展库paperclip-macros使用指南

简介

paperclip-macros是一个简化Rust过程宏开发的库，它提供了更友好的API来编写声明式宏和过程宏，减少样板代码，使宏开发更加直观。

主要特性

1. 简化过程宏定义语法
2. 提供更友好的错误报告
3. 支持声明式宏和属性宏
4. 内置常用模式匹配和代码生成工具

安装

在Cargo.toml中添加依赖：

[dependencies]
paperclip-macros = "0.1"

基本使用方法

1. 定义属性宏

use paperclip_macros::attribute_macro;

#[attribute_macro]
pub fn my_attribute_macro(attr: TokenStream, item: TokenStream) -> TokenStream {
    // 处理逻辑
    quote! {
        #item
    }
}

2. 定义派生宏

use paperclip_macros::derive_macro;

#[derive_macro]
pub fn my_derive_macro(input: TokenStream) -> TokenStream {
    // 处理逻辑
    quote! {
        impl SomeTrait for #input {
            // 生成的实现
        }
    }
}

3. 使用声明式宏

use paperclip_macros::decl_macro;

decl_macro! {
    ($name:ident) => {
        struct $name;
    }
}

// 使用
my_macro!(MyStruct); // 生成 struct MyStruct;

高级用法示例

自定义错误报告

use paperclip_macros::{attribute_macro, Diagnostic};

#[attribute_macro]
pub fn validate_struct(attr: TokenStream, item: TokenStream) -> TokenStream {
    // 解析输入
    let input = parse_macro_input!(item as DeriveInput);
    
    // 检查结构体是否有命名字段
    if let Data::Struct(data) = &input.data {
        if data.fields.iter().all(|f| f.ident.is_none()) {
            Diagnostic::error("This attribute requires named fields")
                .span(input.span())
                .emit();
            return TokenStream::new();
        }
    }
    
    // 生成代码...
}

模式匹配辅助

use paperclip_macros::{attribute_macro, Pattern};

#[attribute_macro]
pub fn auto_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
    let input = parse_macro_input!(item as DeriveInput);
    
    // 使用模式匹配简化处理
    match Pattern::from(input) {
        Pattern::Struct(name, fields) => {
            // 处理结构体
        }
        Pattern::Enum(name, variants) => {
            // 处理枚举
        }
        _ => {
            Diagnostic::error("Unsupported item type").emit();
            return TokenStream::new();
        }
    }
}

实际应用示例

生成Builder模式

use paperclip-macros::{derive_macro, Pattern};

#[derive_macro]
pub fn builder(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    let Pattern::Struct(name, fields) = Pattern::from(input) else {
        panic!("Builder macro only works on structs");
    };
    
    let builder_name = format_ident!("{}Builder", name);
    let setter_methods = fields.iter().map(|f| {
        let field_name = &f.ident;
        let field_type = &f.ty;
        quote! {
            pub fn #field_name(mut self, value: #field_type) -> Self {
                self.#field_name = Some(value);
                self
            }
        }
    });
    
    quote! {
        pub struct #builder_name {
            #( #fields: Option<#field_type> ),*
        }
        
        impl #builder_name {
            #( #setter_methods )*
            
            pub fn build(self) -> Result<#name, String> {
                Ok(#name {
                    #( #field_name: self.#field_name.ok_or(format!("field {} not set", stringify!(#field_name)))? ),*
                })
            }
        }
        
        impl #name {
            pub fn builder() -> #builder_name {
                #builder_name {
                    #( #field_name: None ),*
                }
            }
        }
    }
}

完整示例Demo

下面是一个完整的Builder模式实现示例，展示如何使用paperclip-macros：

use paperclip_macros::{derive_macro, Pattern};
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[derive_macro]
pub fn builder(input: TokenStream) -> TokenStream {
    // 解析输入的结构体定义
    let input = parse_macro_input!(input as DeriveInput);
    
    // 使用Pattern匹配结构体
    let Pattern::Struct(struct_name, fields) = Pattern::from(input) else {
        panic!("Builder宏只能用于结构体");
    };
    
    // 生成Builder结构体名称
    let builder_name = format_ident!("{}Builder", struct_name);
    
    // 为每个字段生成setter方法
    let setter_methods = fields.iter().map(|f| {
        let field_name = &f.ident;
        let field_type = &f.ty;
        quote! {
            pub fn #field_name(mut self, value: #field_type) -> Self {
                self.#field_name = Some(value);
                self
            }
        }
    });
    
    // 生成完整的Builder实现代码
    let expanded = quote! {
        // 定义Builder结构体
        pub struct #builder_name {
            #( #fields: Option<#field_type> ),*
        }
        
        // 实现Builder方法
        impl #builder_name {
            #( #setter_methods )*
            
            // build方法用于最终构建目标结构体
            pub fn build(self) -> Result<#struct_name, String> {
                Ok(#struct_name {
                    #( #field_name: self.#field_name.ok_or(format!("字段{}未设置", stringify!(#field_name)))? ),*
                })
            }
        }
        
        // 为原结构体添加builder()方法
        impl #struct_name {
            pub fn builder() -> #builder_name {
                #builder_name {
                    #( #field_name: None ),*
                }
            }
        }
    };
    
    // 返回生成的TokenStream
    expanded.into()
}

使用示例：

#[derive(Builder)]
struct User {
    id: u64,
    name: String,
    email: String,
}

fn main() {
    let user = User::builder()
        .id(1)
        .name("Alice".to_string())
        .email("alice@example.com".to_string())
        .build()
        .unwrap();
    
    println!("User created: {:?}", user);
}

注意事项

1. paperclip-macros仍在活跃开发中，API可能会有变化
2. 错误处理比原生宏更友好，但仍需谨慎处理边界情况
3. 对于复杂宏，性能可能略低于手写实现

总结

paperclip-macros通过提供更高级的抽象和工具集，显著简化了Rust宏开发过程，特别适合需要快速原型开发或对宏开发不太熟悉的开发者。