Crate quote [−] [src]

This crate provides the quote! macro for turning Rust syntax tree data structures into tokens of source code.

Procedural macros in Rust receive a stream of tokens as input, execute arbitrary Rust code to determine how to manipulate those tokens, and produce a stream of tokens to hand back to the compiler to compile into the caller's crate. Quasi-quoting is a solution to one piece of that -- producing tokens to return to the compiler.

The idea of quasi-quoting is that we write code that we treat as data. Within the quote! macro, we can write what looks like code to our text editor or IDE. We get all the benefits of the editor's brace matching, syntax highlighting, indentation, and maybe autocompletion. But rather than compiling that as code into the current crate, we can treat it as data, pass it around, mutate it, and eventually hand it back to the compiler as tokens to compile into the macro caller's crate.

This crate is motivated by the procedural macro use case, but is a general-purpose Rust quasi-quoting library and is not specific to procedural macros.

Version requirement: Quote supports any compiler version back to Rust's very first support for procedural macros in Rust 1.15.0.

[dependencies]
quote = "0.6"

#[macro_use]
extern crate quote;

Example

The following quasi-quoted block of code is something you might find in a procedural macro having to do with data structure serialization. The #var syntax performs interpolation of runtime variables into the quoted tokens. Check out the documentation of the quote! macro for more detail about the syntax. See also the quote_spanned! macro which is important for implementing hygienic procedural macros.

let tokens = quote! {
    struct SerializeWith #generics #where_clause {
        value: &'a #field_ty,
        phantom: ::std::marker::PhantomData<#item_ty>,
    }

    impl #generics serde::Serialize for SerializeWith #generics #where_clause {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            #path(self.value, serializer)
        }
    }

    SerializeWith {
        value: #value,
        phantom: ::std::marker::PhantomData::<#item_ty>,
    }
};

Recursion limit

The quote! macro relies on deep recursion so some large invocations may fail with "recursion limit reached" when you compile. If it fails, bump up the recursion limit by adding #![recursion_limit = "128"] to your crate. An even higher limit may be necessary for especially large invocations.

Macros

quote	The whole point.
quote_spanned	Same as `quote!`, but applies a given span to all tokens originating within the macro invocation.

Traits

ToTokens	Types that can be interpolated inside a `quote!` invocation.
TokenStreamExt	TokenStream extension trait with methods for appending tokens.