将标记返回给编译器

宏quote!的值是一个类型为safe_proc_macro2::TokenStream的表达式。同时，Rust过程宏期望返回的类型为proc_macro::TokenStream。

这两种类型的区别在于，proc_macro类型完全特定于过程宏，并且永远不会存在于过程宏之外的代码中，而proc_macro2类型可能存在于任何地方，包括测试和主.rs、build.rs等非宏代码。这就是为什么过程宏生态系统在很大程度上是围绕proc_macro2构建的，因为这确保了库是可单元测试的，并且可以在非宏上下文中访问。

两种类型都存在From转换，因此从一个过程宏返回quote!的输出通常看起来像tokens.into()或proc_macro::TokenStream::from(tokens)。

示例

组合引用片段

通常，你不会一次性构建完整的TokenStream。不同的部分可能来自不同的辅助函数。由quote!产生的标记本身实现了ToTokens，因此可以被插入到后续的quote!调用中，以构建最终结果。

let type_definition = quote! {...};
let methods = quote! {...};

let tokens = quote! {
    #type_definition
    #methods
};

构建标识符

假设我们有一个标识符ident，它来自宏输入的某个地方，并且我们需要以某种方式修改它以供宏输出。让我们考虑在标识符前面添加一个下划线。

简单地将标识符插入到下划线旁边不会产生连接它们的行为。下划线和标识符将继续作为两个单独的标记存在，就像你写了_ x一样。

// incorrect
quote! {
    let mut _#ident = 0;
}

解决方案是构建一个具有正确值的新标识符标记。由于这种情况非常常见，format_ident!宏提供了一个方便的实用程序来完成此操作。

let varname = format_ident!("_{}", ident);
quote! {
    let mut #varname = 0;
}

或者，可以使用Syn和proc-macro2提供的API直接构建标识符。这大致等同于上面的方法，但不会处理ident是原始标识符的情况。

let concatenated = format!("_{}", ident);
let varname = syn::Ident::new(&concatenated, ident.span());
quote! {
    let mut #varname = 0;
}

进行方法调用

假设我们的宏需要宏输入中指定的一些类型具有一个名为new的构造函数。我们有一个名为field_type的变量，其类型为syn::Type，并希望调用该构造函数。

// incorrect
quote! {
    let value = #field_type::new();
}

这有时能工作。如果 field_type 是 String，展开后的代码包含 String::new()，这是可以的。但如果 field_type 是类似 Vec<i32> 的东西，那么展开后的代码是 Vec<i32>::new()，这是无效的语法。在手工编写的Rust中，我们通常会写 Vec::<i32>::new()，但对于宏来说，下面的方法通常更方便。

quote! {
    let value = <#field_type>::new();
}

这展开为 <Vec<i32>>::new()，表现正确。

类似的模式适用于特性方法。

quote! {
    let value = <#field_type as core::default::Default>::default();
}

卫生性

任何插值令牌都保留了由它们的 ToTokens 实现提供的 Span 信息。在 quote! 调用中产生的令牌使用 Span::call_site() 进行标记。

可以通过 quote_spanned! 宏显式提供不同的范围。

非宏代码生成器

当在 build.rs 或 main.rs 中使用 quote 并将输出写入文件时，请考虑在写入之前让代码生成器通过 rustfmt 处理令牌（通过调用 rustfmt 二进制文件或通过将 rustfmt 库作为依赖项引入）。这样，如果生成的代码中发生错误，则方便人类阅读和调试。

请注意，当令牌写入文件时，不会保留任何类型的卫生或范围信息；从令牌到源代码的转换是有损的。

许可证