proc_macro2/
lib.rs

1//! [![github]](https://github.com/dtolnay/proc-macro2) [![crates-io]](https://crates.io/crates/proc-macro2) [![docs-rs]](crate)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6//!
7//! <br>
8//!
9//! A wrapper around the procedural macro API of the compiler's [`proc_macro`]
10//! crate. This library serves two purposes:
11//!
12//! - **Bring proc-macro-like functionality to other contexts like build.rs and
13//!   main.rs.** Types from `proc_macro` are entirely specific to procedural
14//!   macros and cannot ever exist in code outside of a procedural macro.
15//!   Meanwhile `proc_macro2` types may exist anywhere including non-macro code.
16//!   By developing foundational libraries like [syn] and [quote] against
17//!   `proc_macro2` rather than `proc_macro`, the procedural macro ecosystem
18//!   becomes easily applicable to many other use cases and we avoid
19//!   reimplementing non-macro equivalents of those libraries.
20//!
21//! - **Make procedural macros unit testable.** As a consequence of being
22//!   specific to procedural macros, nothing that uses `proc_macro` can be
23//!   executed from a unit test. In order for helper libraries or components of
24//!   a macro to be testable in isolation, they must be implemented using
25//!   `proc_macro2`.
26//!
27//! [syn]: https://github.com/dtolnay/syn
28//! [quote]: https://github.com/dtolnay/quote
29//!
30//! # Usage
31//!
32//! The skeleton of a typical procedural macro typically looks like this:
33//!
34//! ```
35//! extern crate proc_macro;
36//!
37//! # const IGNORE: &str = stringify! {
38//! #[proc_macro_derive(MyDerive)]
39//! # };
40//! # #[cfg(wrap_proc_macro)]
41//! pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
42//!     let input = proc_macro2::TokenStream::from(input);
43//!
44//!     let output: proc_macro2::TokenStream = {
45//!         /* transform input */
46//!         # input
47//!     };
48//!
49//!     proc_macro::TokenStream::from(output)
50//! }
51//! ```
52//!
53//! If parsing with [Syn], you'll use [`parse_macro_input!`] instead to
54//! propagate parse errors correctly back to the compiler when parsing fails.
55//!
56//! [`parse_macro_input!`]: https://docs.rs/syn/2.0/syn/macro.parse_macro_input.html
57//!
58//! # Unstable features
59//!
60//! The default feature set of proc-macro2 tracks the most recent stable
61//! compiler API. Functionality in `proc_macro` that is not yet stable is not
62//! exposed by proc-macro2 by default.
63//!
64//! To opt into the additional APIs available in the most recent nightly
65//! compiler, the `procmacro2_semver_exempt` config flag must be passed to
66//! rustc. We will polyfill those nightly-only APIs back to Rust 1.56.0. As
67//! these are unstable APIs that track the nightly compiler, minor versions of
68//! proc-macro2 may make breaking changes to them at any time.
69//!
70//! ```sh
71//! RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
72//! ```
73//!
74//! Note that this must not only be done for your crate, but for any crate that
75//! depends on your crate. This infectious nature is intentional, as it serves
76//! as a reminder that you are outside of the normal semver guarantees.
77//!
78//! Semver exempt methods are marked as such in the proc-macro2 documentation.
79//!
80//! # Thread-Safety
81//!
82//! Most types in this crate are `!Sync` because the underlying compiler
83//! types make use of thread-local memory, meaning they cannot be accessed from
84//! a different thread.
85
86// Proc-macro2 types in rustdoc of other crates get linked to here.
87#![doc(html_root_url = "https://docs.rs/proc-macro2/1.0.94")]
88#![cfg_attr(any(proc_macro_span, super_unstable), feature(proc_macro_span))]
89#![cfg_attr(super_unstable, feature(proc_macro_def_site))]
90#![cfg_attr(docsrs, feature(doc_cfg))]
91#![deny(unsafe_op_in_unsafe_fn)]
92#![allow(
93    clippy::cast_lossless,
94    clippy::cast_possible_truncation,
95    clippy::checked_conversions,
96    clippy::doc_markdown,
97    clippy::elidable_lifetime_names,
98    clippy::incompatible_msrv,
99    clippy::items_after_statements,
100    clippy::iter_without_into_iter,
101    clippy::let_underscore_untyped,
102    clippy::manual_assert,
103    clippy::manual_range_contains,
104    clippy::missing_panics_doc,
105    clippy::missing_safety_doc,
106    clippy::must_use_candidate,
107    clippy::needless_doctest_main,
108    clippy::needless_lifetimes,
109    clippy::new_without_default,
110    clippy::return_self_not_must_use,
111    clippy::shadow_unrelated,
112    clippy::trivially_copy_pass_by_ref,
113    clippy::unnecessary_wraps,
114    clippy::unused_self,
115    clippy::used_underscore_binding,
116    clippy::vec_init_then_push
117)]
118
119#[cfg(all(procmacro2_semver_exempt, wrap_proc_macro, not(super_unstable)))]
120compile_error! {"\
121    Something is not right. If you've tried to turn on \
122    procmacro2_semver_exempt, you need to ensure that it \
123    is turned on for the compilation of the proc-macro2 \
124    build script as well.
125"}
126
127#[cfg(all(
128    procmacro2_nightly_testing,
129    feature = "proc-macro",
130    not(proc_macro_span)
131))]
132compile_error! {"\
133    Build script probe failed to compile.
134"}
135
136extern crate alloc;
137
138#[cfg(feature = "proc-macro")]
139extern crate proc_macro;
140
141mod marker;
142mod parse;
143mod rcvec;
144
145#[cfg(wrap_proc_macro)]
146mod detection;
147
148// Public for proc_macro2::fallback::force() and unforce(), but those are quite
149// a niche use case so we omit it from rustdoc.
150#[doc(hidden)]
151pub mod fallback;
152
153pub mod extra;
154
155#[cfg(not(wrap_proc_macro))]
156use crate::fallback as imp;
157#[path = "wrapper.rs"]
158#[cfg(wrap_proc_macro)]
159mod imp;
160
161#[cfg(span_locations)]
162mod location;
163
164use crate::extra::DelimSpan;
165use crate::marker::{ProcMacroAutoTraits, MARKER};
166use core::cmp::Ordering;
167use core::fmt::{self, Debug, Display};
168use core::hash::{Hash, Hasher};
169#[cfg(span_locations)]
170use core::ops::Range;
171use core::ops::RangeBounds;
172use core::str::FromStr;
173use std::error::Error;
174use std::ffi::CStr;
175#[cfg(procmacro2_semver_exempt)]
176use std::path::PathBuf;
177
178#[cfg(span_locations)]
179#[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
180pub use crate::location::LineColumn;
181
182/// An abstract stream of tokens, or more concretely a sequence of token trees.
183///
184/// This type provides interfaces for iterating over token trees and for
185/// collecting token trees into one stream.
186///
187/// Token stream is both the input and output of `#[proc_macro]`,
188/// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions.
189#[derive(Clone)]
190pub struct TokenStream {
191    inner: imp::TokenStream,
192    _marker: ProcMacroAutoTraits,
193}
194
195/// Error returned from `TokenStream::from_str`.
196pub struct LexError {
197    inner: imp::LexError,
198    _marker: ProcMacroAutoTraits,
199}
200
201impl TokenStream {
202    fn _new(inner: imp::TokenStream) -> Self {
203        TokenStream {
204            inner,
205            _marker: MARKER,
206        }
207    }
208
209    fn _new_fallback(inner: fallback::TokenStream) -> Self {
210        TokenStream {
211            inner: imp::TokenStream::from(inner),
212            _marker: MARKER,
213        }
214    }
215
216    /// Returns an empty `TokenStream` containing no token trees.
217    pub fn new() -> Self {
218        TokenStream::_new(imp::TokenStream::new())
219    }
220
221    /// Checks if this `TokenStream` is empty.
222    pub fn is_empty(&self) -> bool {
223        self.inner.is_empty()
224    }
225}
226
227/// `TokenStream::default()` returns an empty stream,
228/// i.e. this is equivalent with `TokenStream::new()`.
229impl Default for TokenStream {
230    fn default() -> Self {
231        TokenStream::new()
232    }
233}
234
235/// Attempts to break the string into tokens and parse those tokens into a token
236/// stream.
237///
238/// May fail for a number of reasons, for example, if the string contains
239/// unbalanced delimiters or characters not existing in the language.
240///
241/// NOTE: Some errors may cause panics instead of returning `LexError`. We
242/// reserve the right to change these errors into `LexError`s later.
243impl FromStr for TokenStream {
244    type Err = LexError;
245
246    fn from_str(src: &str) -> Result<TokenStream, LexError> {
247        match imp::TokenStream::from_str_checked(src) {
248            Ok(tokens) => Ok(TokenStream::_new(tokens)),
249            Err(lex) => Err(LexError {
250                inner: lex,
251                _marker: MARKER,
252            }),
253        }
254    }
255}
256
257#[cfg(feature = "proc-macro")]
258#[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
259impl From<proc_macro::TokenStream> for TokenStream {
260    fn from(inner: proc_macro::TokenStream) -> Self {
261        TokenStream::_new(imp::TokenStream::from(inner))
262    }
263}
264
265#[cfg(feature = "proc-macro")]
266#[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
267impl From<TokenStream> for proc_macro::TokenStream {
268    fn from(inner: TokenStream) -> Self {
269        proc_macro::TokenStream::from(inner.inner)
270    }
271}
272
273impl From<TokenTree> for TokenStream {
274    fn from(token: TokenTree) -> Self {
275        TokenStream::_new(imp::TokenStream::from(token))
276    }
277}
278
279impl Extend<TokenTree> for TokenStream {
280    fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, streams: I) {
281        self.inner.extend(streams);
282    }
283}
284
285impl Extend<TokenStream> for TokenStream {
286    fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) {
287        self.inner
288            .extend(streams.into_iter().map(|stream| stream.inner));
289    }
290}
291
292/// Collects a number of token trees into a single stream.
293impl FromIterator<TokenTree> for TokenStream {
294    fn from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self {
295        TokenStream::_new(streams.into_iter().collect())
296    }
297}
298impl FromIterator<TokenStream> for TokenStream {
299    fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self {
300        TokenStream::_new(streams.into_iter().map(|i| i.inner).collect())
301    }
302}
303
304/// Prints the token stream as a string that is supposed to be losslessly
305/// convertible back into the same token stream (modulo spans), except for
306/// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative
307/// numeric literals.
308impl Display for TokenStream {
309    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
310        Display::fmt(&self.inner, f)
311    }
312}
313
314/// Prints token in a form convenient for debugging.
315impl Debug for TokenStream {
316    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
317        Debug::fmt(&self.inner, f)
318    }
319}
320
321impl LexError {
322    pub fn span(&self) -> Span {
323        Span::_new(self.inner.span())
324    }
325}
326
327impl Debug for LexError {
328    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
329        Debug::fmt(&self.inner, f)
330    }
331}
332
333impl Display for LexError {
334    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
335        Display::fmt(&self.inner, f)
336    }
337}
338
339impl Error for LexError {}
340
341/// The source file of a given `Span`.
342///
343/// This type is semver exempt and not exposed by default.
344#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
345#[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
346#[derive(Clone, PartialEq, Eq)]
347pub struct SourceFile {
348    inner: imp::SourceFile,
349    _marker: ProcMacroAutoTraits,
350}
351
352#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
353impl SourceFile {
354    fn _new(inner: imp::SourceFile) -> Self {
355        SourceFile {
356            inner,
357            _marker: MARKER,
358        }
359    }
360
361    /// Get the path to this source file.
362    ///
363    /// ### Note
364    ///
365    /// If the code span associated with this `SourceFile` was generated by an
366    /// external macro, this may not be an actual path on the filesystem. Use
367    /// [`is_real`] to check.
368    ///
369    /// Also note that even if `is_real` returns `true`, if
370    /// `--remap-path-prefix` was passed on the command line, the path as given
371    /// may not actually be valid.
372    ///
373    /// [`is_real`]: #method.is_real
374    pub fn path(&self) -> PathBuf {
375        self.inner.path()
376    }
377
378    /// Returns `true` if this source file is a real source file, and not
379    /// generated by an external macro's expansion.
380    pub fn is_real(&self) -> bool {
381        self.inner.is_real()
382    }
383}
384
385#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
386impl Debug for SourceFile {
387    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
388        Debug::fmt(&self.inner, f)
389    }
390}
391
392/// A region of source code, along with macro expansion information.
393#[derive(Copy, Clone)]
394pub struct Span {
395    inner: imp::Span,
396    _marker: ProcMacroAutoTraits,
397}
398
399impl Span {
400    fn _new(inner: imp::Span) -> Self {
401        Span {
402            inner,
403            _marker: MARKER,
404        }
405    }
406
407    fn _new_fallback(inner: fallback::Span) -> Self {
408        Span {
409            inner: imp::Span::from(inner),
410            _marker: MARKER,
411        }
412    }
413
414    /// The span of the invocation of the current procedural macro.
415    ///
416    /// Identifiers created with this span will be resolved as if they were
417    /// written directly at the macro call location (call-site hygiene) and
418    /// other code at the macro call site will be able to refer to them as well.
419    pub fn call_site() -> Self {
420        Span::_new(imp::Span::call_site())
421    }
422
423    /// The span located at the invocation of the procedural macro, but with
424    /// local variables, labels, and `$crate` resolved at the definition site
425    /// of the macro. This is the same hygiene behavior as `macro_rules`.
426    pub fn mixed_site() -> Self {
427        Span::_new(imp::Span::mixed_site())
428    }
429
430    /// A span that resolves at the macro definition site.
431    ///
432    /// This method is semver exempt and not exposed by default.
433    #[cfg(procmacro2_semver_exempt)]
434    #[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
435    pub fn def_site() -> Self {
436        Span::_new(imp::Span::def_site())
437    }
438
439    /// Creates a new span with the same line/column information as `self` but
440    /// that resolves symbols as though it were at `other`.
441    pub fn resolved_at(&self, other: Span) -> Span {
442        Span::_new(self.inner.resolved_at(other.inner))
443    }
444
445    /// Creates a new span with the same name resolution behavior as `self` but
446    /// with the line/column information of `other`.
447    pub fn located_at(&self, other: Span) -> Span {
448        Span::_new(self.inner.located_at(other.inner))
449    }
450
451    /// Convert `proc_macro2::Span` to `proc_macro::Span`.
452    ///
453    /// This method is available when building with a nightly compiler, or when
454    /// building with rustc 1.29+ *without* semver exempt features.
455    ///
456    /// # Panics
457    ///
458    /// Panics if called from outside of a procedural macro. Unlike
459    /// `proc_macro2::Span`, the `proc_macro::Span` type can only exist within
460    /// the context of a procedural macro invocation.
461    #[cfg(wrap_proc_macro)]
462    pub fn unwrap(self) -> proc_macro::Span {
463        self.inner.unwrap()
464    }
465
466    // Soft deprecated. Please use Span::unwrap.
467    #[cfg(wrap_proc_macro)]
468    #[doc(hidden)]
469    pub fn unstable(self) -> proc_macro::Span {
470        self.unwrap()
471    }
472
473    /// The original source file into which this span points.
474    ///
475    /// This method is semver exempt and not exposed by default.
476    #[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
477    #[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
478    pub fn source_file(&self) -> SourceFile {
479        SourceFile::_new(self.inner.source_file())
480    }
481
482    /// Returns the span's byte position range in the source file.
483    ///
484    /// This method requires the `"span-locations"` feature to be enabled.
485    ///
486    /// When executing in a procedural macro context, the returned range is only
487    /// accurate if compiled with a nightly toolchain. The stable toolchain does
488    /// not have this information available. When executing outside of a
489    /// procedural macro, such as main.rs or build.rs, the byte range is always
490    /// accurate regardless of toolchain.
491    #[cfg(span_locations)]
492    #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
493    pub fn byte_range(&self) -> Range<usize> {
494        self.inner.byte_range()
495    }
496
497    /// Get the starting line/column in the source file for this span.
498    ///
499    /// This method requires the `"span-locations"` feature to be enabled.
500    ///
501    /// When executing in a procedural macro context, the returned line/column
502    /// are only meaningful if compiled with a nightly toolchain. The stable
503    /// toolchain does not have this information available. When executing
504    /// outside of a procedural macro, such as main.rs or build.rs, the
505    /// line/column are always meaningful regardless of toolchain.
506    #[cfg(span_locations)]
507    #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
508    pub fn start(&self) -> LineColumn {
509        self.inner.start()
510    }
511
512    /// Get the ending line/column in the source file for this span.
513    ///
514    /// This method requires the `"span-locations"` feature to be enabled.
515    ///
516    /// When executing in a procedural macro context, the returned line/column
517    /// are only meaningful if compiled with a nightly toolchain. The stable
518    /// toolchain does not have this information available. When executing
519    /// outside of a procedural macro, such as main.rs or build.rs, the
520    /// line/column are always meaningful regardless of toolchain.
521    #[cfg(span_locations)]
522    #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
523    pub fn end(&self) -> LineColumn {
524        self.inner.end()
525    }
526
527    /// Create a new span encompassing `self` and `other`.
528    ///
529    /// Returns `None` if `self` and `other` are from different files.
530    ///
531    /// Warning: the underlying [`proc_macro::Span::join`] method is
532    /// nightly-only. When called from within a procedural macro not using a
533    /// nightly compiler, this method will always return `None`.
534    pub fn join(&self, other: Span) -> Option<Span> {
535        self.inner.join(other.inner).map(Span::_new)
536    }
537
538    /// Compares two spans to see if they're equal.
539    ///
540    /// This method is semver exempt and not exposed by default.
541    #[cfg(procmacro2_semver_exempt)]
542    #[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
543    pub fn eq(&self, other: &Span) -> bool {
544        self.inner.eq(&other.inner)
545    }
546
547    /// Returns the source text behind a span. This preserves the original
548    /// source code, including spaces and comments. It only returns a result if
549    /// the span corresponds to real source code.
550    ///
551    /// Note: The observable result of a macro should only rely on the tokens
552    /// and not on this source text. The result of this function is a best
553    /// effort to be used for diagnostics only.
554    pub fn source_text(&self) -> Option<String> {
555        self.inner.source_text()
556    }
557}
558
559/// Prints a span in a form convenient for debugging.
560impl Debug for Span {
561    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
562        Debug::fmt(&self.inner, f)
563    }
564}
565
566/// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`).
567#[derive(Clone)]
568pub enum TokenTree {
569    /// A token stream surrounded by bracket delimiters.
570    Group(Group),
571    /// An identifier.
572    Ident(Ident),
573    /// A single punctuation character (`+`, `,`, `$`, etc.).
574    Punct(Punct),
575    /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc.
576    Literal(Literal),
577}
578
579impl TokenTree {
580    /// Returns the span of this tree, delegating to the `span` method of
581    /// the contained token or a delimited stream.
582    pub fn span(&self) -> Span {
583        match self {
584            TokenTree::Group(t) => t.span(),
585            TokenTree::Ident(t) => t.span(),
586            TokenTree::Punct(t) => t.span(),
587            TokenTree::Literal(t) => t.span(),
588        }
589    }
590
591    /// Configures the span for *only this token*.
592    ///
593    /// Note that if this token is a `Group` then this method will not configure
594    /// the span of each of the internal tokens, this will simply delegate to
595    /// the `set_span` method of each variant.
596    pub fn set_span(&mut self, span: Span) {
597        match self {
598            TokenTree::Group(t) => t.set_span(span),
599            TokenTree::Ident(t) => t.set_span(span),
600            TokenTree::Punct(t) => t.set_span(span),
601            TokenTree::Literal(t) => t.set_span(span),
602        }
603    }
604}
605
606impl From<Group> for TokenTree {
607    fn from(g: Group) -> Self {
608        TokenTree::Group(g)
609    }
610}
611
612impl From<Ident> for TokenTree {
613    fn from(g: Ident) -> Self {
614        TokenTree::Ident(g)
615    }
616}
617
618impl From<Punct> for TokenTree {
619    fn from(g: Punct) -> Self {
620        TokenTree::Punct(g)
621    }
622}
623
624impl From<Literal> for TokenTree {
625    fn from(g: Literal) -> Self {
626        TokenTree::Literal(g)
627    }
628}
629
630/// Prints the token tree as a string that is supposed to be losslessly
631/// convertible back into the same token tree (modulo spans), except for
632/// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative
633/// numeric literals.
634impl Display for TokenTree {
635    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
636        match self {
637            TokenTree::Group(t) => Display::fmt(t, f),
638            TokenTree::Ident(t) => Display::fmt(t, f),
639            TokenTree::Punct(t) => Display::fmt(t, f),
640            TokenTree::Literal(t) => Display::fmt(t, f),
641        }
642    }
643}
644
645/// Prints token tree in a form convenient for debugging.
646impl Debug for TokenTree {
647    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
648        // Each of these has the name in the struct type in the derived debug,
649        // so don't bother with an extra layer of indirection
650        match self {
651            TokenTree::Group(t) => Debug::fmt(t, f),
652            TokenTree::Ident(t) => {
653                let mut debug = f.debug_struct("Ident");
654                debug.field("sym", &format_args!("{}", t));
655                imp::debug_span_field_if_nontrivial(&mut debug, t.span().inner);
656                debug.finish()
657            }
658            TokenTree::Punct(t) => Debug::fmt(t, f),
659            TokenTree::Literal(t) => Debug::fmt(t, f),
660        }
661    }
662}
663
664/// A delimited token stream.
665///
666/// A `Group` internally contains a `TokenStream` which is surrounded by
667/// `Delimiter`s.
668#[derive(Clone)]
669pub struct Group {
670    inner: imp::Group,
671}
672
673/// Describes how a sequence of token trees is delimited.
674#[derive(Copy, Clone, Debug, Eq, PartialEq)]
675pub enum Delimiter {
676    /// `( ... )`
677    Parenthesis,
678    /// `{ ... }`
679    Brace,
680    /// `[ ... ]`
681    Bracket,
682    /// `∅ ... ∅`
683    ///
684    /// An invisible delimiter, that may, for example, appear around tokens
685    /// coming from a "macro variable" `$var`. It is important to preserve
686    /// operator priorities in cases like `$var * 3` where `$var` is `1 + 2`.
687    /// Invisible delimiters may not survive roundtrip of a token stream through
688    /// a string.
689    ///
690    /// <div class="warning">
691    ///
692    /// Note: rustc currently can ignore the grouping of tokens delimited by `None` in the output
693    /// of a proc_macro. Only `None`-delimited groups created by a macro_rules macro in the input
694    /// of a proc_macro macro are preserved, and only in very specific circumstances.
695    /// Any `None`-delimited groups (re)created by a proc_macro will therefore not preserve
696    /// operator priorities as indicated above. The other `Delimiter` variants should be used
697    /// instead in this context. This is a rustc bug. For details, see
698    /// [rust-lang/rust#67062](https://github.com/rust-lang/rust/issues/67062).
699    ///
700    /// </div>
701    None,
702}
703
704impl Group {
705    fn _new(inner: imp::Group) -> Self {
706        Group { inner }
707    }
708
709    fn _new_fallback(inner: fallback::Group) -> Self {
710        Group {
711            inner: imp::Group::from(inner),
712        }
713    }
714
715    /// Creates a new `Group` with the given delimiter and token stream.
716    ///
717    /// This constructor will set the span for this group to
718    /// `Span::call_site()`. To change the span you can use the `set_span`
719    /// method below.
720    pub fn new(delimiter: Delimiter, stream: TokenStream) -> Self {
721        Group {
722            inner: imp::Group::new(delimiter, stream.inner),
723        }
724    }
725
726    /// Returns the punctuation used as the delimiter for this group: a set of
727    /// parentheses, square brackets, or curly braces.
728    pub fn delimiter(&self) -> Delimiter {
729        self.inner.delimiter()
730    }
731
732    /// Returns the `TokenStream` of tokens that are delimited in this `Group`.
733    ///
734    /// Note that the returned token stream does not include the delimiter
735    /// returned above.
736    pub fn stream(&self) -> TokenStream {
737        TokenStream::_new(self.inner.stream())
738    }
739
740    /// Returns the span for the delimiters of this token stream, spanning the
741    /// entire `Group`.
742    ///
743    /// ```text
744    /// pub fn span(&self) -> Span {
745    ///            ^^^^^^^
746    /// ```
747    pub fn span(&self) -> Span {
748        Span::_new(self.inner.span())
749    }
750
751    /// Returns the span pointing to the opening delimiter of this group.
752    ///
753    /// ```text
754    /// pub fn span_open(&self) -> Span {
755    ///                 ^
756    /// ```
757    pub fn span_open(&self) -> Span {
758        Span::_new(self.inner.span_open())
759    }
760
761    /// Returns the span pointing to the closing delimiter of this group.
762    ///
763    /// ```text
764    /// pub fn span_close(&self) -> Span {
765    ///                        ^
766    /// ```
767    pub fn span_close(&self) -> Span {
768        Span::_new(self.inner.span_close())
769    }
770
771    /// Returns an object that holds this group's `span_open()` and
772    /// `span_close()` together (in a more compact representation than holding
773    /// those 2 spans individually).
774    pub fn delim_span(&self) -> DelimSpan {
775        DelimSpan::new(&self.inner)
776    }
777
778    /// Configures the span for this `Group`'s delimiters, but not its internal
779    /// tokens.
780    ///
781    /// This method will **not** set the span of all the internal tokens spanned
782    /// by this group, but rather it will only set the span of the delimiter
783    /// tokens at the level of the `Group`.
784    pub fn set_span(&mut self, span: Span) {
785        self.inner.set_span(span.inner);
786    }
787}
788
789/// Prints the group as a string that should be losslessly convertible back
790/// into the same group (modulo spans), except for possibly `TokenTree::Group`s
791/// with `Delimiter::None` delimiters.
792impl Display for Group {
793    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
794        Display::fmt(&self.inner, formatter)
795    }
796}
797
798impl Debug for Group {
799    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
800        Debug::fmt(&self.inner, formatter)
801    }
802}
803
804/// A `Punct` is a single punctuation character like `+`, `-` or `#`.
805///
806/// Multicharacter operators like `+=` are represented as two instances of
807/// `Punct` with different forms of `Spacing` returned.
808#[derive(Clone)]
809pub struct Punct {
810    ch: char,
811    spacing: Spacing,
812    span: Span,
813}
814
815/// Whether a `Punct` is followed immediately by another `Punct` or followed by
816/// another token or whitespace.
817#[derive(Copy, Clone, Debug, Eq, PartialEq)]
818pub enum Spacing {
819    /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`.
820    Alone,
821    /// E.g. `+` is `Joint` in `+=` or `'` is `Joint` in `'#`.
822    ///
823    /// Additionally, single quote `'` can join with identifiers to form
824    /// lifetimes `'ident`.
825    Joint,
826}
827
828impl Punct {
829    /// Creates a new `Punct` from the given character and spacing.
830    ///
831    /// The `ch` argument must be a valid punctuation character permitted by the
832    /// language, otherwise the function will panic.
833    ///
834    /// The returned `Punct` will have the default span of `Span::call_site()`
835    /// which can be further configured with the `set_span` method below.
836    pub fn new(ch: char, spacing: Spacing) -> Self {
837        if let '!' | '#' | '$' | '%' | '&' | '\'' | '*' | '+' | ',' | '-' | '.' | '/' | ':' | ';'
838        | '<' | '=' | '>' | '?' | '@' | '^' | '|' | '~' = ch
839        {
840            Punct {
841                ch,
842                spacing,
843                span: Span::call_site(),
844            }
845        } else {
846            panic!("unsupported proc macro punctuation character {:?}", ch);
847        }
848    }
849
850    /// Returns the value of this punctuation character as `char`.
851    pub fn as_char(&self) -> char {
852        self.ch
853    }
854
855    /// Returns the spacing of this punctuation character, indicating whether
856    /// it's immediately followed by another `Punct` in the token stream, so
857    /// they can potentially be combined into a multicharacter operator
858    /// (`Joint`), or it's followed by some other token or whitespace (`Alone`)
859    /// so the operator has certainly ended.
860    pub fn spacing(&self) -> Spacing {
861        self.spacing
862    }
863
864    /// Returns the span for this punctuation character.
865    pub fn span(&self) -> Span {
866        self.span
867    }
868
869    /// Configure the span for this punctuation character.
870    pub fn set_span(&mut self, span: Span) {
871        self.span = span;
872    }
873}
874
875/// Prints the punctuation character as a string that should be losslessly
876/// convertible back into the same character.
877impl Display for Punct {
878    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
879        Display::fmt(&self.ch, f)
880    }
881}
882
883impl Debug for Punct {
884    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
885        let mut debug = fmt.debug_struct("Punct");
886        debug.field("char", &self.ch);
887        debug.field("spacing", &self.spacing);
888        imp::debug_span_field_if_nontrivial(&mut debug, self.span.inner);
889        debug.finish()
890    }
891}
892
893/// A word of Rust code, which may be a keyword or legal variable name.
894///
895/// An identifier consists of at least one Unicode code point, the first of
896/// which has the XID_Start property and the rest of which have the XID_Continue
897/// property.
898///
899/// - The empty string is not an identifier. Use `Option<Ident>`.
900/// - A lifetime is not an identifier. Use `syn::Lifetime` instead.
901///
902/// An identifier constructed with `Ident::new` is permitted to be a Rust
903/// keyword, though parsing one through its [`Parse`] implementation rejects
904/// Rust keywords. Use `input.call(Ident::parse_any)` when parsing to match the
905/// behaviour of `Ident::new`.
906///
907/// [`Parse`]: https://docs.rs/syn/2.0/syn/parse/trait.Parse.html
908///
909/// # Examples
910///
911/// A new ident can be created from a string using the `Ident::new` function.
912/// A span must be provided explicitly which governs the name resolution
913/// behavior of the resulting identifier.
914///
915/// ```
916/// use proc_macro2::{Ident, Span};
917///
918/// fn main() {
919///     let call_ident = Ident::new("calligraphy", Span::call_site());
920///
921///     println!("{}", call_ident);
922/// }
923/// ```
924///
925/// An ident can be interpolated into a token stream using the `quote!` macro.
926///
927/// ```
928/// use proc_macro2::{Ident, Span};
929/// use quote::quote;
930///
931/// fn main() {
932///     let ident = Ident::new("demo", Span::call_site());
933///
934///     // Create a variable binding whose name is this ident.
935///     let expanded = quote! { let #ident = 10; };
936///
937///     // Create a variable binding with a slightly different name.
938///     let temp_ident = Ident::new(&format!("new_{}", ident), Span::call_site());
939///     let expanded = quote! { let #temp_ident = 10; };
940/// }
941/// ```
942///
943/// A string representation of the ident is available through the `to_string()`
944/// method.
945///
946/// ```
947/// # use proc_macro2::{Ident, Span};
948/// #
949/// # let ident = Ident::new("another_identifier", Span::call_site());
950/// #
951/// // Examine the ident as a string.
952/// let ident_string = ident.to_string();
953/// if ident_string.len() > 60 {
954///     println!("Very long identifier: {}", ident_string)
955/// }
956/// ```
957#[derive(Clone)]
958pub struct Ident {
959    inner: imp::Ident,
960    _marker: ProcMacroAutoTraits,
961}
962
963impl Ident {
964    fn _new(inner: imp::Ident) -> Self {
965        Ident {
966            inner,
967            _marker: MARKER,
968        }
969    }
970
971    fn _new_fallback(inner: fallback::Ident) -> Self {
972        Ident {
973            inner: imp::Ident::from(inner),
974            _marker: MARKER,
975        }
976    }
977
978    /// Creates a new `Ident` with the given `string` as well as the specified
979    /// `span`.
980    ///
981    /// The `string` argument must be a valid identifier permitted by the
982    /// language, otherwise the function will panic.
983    ///
984    /// Note that `span`, currently in rustc, configures the hygiene information
985    /// for this identifier.
986    ///
987    /// As of this time `Span::call_site()` explicitly opts-in to "call-site"
988    /// hygiene meaning that identifiers created with this span will be resolved
989    /// as if they were written directly at the location of the macro call, and
990    /// other code at the macro call site will be able to refer to them as well.
991    ///
992    /// Later spans like `Span::def_site()` will allow to opt-in to
993    /// "definition-site" hygiene meaning that identifiers created with this
994    /// span will be resolved at the location of the macro definition and other
995    /// code at the macro call site will not be able to refer to them.
996    ///
997    /// Due to the current importance of hygiene this constructor, unlike other
998    /// tokens, requires a `Span` to be specified at construction.
999    ///
1000    /// # Panics
1001    ///
1002    /// Panics if the input string is neither a keyword nor a legal variable
1003    /// name. If you are not sure whether the string contains an identifier and
1004    /// need to handle an error case, use
1005    /// <a href="https://docs.rs/syn/2.0/syn/fn.parse_str.html"><code
1006    ///   style="padding-right:0;">syn::parse_str</code></a><code
1007    ///   style="padding-left:0;">::&lt;Ident&gt;</code>
1008    /// rather than `Ident::new`.
1009    #[track_caller]
1010    pub fn new(string: &str, span: Span) -> Self {
1011        Ident::_new(imp::Ident::new_checked(string, span.inner))
1012    }
1013
1014    /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). The
1015    /// `string` argument must be a valid identifier permitted by the language
1016    /// (including keywords, e.g. `fn`). Keywords which are usable in path
1017    /// segments (e.g. `self`, `super`) are not supported, and will cause a
1018    /// panic.
1019    #[track_caller]
1020    pub fn new_raw(string: &str, span: Span) -> Self {
1021        Ident::_new(imp::Ident::new_raw_checked(string, span.inner))
1022    }
1023
1024    /// Returns the span of this `Ident`.
1025    pub fn span(&self) -> Span {
1026        Span::_new(self.inner.span())
1027    }
1028
1029    /// Configures the span of this `Ident`, possibly changing its hygiene
1030    /// context.
1031    pub fn set_span(&mut self, span: Span) {
1032        self.inner.set_span(span.inner);
1033    }
1034}
1035
1036impl PartialEq for Ident {
1037    fn eq(&self, other: &Ident) -> bool {
1038        self.inner == other.inner
1039    }
1040}
1041
1042impl<T> PartialEq<T> for Ident
1043where
1044    T: ?Sized + AsRef<str>,
1045{
1046    fn eq(&self, other: &T) -> bool {
1047        self.inner == other
1048    }
1049}
1050
1051impl Eq for Ident {}
1052
1053impl PartialOrd for Ident {
1054    fn partial_cmp(&self, other: &Ident) -> Option<Ordering> {
1055        Some(self.cmp(other))
1056    }
1057}
1058
1059impl Ord for Ident {
1060    fn cmp(&self, other: &Ident) -> Ordering {
1061        self.to_string().cmp(&other.to_string())
1062    }
1063}
1064
1065impl Hash for Ident {
1066    fn hash<H: Hasher>(&self, hasher: &mut H) {
1067        self.to_string().hash(hasher);
1068    }
1069}
1070
1071/// Prints the identifier as a string that should be losslessly convertible back
1072/// into the same identifier.
1073impl Display for Ident {
1074    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1075        Display::fmt(&self.inner, f)
1076    }
1077}
1078
1079impl Debug for Ident {
1080    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1081        Debug::fmt(&self.inner, f)
1082    }
1083}
1084
1085/// A literal string (`"hello"`), byte string (`b"hello"`), character (`'a'`),
1086/// byte character (`b'a'`), an integer or floating point number with or without
1087/// a suffix (`1`, `1u8`, `2.3`, `2.3f32`).
1088///
1089/// Boolean literals like `true` and `false` do not belong here, they are
1090/// `Ident`s.
1091#[derive(Clone)]
1092pub struct Literal {
1093    inner: imp::Literal,
1094    _marker: ProcMacroAutoTraits,
1095}
1096
1097macro_rules! suffixed_int_literals {
1098    ($($name:ident => $kind:ident,)*) => ($(
1099        /// Creates a new suffixed integer literal with the specified value.
1100        ///
1101        /// This function will create an integer like `1u32` where the integer
1102        /// value specified is the first part of the token and the integral is
1103        /// also suffixed at the end. Literals created from negative numbers may
1104        /// not survive roundtrips through `TokenStream` or strings and may be
1105        /// broken into two tokens (`-` and positive literal).
1106        ///
1107        /// Literals created through this method have the `Span::call_site()`
1108        /// span by default, which can be configured with the `set_span` method
1109        /// below.
1110        pub fn $name(n: $kind) -> Literal {
1111            Literal::_new(imp::Literal::$name(n))
1112        }
1113    )*)
1114}
1115
1116macro_rules! unsuffixed_int_literals {
1117    ($($name:ident => $kind:ident,)*) => ($(
1118        /// Creates a new unsuffixed integer literal with the specified value.
1119        ///
1120        /// This function will create an integer like `1` where the integer
1121        /// value specified is the first part of the token. No suffix is
1122        /// specified on this token, meaning that invocations like
1123        /// `Literal::i8_unsuffixed(1)` are equivalent to
1124        /// `Literal::u32_unsuffixed(1)`. Literals created from negative numbers
1125        /// may not survive roundtrips through `TokenStream` or strings and may
1126        /// be broken into two tokens (`-` and positive literal).
1127        ///
1128        /// Literals created through this method have the `Span::call_site()`
1129        /// span by default, which can be configured with the `set_span` method
1130        /// below.
1131        pub fn $name(n: $kind) -> Literal {
1132            Literal::_new(imp::Literal::$name(n))
1133        }
1134    )*)
1135}
1136
1137impl Literal {
1138    fn _new(inner: imp::Literal) -> Self {
1139        Literal {
1140            inner,
1141            _marker: MARKER,
1142        }
1143    }
1144
1145    fn _new_fallback(inner: fallback::Literal) -> Self {
1146        Literal {
1147            inner: imp::Literal::from(inner),
1148            _marker: MARKER,
1149        }
1150    }
1151
1152    suffixed_int_literals! {
1153        u8_suffixed => u8,
1154        u16_suffixed => u16,
1155        u32_suffixed => u32,
1156        u64_suffixed => u64,
1157        u128_suffixed => u128,
1158        usize_suffixed => usize,
1159        i8_suffixed => i8,
1160        i16_suffixed => i16,
1161        i32_suffixed => i32,
1162        i64_suffixed => i64,
1163        i128_suffixed => i128,
1164        isize_suffixed => isize,
1165    }
1166
1167    unsuffixed_int_literals! {
1168        u8_unsuffixed => u8,
1169        u16_unsuffixed => u16,
1170        u32_unsuffixed => u32,
1171        u64_unsuffixed => u64,
1172        u128_unsuffixed => u128,
1173        usize_unsuffixed => usize,
1174        i8_unsuffixed => i8,
1175        i16_unsuffixed => i16,
1176        i32_unsuffixed => i32,
1177        i64_unsuffixed => i64,
1178        i128_unsuffixed => i128,
1179        isize_unsuffixed => isize,
1180    }
1181
1182    /// Creates a new unsuffixed floating-point literal.
1183    ///
1184    /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1185    /// the float's value is emitted directly into the token but no suffix is
1186    /// used, so it may be inferred to be a `f64` later in the compiler.
1187    /// Literals created from negative numbers may not survive round-trips
1188    /// through `TokenStream` or strings and may be broken into two tokens (`-`
1189    /// and positive literal).
1190    ///
1191    /// # Panics
1192    ///
1193    /// This function requires that the specified float is finite, for example
1194    /// if it is infinity or NaN this function will panic.
1195    pub fn f64_unsuffixed(f: f64) -> Literal {
1196        assert!(f.is_finite());
1197        Literal::_new(imp::Literal::f64_unsuffixed(f))
1198    }
1199
1200    /// Creates a new suffixed floating-point literal.
1201    ///
1202    /// This constructor will create a literal like `1.0f64` where the value
1203    /// specified is the preceding part of the token and `f64` is the suffix of
1204    /// the token. This token will always be inferred to be an `f64` in the
1205    /// compiler. Literals created from negative numbers may not survive
1206    /// round-trips through `TokenStream` or strings and may be broken into two
1207    /// tokens (`-` and positive literal).
1208    ///
1209    /// # Panics
1210    ///
1211    /// This function requires that the specified float is finite, for example
1212    /// if it is infinity or NaN this function will panic.
1213    pub fn f64_suffixed(f: f64) -> Literal {
1214        assert!(f.is_finite());
1215        Literal::_new(imp::Literal::f64_suffixed(f))
1216    }
1217
1218    /// Creates a new unsuffixed floating-point literal.
1219    ///
1220    /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1221    /// the float's value is emitted directly into the token but no suffix is
1222    /// used, so it may be inferred to be a `f64` later in the compiler.
1223    /// Literals created from negative numbers may not survive round-trips
1224    /// through `TokenStream` or strings and may be broken into two tokens (`-`
1225    /// and positive literal).
1226    ///
1227    /// # Panics
1228    ///
1229    /// This function requires that the specified float is finite, for example
1230    /// if it is infinity or NaN this function will panic.
1231    pub fn f32_unsuffixed(f: f32) -> Literal {
1232        assert!(f.is_finite());
1233        Literal::_new(imp::Literal::f32_unsuffixed(f))
1234    }
1235
1236    /// Creates a new suffixed floating-point literal.
1237    ///
1238    /// This constructor will create a literal like `1.0f32` where the value
1239    /// specified is the preceding part of the token and `f32` is the suffix of
1240    /// the token. This token will always be inferred to be an `f32` in the
1241    /// compiler. Literals created from negative numbers may not survive
1242    /// round-trips through `TokenStream` or strings and may be broken into two
1243    /// tokens (`-` and positive literal).
1244    ///
1245    /// # Panics
1246    ///
1247    /// This function requires that the specified float is finite, for example
1248    /// if it is infinity or NaN this function will panic.
1249    pub fn f32_suffixed(f: f32) -> Literal {
1250        assert!(f.is_finite());
1251        Literal::_new(imp::Literal::f32_suffixed(f))
1252    }
1253
1254    /// String literal.
1255    pub fn string(string: &str) -> Literal {
1256        Literal::_new(imp::Literal::string(string))
1257    }
1258
1259    /// Character literal.
1260    pub fn character(ch: char) -> Literal {
1261        Literal::_new(imp::Literal::character(ch))
1262    }
1263
1264    /// Byte character literal.
1265    pub fn byte_character(byte: u8) -> Literal {
1266        Literal::_new(imp::Literal::byte_character(byte))
1267    }
1268
1269    /// Byte string literal.
1270    pub fn byte_string(bytes: &[u8]) -> Literal {
1271        Literal::_new(imp::Literal::byte_string(bytes))
1272    }
1273
1274    /// C string literal.
1275    pub fn c_string(string: &CStr) -> Literal {
1276        Literal::_new(imp::Literal::c_string(string))
1277    }
1278
1279    /// Returns the span encompassing this literal.
1280    pub fn span(&self) -> Span {
1281        Span::_new(self.inner.span())
1282    }
1283
1284    /// Configures the span associated for this literal.
1285    pub fn set_span(&mut self, span: Span) {
1286        self.inner.set_span(span.inner);
1287    }
1288
1289    /// Returns a `Span` that is a subset of `self.span()` containing only
1290    /// the source bytes in range `range`. Returns `None` if the would-be
1291    /// trimmed span is outside the bounds of `self`.
1292    ///
1293    /// Warning: the underlying [`proc_macro::Literal::subspan`] method is
1294    /// nightly-only. When called from within a procedural macro not using a
1295    /// nightly compiler, this method will always return `None`.
1296    pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> {
1297        self.inner.subspan(range).map(Span::_new)
1298    }
1299
1300    // Intended for the `quote!` macro to use when constructing a proc-macro2
1301    // token out of a macro_rules $:literal token, which is already known to be
1302    // a valid literal. This avoids reparsing/validating the literal's string
1303    // representation. This is not public API other than for quote.
1304    #[doc(hidden)]
1305    pub unsafe fn from_str_unchecked(repr: &str) -> Self {
1306        Literal::_new(unsafe { imp::Literal::from_str_unchecked(repr) })
1307    }
1308}
1309
1310impl FromStr for Literal {
1311    type Err = LexError;
1312
1313    fn from_str(repr: &str) -> Result<Self, LexError> {
1314        match imp::Literal::from_str_checked(repr) {
1315            Ok(lit) => Ok(Literal::_new(lit)),
1316            Err(lex) => Err(LexError {
1317                inner: lex,
1318                _marker: MARKER,
1319            }),
1320        }
1321    }
1322}
1323
1324impl Debug for Literal {
1325    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1326        Debug::fmt(&self.inner, f)
1327    }
1328}
1329
1330impl Display for Literal {
1331    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1332        Display::fmt(&self.inner, f)
1333    }
1334}
1335
1336/// Public implementation details for the `TokenStream` type, such as iterators.
1337pub mod token_stream {
1338    use crate::marker::{ProcMacroAutoTraits, MARKER};
1339    use crate::{imp, TokenTree};
1340    use core::fmt::{self, Debug};
1341
1342    pub use crate::TokenStream;
1343
1344    /// An iterator over `TokenStream`'s `TokenTree`s.
1345    ///
1346    /// The iteration is "shallow", e.g. the iterator doesn't recurse into
1347    /// delimited groups, and returns whole groups as token trees.
1348    #[derive(Clone)]
1349    pub struct IntoIter {
1350        inner: imp::TokenTreeIter,
1351        _marker: ProcMacroAutoTraits,
1352    }
1353
1354    impl Iterator for IntoIter {
1355        type Item = TokenTree;
1356
1357        fn next(&mut self) -> Option<TokenTree> {
1358            self.inner.next()
1359        }
1360
1361        fn size_hint(&self) -> (usize, Option<usize>) {
1362            self.inner.size_hint()
1363        }
1364    }
1365
1366    impl Debug for IntoIter {
1367        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1368            f.write_str("TokenStream ")?;
1369            f.debug_list().entries(self.clone()).finish()
1370        }
1371    }
1372
1373    impl IntoIterator for TokenStream {
1374        type Item = TokenTree;
1375        type IntoIter = IntoIter;
1376
1377        fn into_iter(self) -> IntoIter {
1378            IntoIter {
1379                inner: self.inner.into_iter(),
1380                _marker: MARKER,
1381            }
1382        }
1383    }
1384}