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