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 序列)。

rust
// 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 的基本操作 ​

rust
// === 创建 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(位置信息) ​

rust
// 每个 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 ​

rust
// 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_macroproc_macro2
使用位置仅 proc-macro crate任何 crate
标准库提供是否(第三方 crate)
syn/quote 使用否是
可测试难容易
互相转换.into().into()

基本示例 ​

rust
// 展示如何手动构建和分析 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 进行高级别的解析和生成。