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/1.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.31.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.63")]
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::doc_markdown,
97 clippy::items_after_statements,
98 clippy::let_underscore_untyped,
99 clippy::manual_assert,
100 clippy::must_use_candidate,
101 clippy::needless_doctest_main,
102 clippy::new_without_default,
103 clippy::return_self_not_must_use,
104 clippy::shadow_unrelated,
105 clippy::trivially_copy_pass_by_ref,
106 clippy::unnecessary_wraps,
107 clippy::unused_self,
108 clippy::used_underscore_binding,
109 clippy::vec_init_then_push
110)]
111
112#[cfg(all(procmacro2_semver_exempt, wrap_proc_macro, not(super_unstable)))]
113compile_error! {"\
114 Something is not right. If you've tried to turn on \
115 procmacro2_semver_exempt, you need to ensure that it \
116 is turned on for the compilation of the proc-macro2 \
117 build script as well.
118"}
119
120#[cfg(feature = "proc-macro")]
121extern crate proc_macro;
122
123mod marker;
124mod parse;
125mod rcvec;
126
127#[cfg(wrap_proc_macro)]
128mod detection;
129
130// Public for proc_macro2::fallback::force() and unforce(), but those are quite
131// a niche use case so we omit it from rustdoc.
132#[doc(hidden)]
133pub mod fallback;
134
135pub mod extra;
136
137#[cfg(not(wrap_proc_macro))]
138use crate::fallback as imp;
139#[path = "wrapper.rs"]
140#[cfg(wrap_proc_macro)]
141mod imp;
142
143#[cfg(span_locations)]
144mod convert;
145#[cfg(span_locations)]
146mod location;
147
148use crate::extra::DelimSpan;
149use crate::marker::Marker;
150use core::cmp::Ordering;
151use core::fmt::{self, Debug, Display};
152use core::hash::{Hash, Hasher};
153use core::iter::FromIterator;
154use core::ops::RangeBounds;
155use core::str::FromStr;
156use std::error::Error;
157#[cfg(procmacro2_semver_exempt)]
158use std::path::PathBuf;
159
160#[cfg(span_locations)]
161pub use crate::location::LineColumn;
162
163/// An abstract stream of tokens, or more concretely a sequence of token trees.
164///
165/// This type provides interfaces for iterating over token trees and for
166/// collecting token trees into one stream.
167///
168/// Token stream is both the input and output of `#[proc_macro]`,
169/// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions.
170#[derive(Clone)]
171pub struct TokenStream {
172 inner: imp::TokenStream,
173 _marker: Marker,
174}
175
176/// Error returned from `TokenStream::from_str`.
177pub struct LexError {
178 inner: imp::LexError,
179 _marker: Marker,
180}
181
182impl TokenStream {
183 fn _new(inner: imp::TokenStream) -> Self {
184 TokenStream {
185 inner,
186 _marker: Marker,
187 }
188 }
189
190 fn _new_fallback(inner: fallback::TokenStream) -> Self {
191 TokenStream {
192 inner: inner.into(),
193 _marker: Marker,
194 }
195 }
196
197 /// Returns an empty `TokenStream` containing no token trees.
198 pub fn new() -> Self {
199 TokenStream::_new(imp::TokenStream::new())
200 }
201
202 /// Checks if this `TokenStream` is empty.
203 pub fn is_empty(&self) -> bool {
204 self.inner.is_empty()
205 }
206}
207
208/// `TokenStream::default()` returns an empty stream,
209/// i.e. this is equivalent with `TokenStream::new()`.
210impl Default for TokenStream {
211 fn default() -> Self {
212 TokenStream::new()
213 }
214}
215
216/// Attempts to break the string into tokens and parse those tokens into a token
217/// stream.
218///
219/// May fail for a number of reasons, for example, if the string contains
220/// unbalanced delimiters or characters not existing in the language.
221///
222/// NOTE: Some errors may cause panics instead of returning `LexError`. We
223/// reserve the right to change these errors into `LexError`s later.
224impl FromStr for TokenStream {
225 type Err = LexError;
226
227 fn from_str(src: &str) -> Result<TokenStream, LexError> {
228 let e: TokenStream = src.parse().map_err(|e: LexError| LexError {
229 inner: e,
230 _marker: Marker,
231 })?;
232 Ok(TokenStream::_new(inner:e))
233 }
234}
235
236#[cfg(feature = "proc-macro")]
237#[cfg_attr(doc_cfg, doc(cfg(feature = "proc-macro")))]
238impl From<proc_macro::TokenStream> for TokenStream {
239 fn from(inner: proc_macro::TokenStream) -> Self {
240 TokenStream::_new(inner:inner.into())
241 }
242}
243
244#[cfg(feature = "proc-macro")]
245#[cfg_attr(doc_cfg, doc(cfg(feature = "proc-macro")))]
246impl From<TokenStream> for proc_macro::TokenStream {
247 fn from(inner: TokenStream) -> Self {
248 inner.inner.into()
249 }
250}
251
252impl From<TokenTree> for TokenStream {
253 fn from(token: TokenTree) -> Self {
254 TokenStream::_new(inner:imp::TokenStream::from(token))
255 }
256}
257
258impl Extend<TokenTree> for TokenStream {
259 fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, streams: I) {
260 self.inner.extend(iter:streams);
261 }
262}
263
264impl Extend<TokenStream> for TokenStream {
265 fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) {
266 self.inner
267 .extend(iter:streams.into_iter().map(|stream: TokenStream| stream.inner));
268 }
269}
270
271/// Collects a number of token trees into a single stream.
272impl FromIterator<TokenTree> for TokenStream {
273 fn from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self {
274 TokenStream::_new(inner:streams.into_iter().collect())
275 }
276}
277impl FromIterator<TokenStream> for TokenStream {
278 fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self {
279 TokenStream::_new(inner:streams.into_iter().map(|i: TokenStream| i.inner).collect())
280 }
281}
282
283/// Prints the token stream as a string that is supposed to be losslessly
284/// convertible back into the same token stream (modulo spans), except for
285/// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative
286/// numeric literals.
287impl Display for TokenStream {
288 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
289 Display::fmt(&self.inner, f)
290 }
291}
292
293/// Prints token in a form convenient for debugging.
294impl Debug for TokenStream {
295 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
296 Debug::fmt(&self.inner, f)
297 }
298}
299
300impl LexError {
301 pub fn span(&self) -> Span {
302 Span::_new(self.inner.span())
303 }
304}
305
306impl Debug for LexError {
307 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
308 Debug::fmt(&self.inner, f)
309 }
310}
311
312impl Display for LexError {
313 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
314 Display::fmt(&self.inner, f)
315 }
316}
317
318impl Error for LexError {}
319
320/// The source file of a given `Span`.
321///
322/// This type is semver exempt and not exposed by default.
323#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
324#[cfg_attr(doc_cfg, doc(cfg(procmacro2_semver_exempt)))]
325#[derive(Clone, PartialEq, Eq)]
326pub struct SourceFile {
327 inner: imp::SourceFile,
328 _marker: Marker,
329}
330
331#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
332impl SourceFile {
333 fn _new(inner: imp::SourceFile) -> Self {
334 SourceFile {
335 inner,
336 _marker: Marker,
337 }
338 }
339
340 /// Get the path to this source file.
341 ///
342 /// ### Note
343 ///
344 /// If the code span associated with this `SourceFile` was generated by an
345 /// external macro, this may not be an actual path on the filesystem. Use
346 /// [`is_real`] to check.
347 ///
348 /// Also note that even if `is_real` returns `true`, if
349 /// `--remap-path-prefix` was passed on the command line, the path as given
350 /// may not actually be valid.
351 ///
352 /// [`is_real`]: #method.is_real
353 pub fn path(&self) -> PathBuf {
354 self.inner.path()
355 }
356
357 /// Returns `true` if this source file is a real source file, and not
358 /// generated by an external macro's expansion.
359 pub fn is_real(&self) -> bool {
360 self.inner.is_real()
361 }
362}
363
364#[cfg(all(procmacro2_semver_exempt, any(not(wrap_proc_macro), super_unstable)))]
365impl Debug for SourceFile {
366 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
367 Debug::fmt(&self.inner, f)
368 }
369}
370
371/// A region of source code, along with macro expansion information.
372#[derive(Copy, Clone)]
373pub struct Span {
374 inner: imp::Span,
375 _marker: Marker,
376}
377
378impl Span {
379 fn _new(inner: imp::Span) -> Self {
380 Span {
381 inner,
382 _marker: Marker,
383 }
384 }
385
386 fn _new_fallback(inner: fallback::Span) -> Self {
387 Span {
388 inner: inner.into(),
389 _marker: Marker,
390 }
391 }
392
393 /// The span of the invocation of the current procedural macro.
394 ///
395 /// Identifiers created with this span will be resolved as if they were
396 /// written directly at the macro call location (call-site hygiene) and
397 /// other code at the macro call site will be able to refer to them as well.
398 pub fn call_site() -> Self {
399 Span::_new(imp::Span::call_site())
400 }
401
402 /// The span located at the invocation of the procedural macro, but with
403 /// local variables, labels, and `$crate` resolved at the definition site
404 /// of the macro. This is the same hygiene behavior as `macro_rules`.
405 ///
406 /// This function requires Rust 1.45 or later.
407 #[cfg(not(no_hygiene))]
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: &Group) => Display::fmt(self:t, f),
607 TokenTree::Ident(t: &Ident) => Display::fmt(self:t, f),
608 TokenTree::Punct(t: &Punct) => Display::fmt(self:t, f),
609 TokenTree::Literal(t: &Literal) => Display::fmt(self: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: &Group) => Debug::fmt(self:t, f),
621 TokenTree::Ident(t: &Ident) => {
622 let mut debug: DebugStruct<'_, '_> = f.debug_struct(name:"Ident");
623 debug.field(name:"sym", &format_args!("{}", t));
624 imp::debug_span_field_if_nontrivial(&mut debug, span:t.span().inner);
625 debug.finish()
626 }
627 TokenTree::Punct(t: &Punct) => Debug::fmt(self:t, f),
628 TokenTree::Literal(t: &Literal) => Debug::fmt(self: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, f:formatter)
752 }
753}
754
755impl Debug for Group {
756 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
757 Debug::fmt(&self.inner, f: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: DebugStruct<'_, '_> = fmt.debug_struct(name:"Punct");
837 debug.field(name:"char", &self.ch);
838 debug.field(name:"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/1.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/1.0/syn/fn.parse_str.html"><code
950 /// style="padding-right:0;">syn::parse_str</code></a><code
951 /// style="padding-left:0;">::&lt;Ident&gt;</code>
952 /// rather than `Ident::new`.
953 pub fn new(string: &str, span: Span) -> Self {
954 Ident::_new(imp::Ident::new(string, span.inner))
955 }
956
957 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). The
958 /// `string` argument must be a valid identifier permitted by the language
959 /// (including keywords, e.g. `fn`). Keywords which are usable in path
960 /// segments (e.g. `self`, `super`) are not supported, and will cause a
961 /// panic.
962 pub fn new_raw(string: &str, span: Span) -> Self {
963 Ident::_new_raw(string, span)
964 }
965
966 fn _new_raw(string: &str, span: Span) -> Self {
967 Ident::_new(imp::Ident::new_raw(string, span.inner))
968 }
969
970 /// Returns the span of this `Ident`.
971 pub fn span(&self) -> Span {
972 Span::_new(self.inner.span())
973 }
974
975 /// Configures the span of this `Ident`, possibly changing its hygiene
976 /// context.
977 pub fn set_span(&mut self, span: Span) {
978 self.inner.set_span(span.inner);
979 }
980}
981
982impl PartialEq for Ident {
983 fn eq(&self, other: &Ident) -> bool {
984 self.inner == other.inner
985 }
986}
987
988impl<T> PartialEq<T> for Ident
989where
990 T: ?Sized + AsRef<str>,
991{
992 fn eq(&self, other: &T) -> bool {
993 self.inner == other
994 }
995}
996
997impl Eq for Ident {}
998
999impl PartialOrd for Ident {
1000 fn partial_cmp(&self, other: &Ident) -> Option<Ordering> {
1001 Some(self.cmp(other))
1002 }
1003}
1004
1005impl Ord for Ident {
1006 fn cmp(&self, other: &Ident) -> Ordering {
1007 self.to_string().cmp(&other.to_string())
1008 }
1009}
1010
1011impl Hash for Ident {
1012 fn hash<H: Hasher>(&self, hasher: &mut H) {
1013 self.to_string().hash(state:hasher);
1014 }
1015}
1016
1017/// Prints the identifier as a string that should be losslessly convertible back
1018/// into the same identifier.
1019impl Display for Ident {
1020 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1021 Display::fmt(&self.inner, f)
1022 }
1023}
1024
1025impl Debug for Ident {
1026 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1027 Debug::fmt(&self.inner, f)
1028 }
1029}
1030
1031/// A literal string (`"hello"`), byte string (`b"hello"`), character (`'a'`),
1032/// byte character (`b'a'`), an integer or floating point number with or without
1033/// a suffix (`1`, `1u8`, `2.3`, `2.3f32`).
1034///
1035/// Boolean literals like `true` and `false` do not belong here, they are
1036/// `Ident`s.
1037#[derive(Clone)]
1038pub struct Literal {
1039 inner: imp::Literal,
1040 _marker: Marker,
1041}
1042
1043macro_rules! suffixed_int_literals {
1044 ($($name:ident => $kind:ident,)*) => ($(
1045 /// Creates a new suffixed integer literal with the specified value.
1046 ///
1047 /// This function will create an integer like `1u32` where the integer
1048 /// value specified is the first part of the token and the integral is
1049 /// also suffixed at the end. Literals created from negative numbers may
1050 /// not survive roundtrips through `TokenStream` or strings and may be
1051 /// broken into two tokens (`-` and positive literal).
1052 ///
1053 /// Literals created through this method have the `Span::call_site()`
1054 /// span by default, which can be configured with the `set_span` method
1055 /// below.
1056 pub fn $name(n: $kind) -> Literal {
1057 Literal::_new(imp::Literal::$name(n))
1058 }
1059 )*)
1060}
1061
1062macro_rules! unsuffixed_int_literals {
1063 ($($name:ident => $kind:ident,)*) => ($(
1064 /// Creates a new unsuffixed integer literal with the specified value.
1065 ///
1066 /// This function will create an integer like `1` where the integer
1067 /// value specified is the first part of the token. No suffix is
1068 /// specified on this token, meaning that invocations like
1069 /// `Literal::i8_unsuffixed(1)` are equivalent to
1070 /// `Literal::u32_unsuffixed(1)`. Literals created from negative numbers
1071 /// may not survive roundtrips through `TokenStream` or strings and may
1072 /// be broken into two tokens (`-` and positive literal).
1073 ///
1074 /// Literals created through this method have the `Span::call_site()`
1075 /// span by default, which can be configured with the `set_span` method
1076 /// below.
1077 pub fn $name(n: $kind) -> Literal {
1078 Literal::_new(imp::Literal::$name(n))
1079 }
1080 )*)
1081}
1082
1083impl Literal {
1084 fn _new(inner: imp::Literal) -> Self {
1085 Literal {
1086 inner,
1087 _marker: Marker,
1088 }
1089 }
1090
1091 fn _new_fallback(inner: fallback::Literal) -> Self {
1092 Literal {
1093 inner: inner.into(),
1094 _marker: Marker,
1095 }
1096 }
1097
1098 suffixed_int_literals! {
1099 u8_suffixed => u8,
1100 u16_suffixed => u16,
1101 u32_suffixed => u32,
1102 u64_suffixed => u64,
1103 u128_suffixed => u128,
1104 usize_suffixed => usize,
1105 i8_suffixed => i8,
1106 i16_suffixed => i16,
1107 i32_suffixed => i32,
1108 i64_suffixed => i64,
1109 i128_suffixed => i128,
1110 isize_suffixed => isize,
1111 }
1112
1113 unsuffixed_int_literals! {
1114 u8_unsuffixed => u8,
1115 u16_unsuffixed => u16,
1116 u32_unsuffixed => u32,
1117 u64_unsuffixed => u64,
1118 u128_unsuffixed => u128,
1119 usize_unsuffixed => usize,
1120 i8_unsuffixed => i8,
1121 i16_unsuffixed => i16,
1122 i32_unsuffixed => i32,
1123 i64_unsuffixed => i64,
1124 i128_unsuffixed => i128,
1125 isize_unsuffixed => isize,
1126 }
1127
1128 /// Creates a new unsuffixed floating-point literal.
1129 ///
1130 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1131 /// the float's value is emitted directly into the token but no suffix is
1132 /// used, so it may be inferred to be a `f64` later in the compiler.
1133 /// Literals created from negative numbers may not survive round-trips
1134 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1135 /// and positive literal).
1136 ///
1137 /// # Panics
1138 ///
1139 /// This function requires that the specified float is finite, for example
1140 /// if it is infinity or NaN this function will panic.
1141 pub fn f64_unsuffixed(f: f64) -> Literal {
1142 assert!(f.is_finite());
1143 Literal::_new(imp::Literal::f64_unsuffixed(f))
1144 }
1145
1146 /// Creates a new suffixed floating-point literal.
1147 ///
1148 /// This constructor will create a literal like `1.0f64` where the value
1149 /// specified is the preceding part of the token and `f64` is the suffix of
1150 /// the token. This token will always be inferred to be an `f64` in the
1151 /// compiler. Literals created from negative numbers may not survive
1152 /// round-trips through `TokenStream` or strings and may be broken into two
1153 /// tokens (`-` and positive literal).
1154 ///
1155 /// # Panics
1156 ///
1157 /// This function requires that the specified float is finite, for example
1158 /// if it is infinity or NaN this function will panic.
1159 pub fn f64_suffixed(f: f64) -> Literal {
1160 assert!(f.is_finite());
1161 Literal::_new(imp::Literal::f64_suffixed(f))
1162 }
1163
1164 /// Creates a new unsuffixed floating-point literal.
1165 ///
1166 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1167 /// the float's value is emitted directly into the token but no suffix is
1168 /// used, so it may be inferred to be a `f64` later in the compiler.
1169 /// Literals created from negative numbers may not survive round-trips
1170 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1171 /// and positive literal).
1172 ///
1173 /// # Panics
1174 ///
1175 /// This function requires that the specified float is finite, for example
1176 /// if it is infinity or NaN this function will panic.
1177 pub fn f32_unsuffixed(f: f32) -> Literal {
1178 assert!(f.is_finite());
1179 Literal::_new(imp::Literal::f32_unsuffixed(f))
1180 }
1181
1182 /// Creates a new suffixed floating-point literal.
1183 ///
1184 /// This constructor will create a literal like `1.0f32` where the value
1185 /// specified is the preceding part of the token and `f32` is the suffix of
1186 /// the token. This token will always be inferred to be an `f32` in the
1187 /// compiler. Literals created from negative numbers may not survive
1188 /// round-trips through `TokenStream` or strings and may be broken into two
1189 /// tokens (`-` 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 f32_suffixed(f: f32) -> Literal {
1196 assert!(f.is_finite());
1197 Literal::_new(imp::Literal::f32_suffixed(f))
1198 }
1199
1200 /// String literal.
1201 pub fn string(string: &str) -> Literal {
1202 Literal::_new(imp::Literal::string(string))
1203 }
1204
1205 /// Character literal.
1206 pub fn character(ch: char) -> Literal {
1207 Literal::_new(imp::Literal::character(ch))
1208 }
1209
1210 /// Byte string literal.
1211 pub fn byte_string(s: &[u8]) -> Literal {
1212 Literal::_new(imp::Literal::byte_string(s))
1213 }
1214
1215 /// Returns the span encompassing this literal.
1216 pub fn span(&self) -> Span {
1217 Span::_new(self.inner.span())
1218 }
1219
1220 /// Configures the span associated for this literal.
1221 pub fn set_span(&mut self, span: Span) {
1222 self.inner.set_span(span.inner);
1223 }
1224
1225 /// Returns a `Span` that is a subset of `self.span()` containing only
1226 /// the source bytes in range `range`. Returns `None` if the would-be
1227 /// trimmed span is outside the bounds of `self`.
1228 ///
1229 /// Warning: the underlying [`proc_macro::Literal::subspan`] method is
1230 /// nightly-only. When called from within a procedural macro not using a
1231 /// nightly compiler, this method will always return `None`.
1232 ///
1233 /// [`proc_macro::Literal::subspan`]: https://doc.rust-lang.org/proc_macro/struct.Literal.html#method.subspan
1234 pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> {
1235 self.inner.subspan(range).map(Span::_new)
1236 }
1237
1238 // Intended for the `quote!` macro to use when constructing a proc-macro2
1239 // token out of a macro_rules $:literal token, which is already known to be
1240 // a valid literal. This avoids reparsing/validating the literal's string
1241 // representation. This is not public API other than for quote.
1242 #[doc(hidden)]
1243 pub unsafe fn from_str_unchecked(repr: &str) -> Self {
1244 Literal::_new(imp::Literal::from_str_unchecked(repr))
1245 }
1246}
1247
1248impl FromStr for Literal {
1249 type Err = LexError;
1250
1251 fn from_str(repr: &str) -> Result<Self, LexError> {
1252 repr.parse().map(Literal::_new).map_err(|inner: LexError| LexError {
1253 inner,
1254 _marker: Marker,
1255 })
1256 }
1257}
1258
1259impl Debug for Literal {
1260 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1261 Debug::fmt(&self.inner, f)
1262 }
1263}
1264
1265impl Display for Literal {
1266 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1267 Display::fmt(&self.inner, f)
1268 }
1269}
1270
1271/// Public implementation details for the `TokenStream` type, such as iterators.
1272pub mod token_stream {
1273 use crate::marker::Marker;
1274 use crate::{imp, TokenTree};
1275 use core::fmt::{self, Debug};
1276
1277 pub use crate::TokenStream;
1278
1279 /// An iterator over `TokenStream`'s `TokenTree`s.
1280 ///
1281 /// The iteration is "shallow", e.g. the iterator doesn't recurse into
1282 /// delimited groups, and returns whole groups as token trees.
1283 #[derive(Clone)]
1284 pub struct IntoIter {
1285 inner: imp::TokenTreeIter,
1286 _marker: Marker,
1287 }
1288
1289 impl Iterator for IntoIter {
1290 type Item = TokenTree;
1291
1292 fn next(&mut self) -> Option<TokenTree> {
1293 self.inner.next()
1294 }
1295
1296 fn size_hint(&self) -> (usize, Option<usize>) {
1297 self.inner.size_hint()
1298 }
1299 }
1300
1301 impl Debug for IntoIter {
1302 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1303 f.write_str("TokenStream ")?;
1304 f.debug_list().entries(self.clone()).finish()
1305 }
1306 }
1307
1308 impl IntoIterator for TokenStream {
1309 type Item = TokenTree;
1310 type IntoIter = IntoIter;
1311
1312 fn into_iter(self) -> IntoIter {
1313 IntoIter {
1314 inner: self.inner.into_iter(),
1315 _marker: Marker,
1316 }
1317 }
1318 }
1319}
1320