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