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