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