Macro quote

Source

macro_rules! quote {
    ($($proc_macro:tt)*) => { ... };
}

Expand description

The whole point.

Performs variable interpolation against the input and produces it as TokenStream. For returning tokens to the compiler in a procedural macro, use into() to build a TokenStream.

§Interpolation

Variable interpolation is done with #var (similar to $var in macro_rules! macros). This grabs the var variable that is currently in scope and inserts it in that location in the output tokens. Any type implementing the ToTokens trait can be interpolated. This includes most Rust primitive types as well as most of the syntax tree types from the Syn crate.

Repetition is done using #(...)* or #(...),* again similar to macro_rules!. This iterates through the elements of any variable interpolated within the repetition and inserts a copy of the repetition body for each one.

#(#var)* — no separators
#(#var),* — the character before the asterisk is used as a separator
#( struct #var; )* — the repetition can contain other tokens
#( #k => println!("{}", #v), )* — even multiple interpolations
#(let #var = self.#var;)* - the same variable can be used more than once

The proc_quote::Repeat trait defines which types are allowed to be interpolated inside a repition pattern.

Which types that implement the following traits do Repeat:

Iterator<T> consumes the iterator, iterating through every element.
Borrow<[T]> (includes Vec, array, and slice) iterates with the slice::iter method, thus not consuming the original data.
ToTokens, interpolates the variable in every iteration.

Which types do NOT Repeat:

IntoIterator, to avoid ambiguity (Ex. “Which behavior would have been used for Vec, which implements both IntoIterator and Borrow<[T]>?”; “Which behavior would have been used for TokenStream, which implements both IntoIterator and ToTokens?”). To use the iterator, you may call IntoIterator::into_iter explicitly.
Ambiguous types that implement at least two of the Repeat traits. In the very unlikely case this happens, disambiguate the type by wrapping it under some structure that only implements the trait you desire to use.

§Hygiene

Any interpolated tokens preserve the Span information provided by their ToTokens implementation. Tokens that originate within the quote! invocation are spanned with Span::call_site().

A different span can be provided through the quote_spanned! macro.

§Return type

The macro evaluates to an expression of type proc_macro2::TokenStream. Meanwhile Rust procedural macros are expected to return the type proc_macro::TokenStream.

The difference between the two types is that proc_macro types are entirely specific to procedural macros and cannot ever exist in code outside of a procedural macro, while proc_macro2 types may exist anywhere including tests and non-macro code like main.rs and build.rs. This is why even the procedural macro ecosystem is largely built around proc_macro2, because that ensures the libraries are unit testable and accessible in non-macro contexts.

There is a From-conversion in both directions so returning the output of quote! from a procedural macro usually looks like tokens.into() or proc_macro::TokenStream::from(tokens).

§Examples

§Procedural macro

The structure of a basic procedural macro is as follows. Refer to the Syn crate for further useful guidance on using quote! as part of a procedural macro.

extern crate proc_macro;

use proc_macro::TokenStream;
use quote::quote;

#[proc_macro_derive(HeapSize)]
pub fn derive_heap_size(input: TokenStream) -> TokenStream {
    // Parse the input and figure out what implementation to generate...
    let name = /* ... */;
    let expr = /* ... */;

    let expanded = quote! {
        // The generated impl.
        impl heapsize::HeapSize for #name {
            fn heap_size_of_children(&self) -> usize {
                #expr
            }
        }
    };

    // Hand the output tokens back to the compiler.
    TokenStream::from(expanded)
}

§Combining quoted fragments

Usually you don’t end up constructing an entire final TokenStream in one piece. Different parts may come from different helper functions. The tokens produced by quote! themselves implement ToTokens and so can be interpolated into later quote! invocations to build up a final result.

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

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

§Constructing identifiers

Suppose we have an identifier ident which came from somewhere in a macro input and we need to modify it in some way for the macro output. Let’s consider prepending the identifier with an underscore.

Simply interpolating the identifier next to an underscore will not have the behavior of concatenating them. The underscore and the identifier will continue to be two separate tokens as if you had written _ x.

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

The solution is to perform token-level manipulations using the APIs provided by Syn and proc-macro2.

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

§Making method calls

Let’s say our macro requires some type specified in the macro input to have a constructor called new. We have the type in a variable called field_type of type syn::Type and want to invoke the constructor.

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

This works only sometimes. If field_type is String, the expanded code contains String::new() which is fine. But if field_type is something like Vec<i32> then the expanded code is Vec<i32>::new() which is invalid syntax. Ordinarily in handwritten Rust we would write Vec::<i32>::new() but for macros often the following is more convenient.

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

This expands to <Vec<i32>>::new() which behaves correctly.

A similar pattern is appropriate for trait methods.

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

Macro quoteCopy item path