vendor/proc-macro2/src/lib.rs

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