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