quote! 宏 ​

核心概念 ​

quote! 是过程宏开发中最重要的代码生成工具,由 quote crate 提供。它的作用是将 Rust 代码模板转换为 proc_macro2::TokenStream。在 quote! 块中,你可以写看起来像普通 Rust 代码的内容,但它不会被编译为当前 crate 的代码,而是被转换为 token 数据,最终作为过程宏的输出返回给编译器。

quote! 使用 #var 语法进行变量插值(类似声明宏中的 $var),用 #( ... )* 进行重复展开(类似声明宏中的 $( ... )*)。任何实现了 ToTokens trait 的类型都可以被插值,包括 Rust 基本类型、syn 的语法节点、以及其他 TokenStream。

rust
// quote! 的基本用法(过程宏 crate 中)
//
// use quote::quote;
//
// // 简单的代码生成
// let tokens = quote! {
//     fn hello() {
//         println!("Hello from generated code!");
//     }
// };
//
// // 变量插值
// let name = format_ident!("my_function");
// let value = 42;
// let tokens = quote! {
//     fn #name() -> i32 {
//         #value
//     }
// };
// // 生成: fn my_function() -> i32 { 42 }

fn main() {
    println!("quote! 将代码模板转换为 TokenStream");
    println!("用 #var 插值变量,用 #(...)* 重复展开");
}

变量插值 ​

rust
// === #var 插值 ===
//
// use quote::quote;
// use syn::Ident;
// use proc_macro2::Span;
//
// let struct_name = Ident::new("User", Span::call_site());
// let field_name = Ident::new("name", Span::call_site());
// let field_type = Ident::new("String", Span::call_site());
//
// let tokens = quote! {
//     struct #struct_name {
//         #field_name: #field_type,
//     }
// };
// // 生成: struct User { name: String, }

// === 插值不同类型 ===
//
// // 整数
// let count: usize = 10;
// let tokens = quote! { let x = #count; };
// // 生成: let x = 10usize;
//
// // 字符串字面量
// let msg = "hello";
// let tokens = quote! { println!(#msg); };
// // 生成: println!("hello");
//
// // 布尔值
// let flag = true;
// let tokens = quote! { let b = #flag; };
// // 生成: let b = true;
//
// // 其他 TokenStream
// let inner = quote! { x + y };
// let outer = quote! { let result = #inner; };
// // 生成: let result = x + y;

fn main() {
    println!("任何实现 ToTokens 的类型都可以用 #var 插值");
}

format_ident! 生成标识符 ​

rust
// format_ident! 用来在编译时动态生成标识符名称
// 类似 format! 但返回 Ident 而不是 String
//
// use quote::format_ident;
//
// let name = "User";
// let getter = format_ident!("get_{}", name.to_lowercase());
// // getter = Ident("get_user")
//
// let setter = format_ident!("set_{}", name.to_lowercase());
// // setter = Ident("set_user")
//
// let tokens = quote! {
//     fn #getter(&self) -> &str { &self.name }
//     fn #setter(&mut self, val: String) { self.name = val; }
// };

// === 批量生成标识符 ===
//
// let fields = vec!["name", "age", "email"];
// let getters: Vec<_> = fields.iter()
//     .map(|f| format_ident!("get_{}", f))
//     .collect();
// let field_idents: Vec<_> = fields.iter()
//     .map(|f| format_ident!("{}", f))
//     .collect();
//
// let tokens = quote! {
//     impl User {
//         #(
//             fn #getters(&self) -> &str {
//                 &self.#field_idents
//             }
//         )*
//     }
// };

fn main() {
    println!("format_ident! 动态构建标识符名称");
}

重复展开 ​

rust
// #( ... )* 对集合进行重复展开
// 类似声明宏中的 $( ... )*
//
// use quote::quote;
//
// // === 简单重复 ===
// let fields = vec!["name", "age", "email"];
// let tokens = quote! {
//     #( println!("{}", #fields); )*
// };
// // 生成:
// // println!("name");
// // println!("age");
// // println!("email");

// === 带分隔符的重复 ===
// let values = vec![1, 2, 3, 4, 5];
// let tokens = quote! {
//     let arr = [#( #values ),*];
// };
// // 生成: let arr = [1, 2, 3, 4, 5];

// === 多变量同步重复 ===
// let names = vec![
//     format_ident!("x"),
//     format_ident!("y"),
//     format_ident!("z"),
// ];
// let types = vec![
//     quote! { i32 },
//     quote! { f64 },
//     quote! { String },
// ];
//
// let tokens = quote! {
//     struct Foo {
//         #( #names: #types, )*
//     }
// };
// // 生成:
// // struct Foo {
// //     x: i32,
// //     y: f64,
// //     z: String,
// // }

// === 嵌套重复 ===
// 目前 quote! 不直接支持嵌套重复
// 需要先将内层展开为 TokenStream,再在外层插值

fn main() {
    println!("#(...)* 展开集合,#(...),* 带逗号分隔");
}

quote_spanned! ​

rust
// quote_spanned! 让生成的代码指向特定的源码位置
// 当生成的代码有编译错误时,错误信息会指向正确的位置
//
// use quote::quote_spanned;
// use syn::spanned::Spanned;
//
// // 假设 field 是从输入中解析出的字段
// let field_span = field.span();
// let field_name = &field.ident;
// let field_type = &field.ty;
//
// // 如果 field_type 没有实现 Default,
// // 错误信息会指向用户代码中该字段的位置
// let tokens = quote_spanned! { field_span =>
//     let #field_name: #field_type = Default::default();
// };

