quote! 宏
核心概念
quote! 是过程宏开发中最重要的代码生成工具,由 quote crate 提供。它的作用是将 Rust 代码模板转换为 proc_macro2::TokenStream。在 quote! 块中,你可以写看起来像普通 Rust 代码的内容,但它不会被编译为当前 crate 的代码,而是被转换为 token 数据,最终作为过程宏的输出返回给编译器。
quote! 使用 #var 语法进行变量插值(类似声明宏中的 $var),用 #( ... )* 进行重复展开(类似声明宏中的 $( ... )*)。任何实现了 ToTokens trait 的类型都可以被插值,包括 Rust 基本类型、syn 的语法节点、以及其他 TokenStream。
// 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 插值变量,用 #(...)* 重复展开");
}变量插值
// === #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! 生成标识符
// 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! 动态构建标识符名称");
}重复展开
// #( ... )* 对集合进行重复展开
// 类似声明宏中的 $( ... )*
//
// 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!
// 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! | 用户指定 | 指定的源码位置 | 需要精确错误定位 |
基本示例
// 展示 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。