rust: quote: import crate

This is a subset of the Rust `quote` crate, version 1.0.40 (released
2025-03-12), licensed under "Apache-2.0 OR MIT", from:

    https://github.com/dtolnay/quote/raw/1.0.40/src

The files are copied as-is, with no modifications whatsoever (not even
adding the SPDX identifiers).

For copyright details, please see:

    https://github.com/dtolnay/quote/blob/1.0.40/README.md#license
    https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-APACHE
    https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-MIT

The next patch modifies these files as needed for use within the
kernel. This patch split allows reviewers to double-check the import
and to clearly see the differences introduced.

The following script may be used to verify the contents:

    for path in $(cd rust/quote/ && find . -type f -name '*.rs'); do
        curl --silent --show-error --location \
            https://github.com/dtolnay/quote/raw/1.0.40/src/$path \
            | diff --unified rust/quote/$path - && echo $path: OK
    done

Reviewed-by: Gary Guo <gary@garyguo.net>
Tested-by: Gary Guo <gary@garyguo.net>
Tested-by: Jesung Yang <y.j3ms.n@gmail.com>
Link: https://patch.msgid.link/20251124151837.2184382-12-ojeda@kernel.org
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

7 files changed, 2633 insertions, 0 deletions

diff --git a/rust/quote/ext.rs b/rust/quote/ext.rs
new file mode 100644
index 000000000000..92c2315b182d
--- /dev/null
+++ b/rust/quote/ext.rs
@@ -0,0 +1,110 @@
+use super::ToTokens;
+use core::iter;
+use proc_macro2::{TokenStream, TokenTree};
+
+/// TokenStream extension trait with methods for appending tokens.
+///
+/// This trait is sealed and cannot be implemented outside of the `quote` crate.
+pub trait TokenStreamExt: private::Sealed {
+    /// For use by `ToTokens` implementations.
+    ///
+    /// Appends the token specified to this list of tokens.
+    fn append<U>(&mut self, token: U)
+    where
+        U: Into<TokenTree>;
+
+    /// For use by `ToTokens` implementations.
+    ///
+    /// ```
+    /// # use quote::{quote, TokenStreamExt, ToTokens};
+    /// # use proc_macro2::TokenStream;
+    /// #
+    /// struct X;
+    ///
+    /// impl ToTokens for X {
+    ///     fn to_tokens(&self, tokens: &mut TokenStream) {
+    ///         tokens.append_all(&[true, false]);
+    ///     }
+    /// }
+    ///
+    /// let tokens = quote!(#X);
+    /// assert_eq!(tokens.to_string(), "true false");
+    /// ```
+    fn append_all<I>(&mut self, iter: I)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens;
+
+    /// For use by `ToTokens` implementations.
+    ///
+    /// Appends all of the items in the iterator `I`, separated by the tokens
+    /// `U`.
+    fn append_separated<I, U>(&mut self, iter: I, op: U)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens,
+        U: ToTokens;
+
+    /// For use by `ToTokens` implementations.
+    ///
+    /// Appends all tokens in the iterator `I`, appending `U` after each
+    /// element, including after the last element of the iterator.
+    fn append_terminated<I, U>(&mut self, iter: I, term: U)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens,
+        U: ToTokens;
+}
+
+impl TokenStreamExt for TokenStream {
+    fn append<U>(&mut self, token: U)
+    where
+        U: Into<TokenTree>,
+    {
+        self.extend(iter::once(token.into()));
+    }
+
+    fn append_all<I>(&mut self, iter: I)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens,
+    {
+        for token in iter {
+            token.to_tokens(self);
+        }
+    }
+
+    fn append_separated<I, U>(&mut self, iter: I, op: U)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens,
+        U: ToTokens,
+    {
+        for (i, token) in iter.into_iter().enumerate() {
+            if i > 0 {
+                op.to_tokens(self);
+            }
+            token.to_tokens(self);
+        }
+    }
+
+    fn append_terminated<I, U>(&mut self, iter: I, term: U)
+    where
+        I: IntoIterator,
+        I::Item: ToTokens,
+        U: ToTokens,
+    {
+        for token in iter {
+            token.to_tokens(self);
+            term.to_tokens(self);
+        }
+    }
+}
+
+mod private {
+    use proc_macro2::TokenStream;
+
+    pub trait Sealed {}
+
+    impl Sealed for TokenStream {}
+}
diff --git a/rust/quote/format.rs b/rust/quote/format.rs
new file mode 100644
index 000000000000..ec0bbf38ba37
--- /dev/null
+++ b/rust/quote/format.rs
@@ -0,0 +1,168 @@
+/// Formatting macro for constructing `Ident`s.
+///
+/// <br>
+///
+/// # Syntax
+///
+/// Syntax is copied from the [`format!`] macro, supporting both positional and
+/// named arguments.
+///
+/// Only a limited set of formatting traits are supported. The current mapping
+/// of format types to traits is:
+///
+/// * `{}` ⇒ [`IdentFragment`]
+/// * `{:o}` ⇒ [`Octal`](std::fmt::Octal)
+/// * `{:x}` ⇒ [`LowerHex`](std::fmt::LowerHex)
+/// * `{:X}` ⇒ [`UpperHex`](std::fmt::UpperHex)
+/// * `{:b}` ⇒ [`Binary`](std::fmt::Binary)
+///
+/// See [`std::fmt`] for more information.
+///
+/// <br>
+///
+/// # IdentFragment
+///
+/// Unlike `format!`, this macro uses the [`IdentFragment`] formatting trait by
+/// default. This trait is like `Display`, with a few differences:
+///
+/// * `IdentFragment` is only implemented for a limited set of types, such as
+///   unsigned integers and strings.
+/// * [`Ident`] arguments will have their `r#` prefixes stripped, if present.
+///
+/// [`IdentFragment`]: crate::IdentFragment
+/// [`Ident`]: proc_macro2::Ident
+///
+/// <br>
+///
+/// # Hygiene
+///
+/// The [`Span`] of the first `Ident` argument is used as the span of the final
+/// identifier, falling back to [`Span::call_site`] when no identifiers are
+/// provided.
+///
+/// ```
+/// # use quote::format_ident;
+/// # let ident = format_ident!("Ident");
+/// // If `ident` is an Ident, the span of `my_ident` will be inherited from it.
+/// let my_ident = format_ident!("My{}{}", ident, "IsCool");
+/// assert_eq!(my_ident, "MyIdentIsCool");
+/// ```
+///
+/// Alternatively, the span can be overridden by passing the `span` named
+/// argument.
+///
+/// ```
+/// # use quote::format_ident;
+/// # const IGNORE_TOKENS: &'static str = stringify! {
+/// let my_span = /* ... */;
+/// # };
+/// # let my_span = proc_macro2::Span::call_site();
+/// format_ident!("MyIdent", span = my_span);
+/// ```
+///
+/// [`Span`]: proc_macro2::Span
+/// [`Span::call_site`]: proc_macro2::Span::call_site
+///
+/// <p><br></p>
+///
+/// # Panics
+///
+/// This method will panic if the resulting formatted string is not a valid
+/// identifier.
+///
+/// <br>
+///
+/// # Examples
+///
+/// Composing raw and non-raw identifiers:
+/// ```
+/// # use quote::format_ident;
+/// let my_ident = format_ident!("My{}", "Ident");
+/// assert_eq!(my_ident, "MyIdent");
+///
+/// let raw = format_ident!("r#Raw");
+/// assert_eq!(raw, "r#Raw");
+///
+/// let my_ident_raw = format_ident!("{}Is{}", my_ident, raw);
+/// assert_eq!(my_ident_raw, "MyIdentIsRaw");
+/// ```
+///
+/// Integer formatting options:
+/// ```
+/// # use quote::format_ident;
+/// let num: u32 = 10;
+///
+/// let decimal = format_ident!("Id_{}", num);
+/// assert_eq!(decimal, "Id_10");
+///
+/// let octal = format_ident!("Id_{:o}", num);
+/// assert_eq!(octal, "Id_12");
+///
+/// let binary = format_ident!("Id_{:b}", num);
+/// assert_eq!(binary, "Id_1010");
+///
+/// let lower_hex = format_ident!("Id_{:x}", num);
+/// assert_eq!(lower_hex, "Id_a");
+///
+/// let upper_hex = format_ident!("Id_{:X}", num);
+/// assert_eq!(upper_hex, "Id_A");
+/// ```
+#[macro_export]
+macro_rules! format_ident {
+    ($fmt:expr) => {
+        $crate::format_ident_impl!([
+            $crate::__private::Option::None,
+            $fmt
+        ])
+    };
+
+    ($fmt:expr, $($rest:tt)*) => {
+        $crate::format_ident_impl!([
+            $crate::__private::Option::None,
+            $fmt
+        ] $($rest)*)
+    };
+}
+
+#[macro_export]
+#[doc(hidden)]
+macro_rules! format_ident_impl {
+    // Final state
+    ([$span:expr, $($fmt:tt)*]) => {
+        $crate::__private::mk_ident(
+            &$crate::__private::format!($($fmt)*),
+            $span,
+        )
+    };
+
+    // Span argument
+    ([$old:expr, $($fmt:tt)*] span = $span:expr) => {
+        $crate::format_ident_impl!([$old, $($fmt)*] span = $span,)
+    };
+    ([$old:expr, $($fmt:tt)*] span = $span:expr, $($rest:tt)*) => {
+        $crate::format_ident_impl!([
+            $crate::__private::Option::Some::<$crate::__private::Span>($span),
+            $($fmt)*
+        ] $($rest)*)
+    };
+
+    // Named argument
+    ([$span:expr, $($fmt:tt)*] $name:ident = $arg:expr) => {
+        $crate::format_ident_impl!([$span, $($fmt)*] $name = $arg,)
+    };
+    ([$span:expr, $($fmt:tt)*] $name:ident = $arg:expr, $($rest:tt)*) => {
+        match $crate::__private::IdentFragmentAdapter(&$arg) {
+            arg => $crate::format_ident_impl!([$span.or(arg.span()), $($fmt)*, $name = arg] $($rest)*),
+        }
+    };
+
+    // Positional argument
+    ([$span:expr, $($fmt:tt)*] $arg:expr) => {
+        $crate::format_ident_impl!([$span, $($fmt)*] $arg,)
+    };
+    ([$span:expr, $($fmt:tt)*] $arg:expr, $($rest:tt)*) => {
+        match $crate::__private::IdentFragmentAdapter(&$arg) {
+            arg => $crate::format_ident_impl!([$span.or(arg.span()), $($fmt)*, arg] $($rest)*),
+        }
+    };
+}
diff --git a/rust/quote/ident_fragment.rs b/rust/quote/ident_fragment.rs
new file mode 100644
index 000000000000..6c2a9a87acb4
--- /dev/null
+++ b/rust/quote/ident_fragment.rs
@@ -0,0 +1,88 @@
+use alloc::borrow::Cow;
+use core::fmt;
+use proc_macro2::{Ident, Span};
+
+/// Specialized formatting trait used by `format_ident!`.
+///
+/// [`Ident`] arguments formatted using this trait will have their `r#` prefix
+/// stripped, if present.
+///
+/// See [`format_ident!`] for more information.
+///
+/// [`format_ident!`]: crate::format_ident
+pub trait IdentFragment {
+    /// Format this value as an identifier fragment.
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result;
+
+    /// Span associated with this `IdentFragment`.
+    ///
+    /// If non-`None`, may be inherited by formatted identifiers.
+    fn span(&self) -> Option<Span> {
+        None
+    }
+}
+
+impl<T: IdentFragment + ?Sized> IdentFragment for &T {
+    fn span(&self) -> Option<Span> {
+        <T as IdentFragment>::span(*self)
+    }
+
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        IdentFragment::fmt(*self, f)
+    }
+}
+
+impl<T: IdentFragment + ?Sized> IdentFragment for &mut T {
+    fn span(&self) -> Option<Span> {
+        <T as IdentFragment>::span(*self)
+    }
+
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        IdentFragment::fmt(*self, f)
+    }
+}
+
+impl IdentFragment for Ident {
+    fn span(&self) -> Option<Span> {
+        Some(self.span())
+    }
+
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let id = self.to_string();
+        if let Some(id) = id.strip_prefix("r#") {
+            fmt::Display::fmt(id, f)
+        } else {
+            fmt::Display::fmt(&id[..], f)
+        }
+    }
+}
+
+impl<T> IdentFragment for Cow<'_, T>
+where
+    T: IdentFragment + ToOwned + ?Sized,
+{
+    fn span(&self) -> Option<Span> {
+        T::span(self)
+    }
+
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        T::fmt(self, f)
+    }
+}
+
+// Limited set of types which this is implemented for, as we want to avoid types
+// which will often include non-identifier characters in their `Display` impl.
+macro_rules! ident_fragment_display {
+    ($($T:ty),*) => {
+        $(
+            impl IdentFragment for $T {
+                fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+                    fmt::Display::fmt(self, f)
+                }
+            }
+        )*
+    };
+}
+
+ident_fragment_display!(bool, str, String, char);
+ident_fragment_display!(u8, u16, u32, u64, u128, usize);
diff --git a/rust/quote/lib.rs b/rust/quote/lib.rs
new file mode 100644
index 000000000000..0a12d607f279
--- /dev/null
+++ b/rust/quote/lib.rs
@@ -0,0 +1,1454 @@
+//! [![github]](https://github.com/dtolnay/quote)&ensp;[![crates-io]](https://crates.io/crates/quote)&ensp;[![docs-rs]](https://docs.rs/quote)
+//!
+//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
+//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
+//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
+//!
+//! <br>
+//!
+//! 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 &mdash; 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.
+//!
+//! ```toml
+//! [dependencies]
+//! quote = "1.0"
+//! ```
+//!
+//! <br>
+//!
+//! # 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.
+//!
+//! [a]: https://serde.rs/
+//!
+//! ```
+//! # use quote::quote;
+//! #
+//! # let generics = "";
+//! # let where_clause = "";
+//! # let field_ty = "";
+//! # let item_ty = "";
+//! # let path = "";
+//! # let value = "";
+//! #
+//! let tokens = quote! {
+//!     struct SerializeWith #generics #where_clause {
+//!         value: &'a #field_ty,
+//!         phantom: core::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: core::marker::PhantomData::<#item_ty>,
+//!     }
+//! };
+//! ```
+//!
+//! <br>
+//!
+//! # Non-macro code generators
+//!
+//! When using `quote` in a build.rs or main.rs and writing the output out to a
+//! file, consider having the code generator pass the tokens through
+//! [prettyplease] before writing. This way if an error occurs in the generated
+//! code it is convenient for a human to read and debug.
+//!
+//! [prettyplease]: https://github.com/dtolnay/prettyplease
+
+// Quote types in rustdoc of other crates get linked to here.
+#![doc(html_root_url = "https://docs.rs/quote/1.0.40")]
+#![allow(
+    clippy::doc_markdown,
+    clippy::elidable_lifetime_names,
+    clippy::missing_errors_doc,
+    clippy::missing_panics_doc,
+    clippy::module_name_repetitions,
+    clippy::needless_lifetimes,
+    // false positive https://github.com/rust-lang/rust-clippy/issues/6983
+    clippy::wrong_self_convention,
+)]
+
+extern crate alloc;
+
+#[cfg(feature = "proc-macro")]
+extern crate proc_macro;
+
+mod ext;
+mod format;
+mod ident_fragment;
+mod to_tokens;
+
+// Not public API.
+#[doc(hidden)]
+#[path = "runtime.rs"]
+pub mod __private;
+
+pub use crate::ext::TokenStreamExt;
+pub use crate::ident_fragment::IdentFragment;
+pub use crate::to_tokens::ToTokens;
+
+// Not public API.
+#[doc(hidden)]
+pub mod spanned;
+
+macro_rules! __quote {
+    ($quote:item) => {
+        /// The whole point.
+        ///
+        /// Performs variable interpolation against the input and produces it as
+        /// [`proc_macro2::TokenStream`].
+        ///
+        /// Note: for returning tokens to the compiler in a procedural macro, use
+        /// `.into()` on the result to convert to [`proc_macro::TokenStream`].
+        ///
+        /// <br>
+        ///
+        /// # 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.
+        ///
+        /// [Syn]: https://github.com/dtolnay/syn
+        ///
+        /// 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. The variables in an interpolation may be a `Vec`, slice,
+        /// `BTreeSet`, or any `Iterator`.
+        ///
+        /// - `#(#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
+        ///
+        /// <br>
+        ///
+        /// # 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()`].
+        ///
+        /// [`Span::call_site()`]: proc_macro2::Span::call_site
+        ///
+        /// A different span can be provided through the [`quote_spanned!`] macro.
+        ///
+        /// <br>
+        ///
+        /// # 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)`.
+        ///
+        /// <br>
+        ///
+        /// # 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.
+        ///
+        /// [Syn]: https://github.com/dtolnay/syn
+        ///
+        /// ```
+        /// # #[cfg(any())]
+        /// extern crate proc_macro;
+        /// # extern crate proc_macro2;
+        ///
+        /// # #[cfg(any())]
+        /// use proc_macro::TokenStream;
+        /// # use proc_macro2::TokenStream;
+        /// use quote::quote;
+        ///
+        /// # const IGNORE_TOKENS: &'static str = stringify! {
+        /// #[proc_macro_derive(HeapSize)]
+        /// # };
+        /// pub fn derive_heap_size(input: TokenStream) -> TokenStream {
+        ///     // Parse the input and figure out what implementation to generate...
+        ///     # const IGNORE_TOKENS: &'static str = stringify! {
+        ///     let name = /* ... */;
+        ///     let expr = /* ... */;
+        ///     # };
+        ///     #
+        ///     # let name = 0;
+        ///     # let expr = 0;
+        ///
+        ///     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)
+        /// }
+        /// ```
+        ///
+        /// <p><br></p>
+        ///
+        /// ### 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.
+        ///
+        /// ```
+        /// # use quote::quote;
+        /// #
+        /// let type_definition = quote! {...};
+        /// let methods = quote! {...};
+        ///
+        /// let tokens = quote! {
+        ///     #type_definition
+        ///     #methods
+        /// };
+        /// ```
+        ///
+        /// <p><br></p>
+        ///
+        /// ### 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`.
+        ///
+        /// ```
+        /// # use proc_macro2::{self as syn, Span};
+        /// # use quote::quote;
+        /// #
+        /// # let ident = syn::Ident::new("i", Span::call_site());
+        /// #
+        /// // incorrect
+        /// quote! {
+        ///     let mut _#ident = 0;
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// The solution is to build a new identifier token with the correct value. As
+        /// this is such a common case, the [`format_ident!`] macro provides a
+        /// convenient utility for doing so correctly.
+        ///
+        /// ```
+        /// # use proc_macro2::{Ident, Span};
+        /// # use quote::{format_ident, quote};
+        /// #
+        /// # let ident = Ident::new("i", Span::call_site());
+        /// #
+        /// let varname = format_ident!("_{}", ident);
+        /// quote! {
+        ///     let mut #varname = 0;
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// Alternatively, the APIs provided by Syn and proc-macro2 can be used to
+        /// directly build the identifier. This is roughly equivalent to the above, but
+        /// will not handle `ident` being a raw identifier.
+        ///
+        /// ```
+        /// # use proc_macro2::{self as syn, Span};
+        /// # use quote::quote;
+        /// #
+        /// # let ident = syn::Ident::new("i", Span::call_site());
+        /// #
+        /// let concatenated = format!("_{}", ident);
+        /// let varname = syn::Ident::new(&concatenated, ident.span());
+        /// quote! {
+        ///     let mut #varname = 0;
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// <p><br></p>
+        ///
+        /// ### 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.
+        ///
+        /// ```
+        /// # use quote::quote;
+        /// #
+        /// # let field_type = quote!(...);
+        /// #
+        /// // 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.
+        ///
+        /// ```
+        /// # use quote::quote;
+        /// #
+        /// # let field_type = quote!(...);
+        /// #
+        /// quote! {
+        ///     let value = <#field_type>::new();
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// This expands to `<Vec<i32>>::new()` which behaves correctly.
+        ///
+        /// A similar pattern is appropriate for trait methods.
+        ///
+        /// ```
+        /// # use quote::quote;
+        /// #
+        /// # let field_type = quote!(...);
+        /// #
+        /// quote! {
+        ///     let value = <#field_type as core::default::Default>::default();
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// <p><br></p>
+        ///
+        /// ### Interpolating text inside of doc comments
+        ///
+        /// Neither doc comments nor string literals get interpolation behavior in
+        /// quote:
+        ///
+        /// ```compile_fail
+        /// quote! {
+        ///     /// try to interpolate: #ident
+        ///     ///
+        ///     /// ...
+        /// }
+        /// ```
+        ///
+        /// ```compile_fail
+        /// quote! {
+        ///     #[doc = "try to interpolate: #ident"]
+        /// }
+        /// ```
+        ///
+        /// Instead the best way to build doc comments that involve variables is by
+        /// formatting the doc string literal outside of quote.
+        ///
+        /// ```rust
+        /// # use proc_macro2::{Ident, Span};
+        /// # use quote::quote;
+        /// #
+        /// # const IGNORE: &str = stringify! {
+        /// let msg = format!(...);
+        /// # };
+        /// #
+        /// # let ident = Ident::new("var", Span::call_site());
+        /// # let msg = format!("try to interpolate: {}", ident);
+        /// quote! {
+        ///     #[doc = #msg]
+        ///     ///
+        ///     /// ...
+        /// }
+        /// # ;
+        /// ```
+        ///
+        /// <p><br></p>
+        ///
+        /// ### Indexing into a tuple struct
+        ///
+        /// When interpolating indices of a tuple or tuple struct, we need them not to
+        /// appears suffixed as integer literals by interpolating them as [`syn::Index`]
+        /// instead.
+        ///
+        /// [`syn::Index`]: https://docs.rs/syn/2.0/syn/struct.Index.html
+        ///
+        /// ```compile_fail
+        /// let i = 0usize..self.fields.len();
+        ///
+        /// // expands to 0 + self.0usize.heap_size() + self.1usize.heap_size() + ...
+        /// // which is not valid syntax
+        /// quote! {
+        ///     0 #( + self.#i.heap_size() )*
+        /// }
+        /// ```
+        ///
+        /// ```
+        /// # use proc_macro2::{Ident, TokenStream};
+        /// # use quote::quote;
+        /// #
+        /// # mod syn {
+        /// #     use proc_macro2::{Literal, TokenStream};
+        /// #     use quote::{ToTokens, TokenStreamExt};
+        /// #
+        /// #     pub struct Index(usize);
+        /// #
+        /// #     impl From<usize> for Index {
+        /// #         fn from(i: usize) -> Self {
+        /// #             Index(i)
+        /// #         }
+        /// #     }
+        /// #
+        /// #     impl ToTokens for Index {
+        /// #         fn to_tokens(&self, tokens: &mut TokenStream) {
+        /// #             tokens.append(Literal::usize_unsuffixed(self.0));
+        /// #         }
+        /// #     }
+        /// # }
+        /// #
+        /// # struct Struct {
+        /// #     fields: Vec<Ident>,
+        /// # }
+        /// #
+        /// # impl Struct {
+        /// #     fn example(&self) -> TokenStream {
+        /// let i = (0..self.fields.len()).map(syn::Index::from);
+        ///
+        /// // expands to 0 + self.0.heap_size() + self.1.heap_size() + ...
+        /// quote! {
+        ///     0 #( + self.#i.heap_size() )*
+        /// }
+        /// #     }
+        /// # }
+        /// ```
+        $quote
+    };
+}
+
+#[cfg(doc)]
+__quote![
+    #[macro_export]
+    macro_rules! quote {
+        ($($tt:tt)*) => {
+            ...
+        };
+    }
+];
+
+#[cfg(not(doc))]
+__quote![
+    #[macro_export]
+    macro_rules! quote {
+        () => {
+            $crate::__private::TokenStream::new()
+        };
+
+        // Special case rule for a single tt, for performance.
+        ($tt:tt) => {{
+            let mut _s = $crate::__private::TokenStream::new();
+            $crate::quote_token!{$tt _s}
+            _s
+        }};
+
+        // Special case rules for two tts, for performance.
+        (# $var:ident) => {{
+            let mut _s = $crate::__private::TokenStream::new();
+            $crate::ToTokens::to_tokens(&$var, &mut _s);
+            _s
+        }};
+        ($tt1:tt $tt2:tt) => {{
+            let mut _s = $crate::__private::TokenStream::new();
+            $crate::quote_token!{$tt1 _s}
+            $crate::quote_token!{$tt2 _s}
+            _s
+        }};
+
+        // Rule for any other number of tokens.
+        ($($tt:tt)*) => {{
+            let mut _s = $crate::__private::TokenStream::new();
+            $crate::quote_each_token!{_s $($tt)*}
+            _s
+        }};
+    }
+];
+
+macro_rules! __quote_spanned {
+    ($quote_spanned:item) => {
+        /// Same as `quote!`, but applies a given span to all tokens originating within
+        /// the macro invocation.
+        ///
+        /// <br>
+        ///
+        /// # Syntax
+        ///
+        /// A span expression of type [`Span`], followed by `=>`, followed by the tokens
+        /// to quote. The span expression should be brief &mdash; use a variable for
+        /// anything more than a few characters. There should be no space before the
+        /// `=>` token.
+        ///
+        /// [`Span`]: proc_macro2::Span
+        ///
+        /// ```
+        /// # use proc_macro2::Span;
+        /// # use quote::quote_spanned;
+        /// #
+        /// # const IGNORE_TOKENS: &'static str = stringify! {
+        /// let span = /* ... */;
+        /// # };
+        /// # let span = Span::call_site();
+        /// # let init = 0;
+        ///
+        /// // On one line, use parentheses.
+        /// let tokens = quote_spanned!(span=> Box::into_raw(Box::new(#init)));
+        ///
+        /// // On multiple lines, place the span at the top and use braces.
+        /// let tokens = quote_spanned! {span=>
+        ///     Box::into_raw(Box::new(#init))
+        /// };
+        /// ```
+        ///
+        /// The lack of space before the `=>` should look jarring to Rust programmers
+        /// and this is intentional. The formatting is designed to be visibly
+        /// off-balance and draw the eye a particular way, due to the span expression
+        /// being evaluated in the context of the procedural macro and the remaining
+        /// tokens being evaluated in the generated code.
+        ///
+        /// <br>
+        ///
+        /// # Hygiene
+        ///
+        /// Any interpolated tokens preserve the `Span` information provided by their
+        /// `ToTokens` implementation. Tokens that originate within the `quote_spanned!`
+        /// invocation are spanned with the given span argument.
+        ///
+        /// <br>
+        ///
+        /// # Example
+        ///
+        /// The following procedural macro code uses `quote_spanned!` to assert that a
+        /// particular Rust type implements the [`Sync`] trait so that references can be
+        /// safely shared between threads.
+        ///
+        /// ```
+        /// # use quote::{quote_spanned, TokenStreamExt, ToTokens};
+        /// # use proc_macro2::{Span, TokenStream};
+        /// #
+        /// # struct Type;</