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.8")] 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 85 #[cfg(use_proc_macro)] 86 extern crate proc_macro; 87 88 use std::cmp::Ordering; 89 use std::fmt; 90 use std::hash::{Hash, Hasher}; 91 use std::iter::FromIterator; 92 use std::marker; 93 use std::ops::RangeBounds; 94 #[cfg(procmacro2_semver_exempt)] 95 use std::path::PathBuf; 96 use std::rc::Rc; 97 use std::str::FromStr; 98 99 #[macro_use] 100 mod strnom; 101 mod fallback; 102 103 #[cfg(not(wrap_proc_macro))] 104 use crate::fallback as imp; 105 #[path = "wrapper.rs"] 106 #[cfg(wrap_proc_macro)] 107 mod imp; 108 109 /// An abstract stream of tokens, or more concretely a sequence of token trees. 110 /// 111 /// This type provides interfaces for iterating over token trees and for 112 /// collecting token trees into one stream. 113 /// 114 /// Token stream is both the input and output of `#[proc_macro]`, 115 /// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions. 116 #[derive(Clone)] 117 pub struct TokenStream { 118 inner: imp::TokenStream, 119 _marker: marker::PhantomData<Rc<()>>, 120 } 121 122 /// Error returned from `TokenStream::from_str`. 123 pub struct LexError { 124 inner: imp::LexError, 125 _marker: marker::PhantomData<Rc<()>>, 126 } 127 128 impl TokenStream { _new(inner: imp::TokenStream) -> TokenStream129 fn _new(inner: imp::TokenStream) -> TokenStream { 130 TokenStream { 131 inner, 132 _marker: marker::PhantomData, 133 } 134 } 135 _new_stable(inner: fallback::TokenStream) -> TokenStream136 fn _new_stable(inner: fallback::TokenStream) -> TokenStream { 137 TokenStream { 138 inner: inner.into(), 139 _marker: marker::PhantomData, 140 } 141 } 142 143 /// Returns an empty `TokenStream` containing no token trees. new() -> TokenStream144 pub fn new() -> TokenStream { 145 TokenStream::_new(imp::TokenStream::new()) 146 } 147 148 /// Checks if this `TokenStream` is empty. is_empty(&self) -> bool149 pub fn is_empty(&self) -> bool { 150 self.inner.is_empty() 151 } 152 } 153 154 /// `TokenStream::default()` returns an empty stream, 155 /// i.e. this is equivalent with `TokenStream::new()`. 156 impl Default for TokenStream { default() -> Self157 fn default() -> Self { 158 TokenStream::new() 159 } 160 } 161 162 /// Attempts to break the string into tokens and parse those tokens into a token 163 /// stream. 164 /// 165 /// May fail for a number of reasons, for example, if the string contains 166 /// unbalanced delimiters or characters not existing in the language. 167 /// 168 /// NOTE: Some errors may cause panics instead of returning `LexError`. We 169 /// reserve the right to change these errors into `LexError`s later. 170 impl FromStr for TokenStream { 171 type Err = LexError; 172 from_str(src: &str) -> Result<TokenStream, LexError>173 fn from_str(src: &str) -> Result<TokenStream, LexError> { 174 let e = src.parse().map_err(|e| LexError { 175 inner: e, 176 _marker: marker::PhantomData, 177 })?; 178 Ok(TokenStream::_new(e)) 179 } 180 } 181 182 #[cfg(use_proc_macro)] 183 impl From<proc_macro::TokenStream> for TokenStream { from(inner: proc_macro::TokenStream) -> TokenStream184 fn from(inner: proc_macro::TokenStream) -> TokenStream { 185 TokenStream::_new(inner.into()) 186 } 187 } 188 189 #[cfg(use_proc_macro)] 190 impl From<TokenStream> for proc_macro::TokenStream { from(inner: TokenStream) -> proc_macro::TokenStream191 fn from(inner: TokenStream) -> proc_macro::TokenStream { 192 inner.inner.into() 193 } 194 } 195 196 impl From<TokenTree> for TokenStream { from(token: TokenTree) -> Self197 fn from(token: TokenTree) -> Self { 198 TokenStream::_new(imp::TokenStream::from(token)) 199 } 200 } 201 202 impl Extend<TokenTree> for TokenStream { extend<I: IntoIterator<Item = TokenTree>>(&mut self, streams: I)203 fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, streams: I) { 204 self.inner.extend(streams) 205 } 206 } 207 208 impl Extend<TokenStream> for TokenStream { extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I)209 fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) { 210 self.inner 211 .extend(streams.into_iter().map(|stream| stream.inner)) 212 } 213 } 214 215 /// Collects a number of token trees into a single stream. 216 impl FromIterator<TokenTree> for TokenStream { from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self217 fn from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self { 218 TokenStream::_new(streams.into_iter().collect()) 219 } 220 } 221 impl FromIterator<TokenStream> for TokenStream { from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self222 fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self { 223 TokenStream::_new(streams.into_iter().map(|i| i.inner).collect()) 224 } 225 } 226 227 /// Prints the token stream as a string that is supposed to be losslessly 228 /// convertible back into the same token stream (modulo spans), except for 229 /// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative 230 /// numeric literals. 231 impl fmt::Display for TokenStream { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result232 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 233 self.inner.fmt(f) 234 } 235 } 236 237 /// Prints token in a form convenient for debugging. 238 impl fmt::Debug for TokenStream { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result239 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 240 self.inner.fmt(f) 241 } 242 } 243 244 impl fmt::Debug for LexError { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result245 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 246 self.inner.fmt(f) 247 } 248 } 249 250 /// The source file of a given `Span`. 251 /// 252 /// This type is semver exempt and not exposed by default. 253 #[cfg(procmacro2_semver_exempt)] 254 #[derive(Clone, PartialEq, Eq)] 255 pub struct SourceFile { 256 inner: imp::SourceFile, 257 _marker: marker::PhantomData<Rc<()>>, 258 } 259 260 #[cfg(procmacro2_semver_exempt)] 261 impl SourceFile { _new(inner: imp::SourceFile) -> Self262 fn _new(inner: imp::SourceFile) -> Self { 263 SourceFile { 264 inner, 265 _marker: marker::PhantomData, 266 } 267 } 268 269 /// Get the path to this source file. 270 /// 271 /// ### Note 272 /// 273 /// If the code span associated with this `SourceFile` was generated by an 274 /// external macro, this may not be an actual path on the filesystem. Use 275 /// [`is_real`] to check. 276 /// 277 /// Also note that even if `is_real` returns `true`, if 278 /// `--remap-path-prefix` was passed on the command line, the path as given 279 /// may not actually be valid. 280 /// 281 /// [`is_real`]: #method.is_real path(&self) -> PathBuf282 pub fn path(&self) -> PathBuf { 283 self.inner.path() 284 } 285 286 /// Returns `true` if this source file is a real source file, and not 287 /// generated by an external macro's expansion. is_real(&self) -> bool288 pub fn is_real(&self) -> bool { 289 self.inner.is_real() 290 } 291 } 292 293 #[cfg(procmacro2_semver_exempt)] 294 impl fmt::Debug for SourceFile { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result295 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 296 self.inner.fmt(f) 297 } 298 } 299 300 /// A line-column pair representing the start or end of a `Span`. 301 /// 302 /// This type is semver exempt and not exposed by default. 303 #[cfg(span_locations)] 304 #[derive(Copy, Clone, Debug, PartialEq, Eq)] 305 pub struct LineColumn { 306 /// The 1-indexed line in the source file on which the span starts or ends 307 /// (inclusive). 308 pub line: usize, 309 /// The 0-indexed column (in UTF-8 characters) in the source file on which 310 /// the span starts or ends (inclusive). 311 pub column: usize, 312 } 313 314 /// A region of source code, along with macro expansion information. 315 #[derive(Copy, Clone)] 316 pub struct Span { 317 inner: imp::Span, 318 _marker: marker::PhantomData<Rc<()>>, 319 } 320 321 impl Span { _new(inner: imp::Span) -> Span322 fn _new(inner: imp::Span) -> Span { 323 Span { 324 inner, 325 _marker: marker::PhantomData, 326 } 327 } 328 _new_stable(inner: fallback::Span) -> Span329 fn _new_stable(inner: fallback::Span) -> Span { 330 Span { 331 inner: inner.into(), 332 _marker: marker::PhantomData, 333 } 334 } 335 336 /// The span of the invocation of the current procedural macro. 337 /// 338 /// Identifiers created with this span will be resolved as if they were 339 /// written directly at the macro call location (call-site hygiene) and 340 /// other code at the macro call site will be able to refer to them as well. call_site() -> Span341 pub fn call_site() -> Span { 342 Span::_new(imp::Span::call_site()) 343 } 344 345 /// A span that resolves at the macro definition site. 346 /// 347 /// This method is semver exempt and not exposed by default. 348 #[cfg(procmacro2_semver_exempt)] def_site() -> Span349 pub fn def_site() -> Span { 350 Span::_new(imp::Span::def_site()) 351 } 352 353 /// Creates a new span with the same line/column information as `self` but 354 /// that resolves symbols as though it were at `other`. 355 /// 356 /// This method is semver exempt and not exposed by default. 357 #[cfg(procmacro2_semver_exempt)] resolved_at(&self, other: Span) -> Span358 pub fn resolved_at(&self, other: Span) -> Span { 359 Span::_new(self.inner.resolved_at(other.inner)) 360 } 361 362 /// Creates a new span with the same name resolution behavior as `self` but 363 /// with the line/column information of `other`. 364 /// 365 /// This method is semver exempt and not exposed by default. 366 #[cfg(procmacro2_semver_exempt)] located_at(&self, other: Span) -> Span367 pub fn located_at(&self, other: Span) -> Span { 368 Span::_new(self.inner.located_at(other.inner)) 369 } 370 371 /// Convert `proc_macro2::Span` to `proc_macro::Span`. 372 /// 373 /// This method is available when building with a nightly compiler, or when 374 /// building with rustc 1.29+ *without* semver exempt features. 375 /// 376 /// # Panics 377 /// 378 /// Panics if called from outside of a procedural macro. Unlike 379 /// `proc_macro2::Span`, the `proc_macro::Span` type can only exist within 380 /// the context of a procedural macro invocation. 381 #[cfg(wrap_proc_macro)] unwrap(self) -> proc_macro::Span382 pub fn unwrap(self) -> proc_macro::Span { 383 self.inner.unwrap() 384 } 385 386 // Soft deprecated. Please use Span::unwrap. 387 #[cfg(wrap_proc_macro)] 388 #[doc(hidden)] unstable(self) -> proc_macro::Span389 pub fn unstable(self) -> proc_macro::Span { 390 self.unwrap() 391 } 392 393 /// The original source file into which this span points. 394 /// 395 /// This method is semver exempt and not exposed by default. 396 #[cfg(procmacro2_semver_exempt)] source_file(&self) -> SourceFile397 pub fn source_file(&self) -> SourceFile { 398 SourceFile::_new(self.inner.source_file()) 399 } 400 401 /// Get the starting line/column in the source file for this span. 402 /// 403 /// This method requires the `"span-locations"` feature to be enabled. 404 #[cfg(span_locations)] start(&self) -> LineColumn405 pub fn start(&self) -> LineColumn { 406 let imp::LineColumn { line, column } = self.inner.start(); 407 LineColumn { line, column } 408 } 409 410 /// Get the ending line/column in the source file for this span. 411 /// 412 /// This method requires the `"span-locations"` feature to be enabled. 413 #[cfg(span_locations)] end(&self) -> LineColumn414 pub fn end(&self) -> LineColumn { 415 let imp::LineColumn { line, column } = self.inner.end(); 416 LineColumn { line, column } 417 } 418 419 /// Create a new span encompassing `self` and `other`. 420 /// 421 /// Returns `None` if `self` and `other` are from different files. 422 /// 423 /// Warning: the underlying [`proc_macro::Span::join`] method is 424 /// nightly-only. When called from within a procedural macro not using a 425 /// nightly compiler, this method will always return `None`. 426 /// 427 /// [`proc_macro::Span::join`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.join join(&self, other: Span) -> Option<Span>428 pub fn join(&self, other: Span) -> Option<Span> { 429 self.inner.join(other.inner).map(Span::_new) 430 } 431 432 /// Compares two spans to see if they're equal. 433 /// 434 /// This method is semver exempt and not exposed by default. 435 #[cfg(procmacro2_semver_exempt)] eq(&self, other: &Span) -> bool436 pub fn eq(&self, other: &Span) -> bool { 437 self.inner.eq(&other.inner) 438 } 439 } 440 441 /// Prints a span in a form convenient for debugging. 442 impl fmt::Debug for Span { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result443 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 444 self.inner.fmt(f) 445 } 446 } 447 448 /// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`). 449 #[derive(Clone)] 450 pub enum TokenTree { 451 /// A token stream surrounded by bracket delimiters. 452 Group(Group), 453 /// An identifier. 454 Ident(Ident), 455 /// A single punctuation character (`+`, `,`, `$`, etc.). 456 Punct(Punct), 457 /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc. 458 Literal(Literal), 459 } 460 461 impl TokenTree { 462 /// Returns the span of this tree, delegating to the `span` method of 463 /// the contained token or a delimited stream. span(&self) -> Span464 pub fn span(&self) -> Span { 465 match *self { 466 TokenTree::Group(ref t) => t.span(), 467 TokenTree::Ident(ref t) => t.span(), 468 TokenTree::Punct(ref t) => t.span(), 469 TokenTree::Literal(ref t) => t.span(), 470 } 471 } 472 473 /// Configures the span for *only this token*. 474 /// 475 /// Note that if this token is a `Group` then this method will not configure 476 /// the span of each of the internal tokens, this will simply delegate to 477 /// the `set_span` method of each variant. set_span(&mut self, span: Span)478 pub fn set_span(&mut self, span: Span) { 479 match *self { 480 TokenTree::Group(ref mut t) => t.set_span(span), 481 TokenTree::Ident(ref mut t) => t.set_span(span), 482 TokenTree::Punct(ref mut t) => t.set_span(span), 483 TokenTree::Literal(ref mut t) => t.set_span(span), 484 } 485 } 486 } 487 488 impl From<Group> for TokenTree { from(g: Group) -> TokenTree489 fn from(g: Group) -> TokenTree { 490 TokenTree::Group(g) 491 } 492 } 493 494 impl From<Ident> for TokenTree { from(g: Ident) -> TokenTree495 fn from(g: Ident) -> TokenTree { 496 TokenTree::Ident(g) 497 } 498 } 499 500 impl From<Punct> for TokenTree { from(g: Punct) -> TokenTree501 fn from(g: Punct) -> TokenTree { 502 TokenTree::Punct(g) 503 } 504 } 505 506 impl From<Literal> for TokenTree { from(g: Literal) -> TokenTree507 fn from(g: Literal) -> TokenTree { 508 TokenTree::Literal(g) 509 } 510 } 511 512 /// Prints the token tree as a string that is supposed to be losslessly 513 /// convertible back into the same token tree (modulo spans), except for 514 /// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative 515 /// numeric literals. 516 impl fmt::Display for TokenTree { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result517 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 518 match *self { 519 TokenTree::Group(ref t) => t.fmt(f), 520 TokenTree::Ident(ref t) => t.fmt(f), 521 TokenTree::Punct(ref t) => t.fmt(f), 522 TokenTree::Literal(ref t) => t.fmt(f), 523 } 524 } 525 } 526 527 /// Prints token tree in a form convenient for debugging. 528 impl fmt::Debug for TokenTree { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result529 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 530 // Each of these has the name in the struct type in the derived debug, 531 // so don't bother with an extra layer of indirection 532 match *self { 533 TokenTree::Group(ref t) => t.fmt(f), 534 TokenTree::Ident(ref t) => { 535 let mut debug = f.debug_struct("Ident"); 536 debug.field("sym", &format_args!("{}", t)); 537 imp::debug_span_field_if_nontrivial(&mut debug, t.span().inner); 538 debug.finish() 539 } 540 TokenTree::Punct(ref t) => t.fmt(f), 541 TokenTree::Literal(ref t) => t.fmt(f), 542 } 543 } 544 } 545 546 /// A delimited token stream. 547 /// 548 /// A `Group` internally contains a `TokenStream` which is surrounded by 549 /// `Delimiter`s. 550 #[derive(Clone)] 551 pub struct Group { 552 inner: imp::Group, 553 } 554 555 /// Describes how a sequence of token trees is delimited. 556 #[derive(Copy, Clone, Debug, Eq, PartialEq)] 557 pub enum Delimiter { 558 /// `( ... )` 559 Parenthesis, 560 /// `{ ... }` 561 Brace, 562 /// `[ ... ]` 563 Bracket, 564 /// `Ø ... Ø` 565 /// 566 /// An implicit delimiter, that may, for example, appear around tokens 567 /// coming from a "macro variable" `$var`. It is important to preserve 568 /// operator priorities in cases like `$var * 3` where `$var` is `1 + 2`. 569 /// Implicit delimiters may not survive roundtrip of a token stream through 570 /// a string. 571 None, 572 } 573 574 impl Group { _new(inner: imp::Group) -> Self575 fn _new(inner: imp::Group) -> Self { 576 Group { inner } 577 } 578 _new_stable(inner: fallback::Group) -> Self579 fn _new_stable(inner: fallback::Group) -> Self { 580 Group { 581 inner: inner.into(), 582 } 583 } 584 585 /// Creates a new `Group` with the given delimiter and token stream. 586 /// 587 /// This constructor will set the span for this group to 588 /// `Span::call_site()`. To change the span you can use the `set_span` 589 /// method below. new(delimiter: Delimiter, stream: TokenStream) -> Group590 pub fn new(delimiter: Delimiter, stream: TokenStream) -> Group { 591 Group { 592 inner: imp::Group::new(delimiter, stream.inner), 593 } 594 } 595 596 /// Returns the delimiter of this `Group` delimiter(&self) -> Delimiter597 pub fn delimiter(&self) -> Delimiter { 598 self.inner.delimiter() 599 } 600 601 /// Returns the `TokenStream` of tokens that are delimited in this `Group`. 602 /// 603 /// Note that the returned token stream does not include the delimiter 604 /// returned above. stream(&self) -> TokenStream605 pub fn stream(&self) -> TokenStream { 606 TokenStream::_new(self.inner.stream()) 607 } 608 609 /// Returns the span for the delimiters of this token stream, spanning the 610 /// entire `Group`. 611 /// 612 /// ```text 613 /// pub fn span(&self) -> Span { 614 /// ^^^^^^^ 615 /// ``` span(&self) -> Span616 pub fn span(&self) -> Span { 617 Span::_new(self.inner.span()) 618 } 619 620 /// Returns the span pointing to the opening delimiter of this group. 621 /// 622 /// ```text 623 /// pub fn span_open(&self) -> Span { 624 /// ^ 625 /// ``` span_open(&self) -> Span626 pub fn span_open(&self) -> Span { 627 Span::_new(self.inner.span_open()) 628 } 629 630 /// Returns the span pointing to the closing delimiter of this group. 631 /// 632 /// ```text 633 /// pub fn span_close(&self) -> Span { 634 /// ^ 635 /// ``` span_close(&self) -> Span636 pub fn span_close(&self) -> Span { 637 Span::_new(self.inner.span_close()) 638 } 639 640 /// Configures the span for this `Group`'s delimiters, but not its internal 641 /// tokens. 642 /// 643 /// This method will **not** set the span of all the internal tokens spanned 644 /// by this group, but rather it will only set the span of the delimiter 645 /// tokens at the level of the `Group`. set_span(&mut self, span: Span)646 pub fn set_span(&mut self, span: Span) { 647 self.inner.set_span(span.inner) 648 } 649 } 650 651 /// Prints the group as a string that should be losslessly convertible back 652 /// into the same group (modulo spans), except for possibly `TokenTree::Group`s 653 /// with `Delimiter::None` delimiters. 654 impl fmt::Display for Group { fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result655 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { 656 fmt::Display::fmt(&self.inner, formatter) 657 } 658 } 659 660 impl fmt::Debug for Group { fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result661 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { 662 fmt::Debug::fmt(&self.inner, formatter) 663 } 664 } 665 666 /// An `Punct` is an single punctuation character like `+`, `-` or `#`. 667 /// 668 /// Multicharacter operators like `+=` are represented as two instances of 669 /// `Punct` with different forms of `Spacing` returned. 670 #[derive(Clone)] 671 pub struct Punct { 672 op: char, 673 spacing: Spacing, 674 span: Span, 675 } 676 677 /// Whether an `Punct` is followed immediately by another `Punct` or followed by 678 /// another token or whitespace. 679 #[derive(Copy, Clone, Debug, Eq, PartialEq)] 680 pub enum Spacing { 681 /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`. 682 Alone, 683 /// E.g. `+` is `Joint` in `+=` or `'` is `Joint` in `'#`. 684 /// 685 /// Additionally, single quote `'` can join with identifiers to form 686 /// lifetimes `'ident`. 687 Joint, 688 } 689 690 impl Punct { 691 /// Creates a new `Punct` from the given character and spacing. 692 /// 693 /// The `ch` argument must be a valid punctuation character permitted by the 694 /// language, otherwise the function will panic. 695 /// 696 /// The returned `Punct` will have the default span of `Span::call_site()` 697 /// which can be further configured with the `set_span` method below. new(op: char, spacing: Spacing) -> Punct698 pub fn new(op: char, spacing: Spacing) -> Punct { 699 Punct { 700 op, 701 spacing, 702 span: Span::call_site(), 703 } 704 } 705 706 /// Returns the value of this punctuation character as `char`. as_char(&self) -> char707 pub fn as_char(&self) -> char { 708 self.op 709 } 710 711 /// Returns the spacing of this punctuation character, indicating whether 712 /// it's immediately followed by another `Punct` in the token stream, so 713 /// they can potentially be combined into a multicharacter operator 714 /// (`Joint`), or it's followed by some other token or whitespace (`Alone`) 715 /// so the operator has certainly ended. spacing(&self) -> Spacing716 pub fn spacing(&self) -> Spacing { 717 self.spacing 718 } 719 720 /// Returns the span for this punctuation character. span(&self) -> Span721 pub fn span(&self) -> Span { 722 self.span 723 } 724 725 /// Configure the span for this punctuation character. set_span(&mut self, span: Span)726 pub fn set_span(&mut self, span: Span) { 727 self.span = span; 728 } 729 } 730 731 /// Prints the punctuation character as a string that should be losslessly 732 /// convertible back into the same character. 733 impl fmt::Display for Punct { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result734 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 735 self.op.fmt(f) 736 } 737 } 738 739 impl fmt::Debug for Punct { fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result740 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { 741 let mut debug = fmt.debug_struct("Punct"); 742 debug.field("op", &self.op); 743 debug.field("spacing", &self.spacing); 744 imp::debug_span_field_if_nontrivial(&mut debug, self.span.inner); 745 debug.finish() 746 } 747 } 748 749 /// A word of Rust code, which may be a keyword or legal variable name. 750 /// 751 /// An identifier consists of at least one Unicode code point, the first of 752 /// which has the XID_Start property and the rest of which have the XID_Continue 753 /// property. 754 /// 755 /// - The empty string is not an identifier. Use `Option<Ident>`. 756 /// - A lifetime is not an identifier. Use `syn::Lifetime` instead. 757 /// 758 /// An identifier constructed with `Ident::new` is permitted to be a Rust 759 /// keyword, though parsing one through its [`Parse`] implementation rejects 760 /// Rust keywords. Use `input.call(Ident::parse_any)` when parsing to match the 761 /// behaviour of `Ident::new`. 762 /// 763 /// [`Parse`]: https://docs.rs/syn/1.0/syn/parse/trait.Parse.html 764 /// 765 /// # Examples 766 /// 767 /// A new ident can be created from a string using the `Ident::new` function. 768 /// A span must be provided explicitly which governs the name resolution 769 /// behavior of the resulting identifier. 770 /// 771 /// ``` 772 /// use proc_macro2::{Ident, Span}; 773 /// 774 /// fn main() { 775 /// let call_ident = Ident::new("calligraphy", Span::call_site()); 776 /// 777 /// println!("{}", call_ident); 778 /// } 779 /// ``` 780 /// 781 /// An ident can be interpolated into a token stream using the `quote!` macro. 782 /// 783 /// ``` 784 /// use proc_macro2::{Ident, Span}; 785 /// use quote::quote; 786 /// 787 /// fn main() { 788 /// let ident = Ident::new("demo", Span::call_site()); 789 /// 790 /// // Create a variable binding whose name is this ident. 791 /// let expanded = quote! { let #ident = 10; }; 792 /// 793 /// // Create a variable binding with a slightly different name. 794 /// let temp_ident = Ident::new(&format!("new_{}", ident), Span::call_site()); 795 /// let expanded = quote! { let #temp_ident = 10; }; 796 /// } 797 /// ``` 798 /// 799 /// A string representation of the ident is available through the `to_string()` 800 /// method. 801 /// 802 /// ``` 803 /// # use proc_macro2::{Ident, Span}; 804 /// # 805 /// # let ident = Ident::new("another_identifier", Span::call_site()); 806 /// # 807 /// // Examine the ident as a string. 808 /// let ident_string = ident.to_string(); 809 /// if ident_string.len() > 60 { 810 /// println!("Very long identifier: {}", ident_string) 811 /// } 812 /// ``` 813 #[derive(Clone)] 814 pub struct Ident { 815 inner: imp::Ident, 816 _marker: marker::PhantomData<Rc<()>>, 817 } 818 819 impl Ident { _new(inner: imp::Ident) -> Ident820 fn _new(inner: imp::Ident) -> Ident { 821 Ident { 822 inner, 823 _marker: marker::PhantomData, 824 } 825 } 826 827 /// Creates a new `Ident` with the given `string` as well as the specified 828 /// `span`. 829 /// 830 /// The `string` argument must be a valid identifier permitted by the 831 /// language, otherwise the function will panic. 832 /// 833 /// Note that `span`, currently in rustc, configures the hygiene information 834 /// for this identifier. 835 /// 836 /// As of this time `Span::call_site()` explicitly opts-in to "call-site" 837 /// hygiene meaning that identifiers created with this span will be resolved 838 /// as if they were written directly at the location of the macro call, and 839 /// other code at the macro call site will be able to refer to them as well. 840 /// 841 /// Later spans like `Span::def_site()` will allow to opt-in to 842 /// "definition-site" hygiene meaning that identifiers created with this 843 /// span will be resolved at the location of the macro definition and other 844 /// code at the macro call site will not be able to refer to them. 845 /// 846 /// Due to the current importance of hygiene this constructor, unlike other 847 /// tokens, requires a `Span` to be specified at construction. 848 /// 849 /// # Panics 850 /// 851 /// Panics if the input string is neither a keyword nor a legal variable 852 /// name. If you are not sure whether the string contains an identifier and 853 /// need to handle an error case, use 854 /// <a href="https://docs.rs/syn/1.0/syn/fn.parse_str.html"><code 855 /// style="padding-right:0;">syn::parse_str</code></a><code 856 /// style="padding-left:0;">::<Ident></code> 857 /// rather than `Ident::new`. new(string: &str, span: Span) -> Ident858 pub fn new(string: &str, span: Span) -> Ident { 859 Ident::_new(imp::Ident::new(string, span.inner)) 860 } 861 862 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). 863 /// 864 /// This method is semver exempt and not exposed by default. 865 #[cfg(procmacro2_semver_exempt)] new_raw(string: &str, span: Span) -> Ident866 pub fn new_raw(string: &str, span: Span) -> Ident { 867 Ident::_new_raw(string, span) 868 } 869 _new_raw(string: &str, span: Span) -> Ident870 fn _new_raw(string: &str, span: Span) -> Ident { 871 Ident::_new(imp::Ident::new_raw(string, span.inner)) 872 } 873 874 /// Returns the span of this `Ident`. span(&self) -> Span875 pub fn span(&self) -> Span { 876 Span::_new(self.inner.span()) 877 } 878 879 /// Configures the span of this `Ident`, possibly changing its hygiene 880 /// context. set_span(&mut self, span: Span)881 pub fn set_span(&mut self, span: Span) { 882 self.inner.set_span(span.inner); 883 } 884 } 885 886 impl PartialEq for Ident { eq(&self, other: &Ident) -> bool887 fn eq(&self, other: &Ident) -> bool { 888 self.inner == other.inner 889 } 890 } 891 892 impl<T> PartialEq<T> for Ident 893 where 894 T: ?Sized + AsRef<str>, 895 { eq(&self, other: &T) -> bool896 fn eq(&self, other: &T) -> bool { 897 self.inner == other 898 } 899 } 900 901 impl Eq for Ident {} 902 903 impl PartialOrd for Ident { partial_cmp(&self, other: &Ident) -> Option<Ordering>904 fn partial_cmp(&self, other: &Ident) -> Option<Ordering> { 905 Some(self.cmp(other)) 906 } 907 } 908 909 impl Ord for Ident { cmp(&self, other: &Ident) -> Ordering910 fn cmp(&self, other: &Ident) -> Ordering { 911 self.to_string().cmp(&other.to_string()) 912 } 913 } 914 915 impl Hash for Ident { hash<H: Hasher>(&self, hasher: &mut H)916 fn hash<H: Hasher>(&self, hasher: &mut H) { 917 self.to_string().hash(hasher) 918 } 919 } 920 921 /// Prints the identifier as a string that should be losslessly convertible back 922 /// into the same identifier. 923 impl fmt::Display for Ident { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result924 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 925 self.inner.fmt(f) 926 } 927 } 928 929 impl fmt::Debug for Ident { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result930 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 931 self.inner.fmt(f) 932 } 933 } 934 935 /// A literal string (`"hello"`), byte string (`b"hello"`), character (`'a'`), 936 /// byte character (`b'a'`), an integer or floating point number with or without 937 /// a suffix (`1`, `1u8`, `2.3`, `2.3f32`). 938 /// 939 /// Boolean literals like `true` and `false` do not belong here, they are 940 /// `Ident`s. 941 #[derive(Clone)] 942 pub struct Literal { 943 inner: imp::Literal, 944 _marker: marker::PhantomData<Rc<()>>, 945 } 946 947 macro_rules! suffixed_int_literals { 948 ($($name:ident => $kind:ident,)*) => ($( 949 /// Creates a new suffixed integer literal with the specified value. 950 /// 951 /// This function will create an integer like `1u32` where the integer 952 /// value specified is the first part of the token and the integral is 953 /// also suffixed at the end. Literals created from negative numbers may 954 /// not survive rountrips through `TokenStream` or strings and may be 955 /// broken into two tokens (`-` and positive literal). 956 /// 957 /// Literals created through this method have the `Span::call_site()` 958 /// span by default, which can be configured with the `set_span` method 959 /// below. 960 pub fn $name(n: $kind) -> Literal { 961 Literal::_new(imp::Literal::$name(n)) 962 } 963 )*) 964 } 965 966 macro_rules! unsuffixed_int_literals { 967 ($($name:ident => $kind:ident,)*) => ($( 968 /// Creates a new unsuffixed integer literal with the specified value. 969 /// 970 /// This function will create an integer like `1` where the integer 971 /// value specified is the first part of the token. No suffix is 972 /// specified on this token, meaning that invocations like 973 /// `Literal::i8_unsuffixed(1)` are equivalent to 974 /// `Literal::u32_unsuffixed(1)`. Literals created from negative numbers 975 /// may not survive rountrips through `TokenStream` or strings and may 976 /// be broken into two tokens (`-` and positive literal). 977 /// 978 /// Literals created through this method have the `Span::call_site()` 979 /// span by default, which can be configured with the `set_span` method 980 /// below. 981 pub fn $name(n: $kind) -> Literal { 982 Literal::_new(imp::Literal::$name(n)) 983 } 984 )*) 985 } 986 987 impl Literal { _new(inner: imp::Literal) -> Literal988 fn _new(inner: imp::Literal) -> Literal { 989 Literal { 990 inner, 991 _marker: marker::PhantomData, 992 } 993 } 994 _new_stable(inner: fallback::Literal) -> Literal995 fn _new_stable(inner: fallback::Literal) -> Literal { 996 Literal { 997 inner: inner.into(), 998 _marker: marker::PhantomData, 999 } 1000 } 1001 1002 suffixed_int_literals! { 1003 u8_suffixed => u8, 1004 u16_suffixed => u16, 1005 u32_suffixed => u32, 1006 u64_suffixed => u64, 1007 u128_suffixed => u128, 1008 usize_suffixed => usize, 1009 i8_suffixed => i8, 1010 i16_suffixed => i16, 1011 i32_suffixed => i32, 1012 i64_suffixed => i64, 1013 i128_suffixed => i128, 1014 isize_suffixed => isize, 1015 } 1016 1017 unsuffixed_int_literals! { 1018 u8_unsuffixed => u8, 1019 u16_unsuffixed => u16, 1020 u32_unsuffixed => u32, 1021 u64_unsuffixed => u64, 1022 u128_unsuffixed => u128, 1023 usize_unsuffixed => usize, 1024 i8_unsuffixed => i8, 1025 i16_unsuffixed => i16, 1026 i32_unsuffixed => i32, 1027 i64_unsuffixed => i64, 1028 i128_unsuffixed => i128, 1029 isize_unsuffixed => isize, 1030 } 1031 1032 /// Creates a new unsuffixed floating-point literal. 1033 /// 1034 /// This constructor is similar to those like `Literal::i8_unsuffixed` where 1035 /// the float's value is emitted directly into the token but no suffix is 1036 /// used, so it may be inferred to be a `f64` later in the compiler. 1037 /// Literals created from negative numbers may not survive rountrips through 1038 /// `TokenStream` or strings and may be broken into two tokens (`-` and 1039 /// positive literal). 1040 /// 1041 /// # Panics 1042 /// 1043 /// This function requires that the specified float is finite, for example 1044 /// if it is infinity or NaN this function will panic. f64_unsuffixed(f: f64) -> Literal1045 pub fn f64_unsuffixed(f: f64) -> Literal { 1046 assert!(f.is_finite()); 1047 Literal::_new(imp::Literal::f64_unsuffixed(f)) 1048 } 1049 1050 /// Creates a new suffixed floating-point literal. 1051 /// 1052 /// This constructor will create a literal like `1.0f64` where the value 1053 /// specified is the preceding part of the token and `f64` is the suffix of 1054 /// the token. This token will always be inferred to be an `f64` in the 1055 /// compiler. Literals created from negative numbers may not survive 1056 /// rountrips through `TokenStream` or strings and may be broken into two 1057 /// tokens (`-` and positive literal). 1058 /// 1059 /// # Panics 1060 /// 1061 /// This function requires that the specified float is finite, for example 1062 /// if it is infinity or NaN this function will panic. f64_suffixed(f: f64) -> Literal1063 pub fn f64_suffixed(f: f64) -> Literal { 1064 assert!(f.is_finite()); 1065 Literal::_new(imp::Literal::f64_suffixed(f)) 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. f32_unsuffixed(f: f32) -> Literal1081 pub fn f32_unsuffixed(f: f32) -> Literal { 1082 assert!(f.is_finite()); 1083 Literal::_new(imp::Literal::f32_unsuffixed(f)) 1084 } 1085 1086 /// Creates a new suffixed floating-point literal. 1087 /// 1088 /// This constructor will create a literal like `1.0f32` where the value 1089 /// specified is the preceding part of the token and `f32` is the suffix of 1090 /// the token. This token will always be inferred to be an `f32` 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. f32_suffixed(f: f32) -> Literal1099 pub fn f32_suffixed(f: f32) -> Literal { 1100 assert!(f.is_finite()); 1101 Literal::_new(imp::Literal::f32_suffixed(f)) 1102 } 1103 1104 /// String literal. string(string: &str) -> Literal1105 pub fn string(string: &str) -> Literal { 1106 Literal::_new(imp::Literal::string(string)) 1107 } 1108 1109 /// Character literal. character(ch: char) -> Literal1110 pub fn character(ch: char) -> Literal { 1111 Literal::_new(imp::Literal::character(ch)) 1112 } 1113 1114 /// Byte string literal. byte_string(s: &[u8]) -> Literal1115 pub fn byte_string(s: &[u8]) -> Literal { 1116 Literal::_new(imp::Literal::byte_string(s)) 1117 } 1118 1119 /// Returns the span encompassing this literal. span(&self) -> Span1120 pub fn span(&self) -> Span { 1121 Span::_new(self.inner.span()) 1122 } 1123 1124 /// Configures the span associated for this literal. set_span(&mut self, span: Span)1125 pub fn set_span(&mut self, span: Span) { 1126 self.inner.set_span(span.inner); 1127 } 1128 1129 /// Returns a `Span` that is a subset of `self.span()` containing only 1130 /// the source bytes in range `range`. Returns `None` if the would-be 1131 /// trimmed span is outside the bounds of `self`. 1132 /// 1133 /// Warning: the underlying [`proc_macro::Literal::subspan`] method is 1134 /// nightly-only. When called from within a procedural macro not using a 1135 /// nightly compiler, this method will always return `None`. 1136 /// 1137 /// [`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>1138 pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> { 1139 self.inner.subspan(range).map(Span::_new) 1140 } 1141 } 1142 1143 impl fmt::Debug for Literal { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1144 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1145 self.inner.fmt(f) 1146 } 1147 } 1148 1149 impl fmt::Display for Literal { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1150 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1151 self.inner.fmt(f) 1152 } 1153 } 1154 1155 /// Public implementation details for the `TokenStream` type, such as iterators. 1156 pub mod token_stream { 1157 use std::fmt; 1158 use std::marker; 1159 use std::rc::Rc; 1160 1161 pub use crate::TokenStream; 1162 use crate::{imp, TokenTree}; 1163 1164 /// An iterator over `TokenStream`'s `TokenTree`s. 1165 /// 1166 /// The iteration is "shallow", e.g. the iterator doesn't recurse into 1167 /// delimited groups, and returns whole groups as token trees. 1168 #[derive(Clone)] 1169 pub struct IntoIter { 1170 inner: imp::TokenTreeIter, 1171 _marker: marker::PhantomData<Rc<()>>, 1172 } 1173 1174 impl Iterator for IntoIter { 1175 type Item = TokenTree; 1176 next(&mut self) -> Option<TokenTree>1177 fn next(&mut self) -> Option<TokenTree> { 1178 self.inner.next() 1179 } 1180 } 1181 1182 impl fmt::Debug for IntoIter { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1183 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1184 self.inner.fmt(f) 1185 } 1186 } 1187 1188 impl IntoIterator for TokenStream { 1189 type Item = TokenTree; 1190 type IntoIter = IntoIter; 1191 into_iter(self) -> IntoIter1192 fn into_iter(self) -> IntoIter { 1193 IntoIter { 1194 inner: self.inner.into_iter(), 1195 _marker: marker::PhantomData, 1196 } 1197 } 1198 } 1199 } 1200