// === quote! vs quote_spanned! ===
//
// quote! 生成的代码使用 call_site span(错误指向宏调用处)
// quote_spanned! 生成的代码使用指定的 span(错误指向具体位置)
//
// 好的过程宏应该尽可能使用 quote_spanned!
// 让错误信息指向用户代码中真正有问题的地方

fn main() {
    println!("quote_spanned! 让编译错误指向正确的源码位置");
}
宏Span 来源错误指向使用场景
quote!Span::call_site()宏调用位置一般代码生成
quote_spanned!用户指定指定的源码位置需要精确错误定位

基本示例 ​

rust
// 展示 quote! 在实际派生宏中的综合运用(概念代码)

// === 一个完整的 Builder 派生宏 ===
//
// use proc_macro::TokenStream;
// use quote::{quote, format_ident};
// use syn::{parse_macro_input, DeriveInput, Data, Fields};
//
// #[proc_macro_derive(Builder)]
// pub fn builder_derive(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     let name = &input.ident;
//     let builder_name = format_ident!("{}Builder", name);
//
//     // 提取命名字段
//     let fields = match &input.data {
//         Data::Struct(data) => match &data.fields {
//             Fields::Named(fields) => &fields.named,
//             _ => panic!("Builder 只支持命名字段结构体"),
//         },
//         _ => panic!("Builder 只支持结构体"),
//     };
//
//     // 收集字段信息
//     let field_names: Vec<_> = fields.iter()
//         .map(|f| f.ident.as_ref().unwrap())
//         .collect();
//     let field_types: Vec<_> = fields.iter()
//         .map(|f| &f.ty)
//         .collect();
//
//     let expanded = quote! {
//         // Builder 结构体:所有字段用 Option 包裹
//         pub struct #builder_name {
//             #( #field_names: Option<#field_types>, )*
//         }
//
//         impl #builder_name {
//             // 每个字段的 setter 方法
//             #(
//                 pub fn #field_names(mut self, val: #field_types) -> Self {
//                     self.#field_names = Some(val);
//                     self
//                 }
//             )*
//
//             // build 方法
//             pub fn build(self) -> Result<#name, String> {
//                 Ok(#name {
//                     #(
//                         #field_names: self.#field_names
//                             .ok_or_else(|| format!("缺少字段: {}", stringify!(#field_names)))?,
//                     )*
//                 })
//             }
//         }
//
//         impl #name {
//             pub fn builder() -> #builder_name {
//                 #builder_name {
//                     #( #field_names: None, )*
//                 }
//             }
//         }
//     };
//
//     TokenStream::from(expanded)
// }

// === 使用效果 ===
// #[derive(Builder)]
// struct Server {
//     host: String,
//     port: u16,
// }
//
// fn main() {
//     let server = Server::builder()
//         .host("localhost".to_string())
//         .port(8080)
//         .build()
//         .unwrap();
// }

fn main() {
    println!("quote! 是过程宏代码生成的核心工具");
    println!("配合 syn 解析输入,quote! 生成输出");
    println!("format_ident! 动态构建标识符");
    println!("#(...)* 处理重复的字段/方法生成");
}

常见问题 ​

问题一:quote! 生成的类型是什么?

quote! 返回 proc_macro2::TokenStream。在过程宏入口函数中需要用 .into() 或 TokenStream::from() 转换为 proc_macro::TokenStream。

问题二:quote! 中怎么插入泛型的尖括号?

如果直接写 #ty::new() 且 ty 是 Vec<i32> 这样的泛型,会生成 Vec<i32>::new() 导致语法错误。应该用 turbofish 语法或前置尖括号:<#ty>::new()。

问题三:quote! 中怎么生成字符串字面量?

直接插值字符串变量即可。let s = "hello"; quote! { let x = #s; } 会生成 let x = "hello";。如果需要从 Ident 生成字符串,用 stringify! 或先调用 .to_string()。

问题四:多个 quote! 块可以组合吗?

可以。quote! 返回的 TokenStream 实现了 ToTokens,可以在另一个 quote! 中用 #var 插值。也可以用 TokenStream::extend() 手动拼接。

适用场景 ​

  • 过程宏的代码输出:几乎所有过程宏都用 quote! 生成输出
  • 动态 impl 块生成:为不同类型生成不同的实现
  • 批量方法生成:用 #(...)* 为每个字段生成 getter/setter
  • 条件代码生成:在 Rust 逻辑中决定 quote! 的内容

注意事项 ​

  • quote! 返回 proc_macro2::TokenStream,需要 .into() 转换
  • 用 #var 插值变量,用 #(...)* 展开集合
  • format_ident! 用来动态构建标识符
  • quote_spanned! 提供精确的错误定位
  • 泛型类型插值用 <#ty>::method() 避免语法问题
  • 重复展开中的多个变量必须长度一致

总结 ​

quote! 是过程宏代码生成的核心工具,将 Rust 代码模板转换为 proc_macro2::TokenStream。通过 #var 语法插值变量(任何实现 ToTokens 的类型),通过 #(...)* 展开集合实现重复代码生成。format_ident! 动态构建标识符名称,quote_spanned! 让生成代码的编译错误指向正确的源码位置。quote! 通常与 syn(解析输入)配合使用,形成过程宏的标准开发模式:syn 解析输入 TokenStream 为 AST,业务逻辑处理 AST,quote! 将结果转换回 TokenStream。