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