TokenStream
核心概念
TokenStream 是过程宏中代码的表示形式,它是一系列 token(词法单元)的序列。在 Rust 编译过程中,源代码首先被词法分析器分解为 token,然后这些 token 被组织成 TokenStream 传递给过程宏处理。过程宏接收 TokenStream 作为输入,返回 TokenStream 作为输出。
Rust 中有两个 TokenStream 类型:proc_macro::TokenStream(只能在过程宏 crate 中使用)和 proc_macro2::TokenStream(可以在任何 crate 中使用,方便测试和库开发)。syn 和 quote 都使用 proc_macro2::TokenStream,它可以与 proc_macro::TokenStream 互相转换。
TokenStream 由四种 TokenTree 组成:标识符(Ident)、字面量(Literal)、标点(Punct)和分组(Group,即被括号包裹的 token 序列)。
// TokenStream 的组成元素
//
// use proc_macro::TokenTree;
//
// enum TokenTree {
// Ident(Ident), // 标识符:foo, struct, pub
// Literal(Literal), // 字面量:42, "hello", 3.14
// Punct(Punct), // 标点:+ - * / = ; : ,
// Group(Group), // 分组:(...) [...] {...}
// }
//
// 例如代码 `fn add(a: i32) -> i32 { a + 1 }` 被分解为:
// Ident("fn")
// Ident("add")
// Group(Parenthesis, [Ident("a"), Punct(':'), Ident("i32")])
// Punct('-'), Punct('>')
// Ident("i32")
// Group(Brace, [Ident("a"), Punct('+'), Literal(1)])
fn main() {
println!("TokenStream = 一系列 TokenTree 的序列");
println!("TokenTree = Ident | Literal | Punct | Group");
}TokenStream 的基本操作
// === 创建 TokenStream ===
//
// // 从字符串解析
// let ts: TokenStream = "fn hello() {}".parse().unwrap();
//
// // 空的 TokenStream
// let empty = TokenStream::new();
//
// // 从 TokenTree 迭代器创建
// let ts = TokenStream::from_iter(vec![...]);
//
// // 用 quote! 宏创建(最常用)
// let ts = quote! { fn hello() { println!("hi"); } };
// === 遍历 TokenStream ===
//
// for token in ts {
// match token {
// TokenTree::Ident(ident) => println!("标识符: {}", ident),
// TokenTree::Literal(lit) => println!("字面量: {}", lit),
// TokenTree::Punct(punct) => println!("标点: {}", punct),
// TokenTree::Group(group) => {
// println!("分组({:?}): {}", group.delimiter(), group.stream());
// }
// }
// }
// === 转换 ===
//
// // proc_macro::TokenStream → proc_macro2::TokenStream
// let ts2: proc_macro2::TokenStream = ts.into();
//
// // proc_macro2::TokenStream → proc_macro::TokenStream
// let ts: proc_macro::TokenStream = ts2.into();
//
// // TokenStream → 字符串
// let s = ts.to_string();
fn main() {
println!("TokenStream 支持创建、遍历、转换等操作");
}Span(位置信息)
// 每个 TokenTree 都有一个 Span,记录它在源代码中的位置
// Span 用于生成精确的编译错误信息
// === Span 的类型 ===
//
// Span::call_site() // 调用站点:错误指向宏调用的位置
// Span::mixed_site() // 混合站点:声明宏的默认行为
// Span::def_site() // 定义站点:错误指向宏定义的位置(nightly only)
// === 在错误报告中使用 Span ===
//
// use syn::Error;
//
// // 创建带位置的错误
// let err = Error::new(some_token.span(), "这里有问题");
// return err.to_compile_error().into();
//
// // 使用 new_spanned 从整个语法节点获取 span
// let err = Error::new_spanned(&field, "字段类型不支持");
// return err.to_compile_error().into();
// === 设置生成代码的 Span ===
//
// use quote::quote_spanned;
//
// // 让生成的代码指向特定位置
// let expanded = quote_spanned! { field.span() =>
// impl SomeTrait for #name { ... }
// };
fn main() {
println!("Span 让编译错误能指向正确的源代码位置");
}proc_macro2 与 proc_macro
// proc_macro2 是 proc_macro 的包装库
// 它解决了一个问题:proc_macro 类型只能在过程宏 crate 内部使用
// proc_macro2 的类型可以在任何 crate 中使用
// === 为什么需要 proc_macro2 ===
//
// 1. syn 和 quote 内部使用 proc_macro2
// 2. 可以在普通 crate 中编写辅助函数和测试
// 3. 支持在 proc-macro crate 外部操作 token
// === 两者的关系 ===
//
// proc_macro::TokenStream ←→ proc_macro2::TokenStream
// proc_macro::TokenTree ←→ proc_macro2::TokenTree
// proc_macro::Ident ←→ proc_macro2::Ident
// proc_macro::Literal ←→ proc_macro2::Literal
// proc_macro::Punct ←→ proc_macro2::Punct
// proc_macro::Group ←→ proc_macro2::Group
// proc_macro::Span ←→ proc_macro2::Span
// === 典型的过程宏入口 ===
//
// #[proc_macro_derive(MyMacro)]
// pub fn my_macro(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
// // 立即转换为 proc_macro2 类型
// let input = parse_macro_input!(input as DeriveInput);
//
// // 内部全部使用 proc_macro2 类型
// let expanded: proc_macro2::TokenStream = generate_code(&input);
//
// // 返回时转换回 proc_macro 类型
// expanded.into()
// }
fn main() {
println!("过程宏入口用 proc_macro::TokenStream");
println!("内部处理用 proc_macro2::TokenStream");
}| 特性 | proc_macro | proc_macro2 |
|---|---|---|
| 使用位置 | 仅 proc-macro crate | 任何 crate |
| 标准库提供 | 是 | 否(第三方 crate) |
| syn/quote 使用 | 否 | 是 |
| 可测试 | 难 | 容易 |
| 互相转换 | .into() | .into() |
基本示例
// 展示如何手动构建和分析 TokenStream(概念代码)
// === 手动构建 TokenStream ===
//
// use proc_macro2::{TokenStream, TokenTree, Ident, Literal, Punct, Spacing, Span};
//
// fn build_assignment() -> TokenStream {
// let mut tokens = TokenStream::new();
//
// // let x = 42;
// tokens.extend([
// TokenTree::Ident(Ident::new("let", Span::call_site())),
// TokenTree::Ident(Ident::new("x", Span::call_site())),
// TokenTree::Punct(Punct::new('=', Spacing::Alone)),
// TokenTree::Literal(Literal::i32_unsuffixed(42)),
// TokenTree::Punct(Punct::new(';', Spacing::Alone)),
// ]);
//
// tokens
// }
// === 用 quote! 构建(更简单)===
//
// use quote::quote;
//
// let name = Ident::new("x", Span::call_site());
// let value = 42;
// let tokens = quote! {
// let #name = #value;
// };
// // 生成:let x = 42;
// === 分析 TokenStream ===
//
// fn analyze(ts: &TokenStream) {
// for tt in ts.clone() {
// match tt {
// TokenTree::Ident(i) => println!("Ident: {}", i),
// TokenTree::Literal(l) => println!("Literal: {}", l),
// TokenTree::Punct(p) => println!("Punct: '{}'", p.as_char()),
// TokenTree::Group(g) => {
// println!("Group {:?}:", g.delimiter());
// analyze(&g.stream());
// }
// }
// }
// }
fn main() {
println!("手动构建 TokenStream 繁琐但精确");
println!("quote! 宏是构建 TokenStream 的首选方式");
println!("syn 是解析 TokenStream 的首选方式");
}常见问题
问题一:TokenStream 和 AST 有什么区别?
TokenStream 是扁平的 token 序列,只有词法层面的结构(通过 Group 提供嵌套)。AST(抽象语法树,如 syn::DeriveInput)是有语义结构的树,知道哪个是类型名、哪个是字段、哪个是表达式。syn 将 TokenStream 解析为 AST,quote 将代码模板转换回 TokenStream。
问题二:为什么 quote! 生成的是 proc_macro2::TokenStream?
因为 proc_macro::TokenStream 只能在过程宏上下文中创建和使用。quote! 需要能在任何地方工作(包括测试、辅助函数中),所以使用 proc_macro2::TokenStream。返回时用 .into() 转换。
问题三:TokenStream 可以从字符串创建吗?
可以。"fn foo() {}".parse::<TokenStream>() 可以将字符串解析为 TokenStream。但这种方式没有类型检查,拼写错误只会在宏使用者编译时才被发现。用 quote! 更安全。
问题四:空的 TokenStream 会怎样?
派生宏返回空 TokenStream 表示不追加任何代码。属性宏或函数宏返回空 TokenStream 表示删除原始项(替换为空)。
适用场景
- 过程宏的输入输出:所有过程宏都通过 TokenStream 交互
- 代码分析:遍历 token 进行检查或提取信息
- 代码生成:构建新的代码片段
- 宏调试:打印 TokenStream 查看宏的输入内容
注意事项
- 过程宏入口用
proc_macro::TokenStream,内部用proc_macro2::TokenStream - 用
syn解析 TokenStream 为结构化的 AST - 用
quote!从代码模板生成 TokenStream - Span 信息对编译错误的定位至关重要
- 手动构建 TokenStream 容易出错,优先用
quote! - TokenStream 的
to_string()可用于调试
总结
TokenStream 是过程宏中代码的表示形式,由 Ident(标识符)、Literal(字面量)、Punct(标点)和 Group(分组)四种 TokenTree 组成。proc_macro::TokenStream 只能在过程宏 crate 中使用,proc_macro2::TokenStream 可以在任何 crate 中使用,两者可以互相转换。syn 将 TokenStream 解析为结构化的 AST(如 DeriveInput),quote! 将代码模板转换为 TokenStream。每个 token 都带有 Span 位置信息,用于生成精确的编译错误。实际开发中很少直接操作 TokenStream,而是通过 syn 和 quote 进行高级别的解析和生成。