1 //! A wrapper around the procedural macro API of the compiler's [`proc_macro`] 2 //! crate. This library serves three 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 //! - **Provide the latest and greatest APIs across all compiler versions.** 22 //! Procedural macros were first introduced to Rust in 1.15.0 with an 23 //! extremely minimal interface. Since then, many improvements have landed to 24 //! make macros more flexible and easier to write. This library tracks the 25 //! procedural macro API of the most recent stable compiler but employs a 26 //! polyfill to provide that API consistently across any compiler since 27 //! 1.15.0. 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 //! ```edition2018 37 //! extern crate proc_macro; 38 //! 39 //! # const IGNORE: &str = stringify! { 40 //! #[proc_macro_derive(MyDerive)] 41 //! # }; 42 //! pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream { 43 //! let input = proc_macro2::TokenStream::from(input); 44 //! 45 //! let output: proc_macro2::TokenStream = { 46 //! /* transform input */ 47 //! # input 48 //! }; 49 //! 50 //! proc_macro::TokenStream::from(output) 51 //! } 52 //! ``` 53 //! 54 //! If parsing with [Syn], you'll use [`parse_macro_input!`] instead to 55 //! propagate parse errors correctly back to the compiler when parsing fails. 56 //! 57 //! [`parse_macro_input!`]: https://docs.rs/syn/0.15/syn/macro.parse_macro_input.html 58 //! 59 //! # Unstable features 60 //! 61 //! The default feature set of proc-macro2 tracks the most recent stable 62 //! compiler API. Functionality in `proc_macro` that is not yet stable is not 63 //! exposed by proc-macro2 by default. 64 //! 65 //! To opt into the additional APIs available in the most recent nightly 66 //! compiler, the `procmacro2_semver_exempt` config flag must be passed to 67 //! rustc. As usual, we will polyfill those nightly-only APIs all the way back 68 //! to Rust 1.15.0. As these are unstable APIs that track the nightly compiler, 69 //! minor versions of proc-macro2 may make breaking changes to them at any time. 70 //! 71 //! ```sh 72 //! RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build 73 //! ``` 74 //! 75 //! Note that this must not only be done for your crate, but for any crate that 76 //! depends on your crate. This infectious nature is intentional, as it serves 77 //! as a reminder that you are outside of the normal semver guarantees. 78 //! 79 //! Semver exempt methods are marked as such in the proc-macro2 documentation. 80 81 // Proc-macro2 types in rustdoc of other crates get linked to here. 82 #![doc(html_root_url = "https://docs.rs/proc-macro2/0.4.30")] 83 #![cfg_attr(any(proc_macro_span, super_unstable), feature(proc_macro_span))] 84 #![cfg_attr(super_unstable, feature(proc_macro_raw_ident, proc_macro_def_site))] 85 86 #[cfg(use_proc_macro)] 87 extern crate proc_macro; 88 extern crate unicode_xid; 89 90 use std::cmp::Ordering; 91 use std::fmt; 92 use std::hash::{Hash, Hasher}; 93 use std::iter::FromIterator; 94 use std::marker; 95 #[cfg(procmacro2_semver_exempt)] 96 use std::path::PathBuf; 97 use std::rc::Rc; 98 use std::str::FromStr; 99 100 #[macro_use] 101 mod strnom; 102 mod fallback; 103 104 #[cfg(not(wrap_proc_macro))] 105 use fallback as imp; 106 #[path = "wrapper.rs"] 107 #[cfg(wrap_proc_macro)] 108 mod imp; 109 110 /// An abstract stream of tokens, or more concretely a sequence of token trees. 111 /// 112 /// This type provides interfaces for iterating over token trees and for 113 /// collecting token trees into one stream. 114 /// 115 /// Token stream is both the input and output of `#[proc_macro]`, 116 /// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions. 117 #[derive(Clone)] 118 pub struct TokenStream { 119 inner: imp::TokenStream, 120 _marker: marker::PhantomData<Rc<()>>, 121 } 122 123 /// Error returned from `TokenStream::from_str`. 124 pub struct LexError { 125 inner: imp::LexError, 126 _marker: marker::PhantomData<Rc<()>>, 127 } 128 129 impl TokenStream { _new(inner: imp::TokenStream) -> TokenStream130 fn _new(inner: imp::TokenStream) -> TokenStream { 131 TokenStream { 132 inner: inner, 133 _marker: marker::PhantomData, 134 } 135 } 136 _new_stable(inner: fallback::TokenStream) -> TokenStream137 fn _new_stable(inner: fallback::TokenStream) -> TokenStream { 138 TokenStream { 139 inner: inner.into(), 140 _marker: marker::PhantomData, 141 } 142 } 143 144 /// Returns an empty `TokenStream` containing no token trees. new() -> TokenStream145 pub fn new() -> TokenStream { 146 TokenStream::_new(imp::TokenStream::new()) 147 } 148 149 #[deprecated(since = "0.4.4", note = "please use TokenStream::new")] empty() -> TokenStream150 pub fn empty() -> TokenStream { 151 TokenStream::new() 152 } 153 154 /// Checks if this `TokenStream` is empty. is_empty(&self) -> bool155 pub fn is_empty(&self) -> bool { 156 self.inner.is_empty() 157 } 158 } 159 160 /// `TokenStream::default()` returns an empty stream, 161 /// i.e. this is equivalent with `TokenStream::new()`. 162 impl Default for TokenStream { default() -> Self163 fn default() -> Self { 164 TokenStream::new() 165 } 166 } 167 168 /// Attempts to break the string into tokens and parse those tokens into a token 169 /// stream. 170 /// 171 /// May fail for a number of reasons, for example, if the string contains 172 /// unbalanced delimiters or characters not existing in the language. 173 /// 174 /// NOTE: Some errors may cause panics instead of returning `LexError`. We 175 /// reserve the right to change these errors into `LexError`s later. 176 impl FromStr for TokenStream { 177 type Err = LexError; 178 from_str(src: &str) -> Result<TokenStream, LexError>179 fn from_str(src: &str) -> Result<TokenStream, LexError> { 180 let e = src.parse().map_err(|e| LexError { 181 inner: e, 182 _marker: marker::PhantomData, 183 })?; 184 Ok(TokenStream::_new(e)) 185 } 186 } 187 188 #[cfg(use_proc_macro)] 189 impl From<proc_macro::TokenStream> for TokenStream { from(inner: proc_macro::TokenStream) -> TokenStream190 fn from(inner: proc_macro::TokenStream) -> TokenStream { 191 TokenStream::_new(inner.into()) 192 } 193 } 194 195 #[cfg(use_proc_macro)] 196 impl From<TokenStream> for proc_macro::TokenStream { from(inner: TokenStream) -> proc_macro::TokenStream197 fn from(inner: TokenStream) -> proc_macro::TokenStream { 198 inner.inner.into() 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: 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: 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 { 408 line: line, 409 column: column, 410 } 411 } 412 413 /// Get the ending line/column in the source file for this span. 414 /// 415 /// This method requires the `"span-locations"` feature to be enabled. 416 #[cfg(span_locations)] end(&self) -> LineColumn417 pub fn end(&self) -> LineColumn { 418 let imp::LineColumn { line, column } = self.inner.end(); 419 LineColumn { 420 line: line, 421 column: column, 422 } 423 } 424 425 /// Create a new span encompassing `self` and `other`. 426 /// 427 /// Returns `None` if `self` and `other` are from different files. 428 /// 429 /// This method is semver exempt and not exposed by default. 430 #[cfg(procmacro2_semver_exempt)] join(&self, other: Span) -> Option<Span>431 pub fn join(&self, other: Span) -> Option<Span> { 432 self.inner.join(other.inner).map(Span::_new) 433 } 434 435 /// Compares to spans to see if they're equal. 436 /// 437 /// This method is semver exempt and not exposed by default. 438 #[cfg(procmacro2_semver_exempt)] eq(&self, other: &Span) -> bool439 pub fn eq(&self, other: &Span) -> bool { 440 self.inner.eq(&other.inner) 441 } 442 } 443 444 /// Prints a span in a form convenient for debugging. 445 impl fmt::Debug for Span { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result446 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 447 self.inner.fmt(f) 448 } 449 } 450 451 /// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`). 452 #[derive(Clone)] 453 pub enum TokenTree { 454 /// A token stream surrounded by bracket delimiters. 455 Group(Group), 456 /// An identifier. 457 Ident(Ident), 458 /// A single punctuation character (`+`, `,`, `$`, etc.). 459 Punct(Punct), 460 /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc. 461 Literal(Literal), 462 } 463 464 impl TokenTree { 465 /// Returns the span of this tree, delegating to the `span` method of 466 /// the contained token or a delimited stream. span(&self) -> Span467 pub fn span(&self) -> Span { 468 match *self { 469 TokenTree::Group(ref t) => t.span(), 470 TokenTree::Ident(ref t) => t.span(), 471 TokenTree::Punct(ref t) => t.span(), 472 TokenTree::Literal(ref t) => t.span(), 473 } 474 } 475 476 /// Configures the span for *only this token*. 477 /// 478 /// Note that if this token is a `Group` then this method will not configure 479 /// the span of each of the internal tokens, this will simply delegate to 480 /// the `set_span` method of each variant. set_span(&mut self, span: Span)481 pub fn set_span(&mut self, span: Span) { 482 match *self { 483 TokenTree::Group(ref mut t) => t.set_span(span), 484 TokenTree::Ident(ref mut t) => t.set_span(span), 485 TokenTree::Punct(ref mut t) => t.set_span(span), 486 TokenTree::Literal(ref mut t) => t.set_span(span), 487 } 488 } 489 } 490 491 impl From<Group> for TokenTree { from(g: Group) -> TokenTree492 fn from(g: Group) -> TokenTree { 493 TokenTree::Group(g) 494 } 495 } 496 497 impl From<Ident> for TokenTree { from(g: Ident) -> TokenTree498 fn from(g: Ident) -> TokenTree { 499 TokenTree::Ident(g) 500 } 501 } 502 503 impl From<Punct> for TokenTree { from(g: Punct) -> TokenTree504 fn from(g: Punct) -> TokenTree { 505 TokenTree::Punct(g) 506 } 507 } 508 509 impl From<Literal> for TokenTree { from(g: Literal) -> TokenTree510 fn from(g: Literal) -> TokenTree { 511 TokenTree::Literal(g) 512 } 513 } 514 515 /// Prints the token tree as a string that is supposed to be losslessly 516 /// convertible back into the same token tree (modulo spans), except for 517 /// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative 518 /// numeric literals. 519 impl fmt::Display for TokenTree { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result520 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 521 match *self { 522 TokenTree::Group(ref t) => t.fmt(f), 523 TokenTree::Ident(ref t) => t.fmt(f), 524 TokenTree::Punct(ref t) => t.fmt(f), 525 TokenTree::Literal(ref t) => t.fmt(f), 526 } 527 } 528 } 529 530 /// Prints token tree in a form convenient for debugging. 531 impl fmt::Debug for TokenTree { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result532 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 533 // Each of these has the name in the struct type in the derived debug, 534 // so don't bother with an extra layer of indirection 535 match *self { 536 TokenTree::Group(ref t) => t.fmt(f), 537 TokenTree::Ident(ref t) => { 538 let mut debug = f.debug_struct("Ident"); 539 debug.field("sym", &format_args!("{}", t)); 540 imp::debug_span_field_if_nontrivial(&mut debug, t.span().inner); 541 debug.finish() 542 } 543 TokenTree::Punct(ref t) => t.fmt(f), 544 TokenTree::Literal(ref t) => t.fmt(f), 545 } 546 } 547 } 548 549 /// A delimited token stream. 550 /// 551 /// A `Group` internally contains a `TokenStream` which is surrounded by 552 /// `Delimiter`s. 553 #[derive(Clone)] 554 pub struct Group { 555 inner: imp::Group, 556 } 557 558 /// Describes how a sequence of token trees is delimited. 559 #[derive(Copy, Clone, Debug, Eq, PartialEq)] 560 pub enum Delimiter { 561 /// `( ... )` 562 Parenthesis, 563 /// `{ ... }` 564 Brace, 565 /// `[ ... ]` 566 Bracket, 567 /// `Ø ... Ø` 568 /// 569 /// An implicit delimiter, that may, for example, appear around tokens 570 /// coming from a "macro variable" `$var`. It is important to preserve 571 /// operator priorities in cases like `$var * 3` where `$var` is `1 + 2`. 572 /// Implicit delimiters may not survive roundtrip of a token stream through 573 /// a string. 574 None, 575 } 576 577 impl Group { _new(inner: imp::Group) -> Self578 fn _new(inner: imp::Group) -> Self { 579 Group { inner: inner } 580 } 581 _new_stable(inner: fallback::Group) -> Self582 fn _new_stable(inner: fallback::Group) -> Self { 583 Group { 584 inner: inner.into(), 585 } 586 } 587 588 /// Creates a new `Group` with the given delimiter and token stream. 589 /// 590 /// This constructor will set the span for this group to 591 /// `Span::call_site()`. To change the span you can use the `set_span` 592 /// method below. new(delimiter: Delimiter, stream: TokenStream) -> Group593 pub fn new(delimiter: Delimiter, stream: TokenStream) -> Group { 594 Group { 595 inner: imp::Group::new(delimiter, stream.inner), 596 } 597 } 598 599 /// Returns the delimiter of this `Group` delimiter(&self) -> Delimiter600 pub fn delimiter(&self) -> Delimiter { 601 self.inner.delimiter() 602 } 603 604 /// Returns the `TokenStream` of tokens that are delimited in this `Group`. 605 /// 606 /// Note that the returned token stream does not include the delimiter 607 /// returned above. stream(&self) -> TokenStream608 pub fn stream(&self) -> TokenStream { 609 TokenStream::_new(self.inner.stream()) 610 } 611 612 /// Returns the span for the delimiters of this token stream, spanning the 613 /// entire `Group`. 614 /// 615 /// ```text 616 /// pub fn span(&self) -> Span { 617 /// ^^^^^^^ 618 /// ``` span(&self) -> Span619 pub fn span(&self) -> Span { 620 Span::_new(self.inner.span()) 621 } 622 623 /// Returns the span pointing to the opening delimiter of this group. 624 /// 625 /// ```text 626 /// pub fn span_open(&self) -> Span { 627 /// ^ 628 /// ``` 629 #[cfg(procmacro2_semver_exempt)] span_open(&self) -> Span630 pub fn span_open(&self) -> Span { 631 Span::_new(self.inner.span_open()) 632 } 633 634 /// Returns the span pointing to the closing delimiter of this group. 635 /// 636 /// ```text 637 /// pub fn span_close(&self) -> Span { 638 /// ^ 639 /// ``` 640 #[cfg(procmacro2_semver_exempt)] span_close(&self) -> Span641 pub fn span_close(&self) -> Span { 642 Span::_new(self.inner.span_close()) 643 } 644 645 /// Configures the span for this `Group`'s delimiters, but not its internal 646 /// tokens. 647 /// 648 /// This method will **not** set the span of all the internal tokens spanned 649 /// by this group, but rather it will only set the span of the delimiter 650 /// tokens at the level of the `Group`. set_span(&mut self, span: Span)651 pub fn set_span(&mut self, span: Span) { 652 self.inner.set_span(span.inner) 653 } 654 } 655 656 /// Prints the group as a string that should be losslessly convertible back 657 /// into the same group (modulo spans), except for possibly `TokenTree::Group`s 658 /// with `Delimiter::None` delimiters. 659 impl fmt::Display for Group { fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result660 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { 661 fmt::Display::fmt(&self.inner, formatter) 662 } 663 } 664 665 impl fmt::Debug for Group { fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result666 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { 667 fmt::Debug::fmt(&self.inner, formatter) 668 } 669 } 670 671 /// An `Punct` is an single punctuation character like `+`, `-` or `#`. 672 /// 673 /// Multicharacter operators like `+=` are represented as two instances of 674 /// `Punct` with different forms of `Spacing` returned. 675 #[derive(Clone)] 676 pub struct Punct { 677 op: char, 678 spacing: Spacing, 679 span: Span, 680 } 681 682 /// Whether an `Punct` is followed immediately by another `Punct` or followed by 683 /// another token or whitespace. 684 #[derive(Copy, Clone, Debug, Eq, PartialEq)] 685 pub enum Spacing { 686 /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`. 687 Alone, 688 /// E.g. `+` is `Joint` in `+=` or `'#`. 689 /// 690 /// Additionally, single quote `'` can join with identifiers to form 691 /// lifetimes `'ident`. 692 Joint, 693 } 694 695 impl Punct { 696 /// Creates a new `Punct` from the given character and spacing. 697 /// 698 /// The `ch` argument must be a valid punctuation character permitted by the 699 /// language, otherwise the function will panic. 700 /// 701 /// The returned `Punct` will have the default span of `Span::call_site()` 702 /// which can be further configured with the `set_span` method below. new(op: char, spacing: Spacing) -> Punct703 pub fn new(op: char, spacing: Spacing) -> Punct { 704 Punct { 705 op: op, 706 spacing: spacing, 707 span: Span::call_site(), 708 } 709 } 710 711 /// Returns the value of this punctuation character as `char`. as_char(&self) -> char712 pub fn as_char(&self) -> char { 713 self.op 714 } 715 716 /// Returns the spacing of this punctuation character, indicating whether 717 /// it's immediately followed by another `Punct` in the token stream, so 718 /// they can potentially be combined into a multicharacter operator 719 /// (`Joint`), or it's followed by some other token or whitespace (`Alone`) 720 /// so the operator has certainly ended. spacing(&self) -> Spacing721 pub fn spacing(&self) -> Spacing { 722 self.spacing 723 } 724 725 /// Returns the span for this punctuation character. span(&self) -> Span726 pub fn span(&self) -> Span { 727 self.span 728 } 729 730 /// Configure the span for this punctuation character. set_span(&mut self, span: Span)731 pub fn set_span(&mut self, span: Span) { 732 self.span = span; 733 } 734 } 735 736 /// Prints the punctuation character as a string that should be losslessly 737 /// convertible back into the same character. 738 impl fmt::Display for Punct { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result739 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 740 self.op.fmt(f) 741 } 742 } 743 744 impl fmt::Debug for Punct { fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result745 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { 746 let mut debug = fmt.debug_struct("Punct"); 747 debug.field("op", &self.op); 748 debug.field("spacing", &self.spacing); 749 imp::debug_span_field_if_nontrivial(&mut debug, self.span.inner); 750 debug.finish() 751 } 752 } 753 754 /// A word of Rust code, which may be a keyword or legal variable name. 755 /// 756 /// An identifier consists of at least one Unicode code point, the first of 757 /// which has the XID_Start property and the rest of which have the XID_Continue 758 /// property. 759 /// 760 /// - The empty string is not an identifier. Use `Option<Ident>`. 761 /// - A lifetime is not an identifier. Use `syn::Lifetime` instead. 762 /// 763 /// An identifier constructed with `Ident::new` is permitted to be a Rust 764 /// keyword, though parsing one through its [`Parse`] implementation rejects 765 /// Rust keywords. Use `input.call(Ident::parse_any)` when parsing to match the 766 /// behaviour of `Ident::new`. 767 /// 768 /// [`Parse`]: https://docs.rs/syn/0.15/syn/parse/trait.Parse.html 769 /// 770 /// # Examples 771 /// 772 /// A new ident can be created from a string using the `Ident::new` function. 773 /// A span must be provided explicitly which governs the name resolution 774 /// behavior of the resulting identifier. 775 /// 776 /// ```edition2018 777 /// use proc_macro2::{Ident, Span}; 778 /// 779 /// fn main() { 780 /// let call_ident = Ident::new("calligraphy", Span::call_site()); 781 /// 782 /// println!("{}", call_ident); 783 /// } 784 /// ``` 785 /// 786 /// An ident can be interpolated into a token stream using the `quote!` macro. 787 /// 788 /// ```edition2018 789 /// use proc_macro2::{Ident, Span}; 790 /// use quote::quote; 791 /// 792 /// fn main() { 793 /// let ident = Ident::new("demo", Span::call_site()); 794 /// 795 /// // Create a variable binding whose name is this ident. 796 /// let expanded = quote! { let #ident = 10; }; 797 /// 798 /// // Create a variable binding with a slightly different name. 799 /// let temp_ident = Ident::new(&format!("new_{}", ident), Span::call_site()); 800 /// let expanded = quote! { let #temp_ident = 10; }; 801 /// } 802 /// ``` 803 /// 804 /// A string representation of the ident is available through the `to_string()` 805 /// method. 806 /// 807 /// ```edition2018 808 /// # use proc_macro2::{Ident, Span}; 809 /// # 810 /// # let ident = Ident::new("another_identifier", Span::call_site()); 811 /// # 812 /// // Examine the ident as a string. 813 /// let ident_string = ident.to_string(); 814 /// if ident_string.len() > 60 { 815 /// println!("Very long identifier: {}", ident_string) 816 /// } 817 /// ``` 818 #[derive(Clone)] 819 pub struct Ident { 820 inner: imp::Ident, 821 _marker: marker::PhantomData<Rc<()>>, 822 } 823 824 impl Ident { _new(inner: imp::Ident) -> Ident825 fn _new(inner: imp::Ident) -> Ident { 826 Ident { 827 inner: inner, 828 _marker: marker::PhantomData, 829 } 830 } 831 832 /// Creates a new `Ident` with the given `string` as well as the specified 833 /// `span`. 834 /// 835 /// The `string` argument must be a valid identifier permitted by the 836 /// language, otherwise the function will panic. 837 /// 838 /// Note that `span`, currently in rustc, configures the hygiene information 839 /// for this identifier. 840 /// 841 /// As of this time `Span::call_site()` explicitly opts-in to "call-site" 842 /// hygiene meaning that identifiers created with this span will be resolved 843 /// as if they were written directly at the location of the macro call, and 844 /// other code at the macro call site will be able to refer to them as well. 845 /// 846 /// Later spans like `Span::def_site()` will allow to opt-in to 847 /// "definition-site" hygiene meaning that identifiers created with this 848 /// span will be resolved at the location of the macro definition and other 849 /// code at the macro call site will not be able to refer to them. 850 /// 851 /// Due to the current importance of hygiene this constructor, unlike other 852 /// tokens, requires a `Span` to be specified at construction. 853 /// 854 /// # Panics 855 /// 856 /// Panics if the input string is neither a keyword nor a legal variable 857 /// name. If you are not sure whether the string contains an identifier and 858 /// need to handle an error case, use 859 /// <a href="https://docs.rs/syn/0.15/syn/fn.parse_str.html"><code 860 /// style="padding-right:0;">syn::parse_str</code></a><code 861 /// style="padding-left:0;">::<Ident></code> 862 /// rather than `Ident::new`. new(string: &str, span: Span) -> Ident863 pub fn new(string: &str, span: Span) -> Ident { 864 Ident::_new(imp::Ident::new(string, span.inner)) 865 } 866 867 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). 868 /// 869 /// This method is semver exempt and not exposed by default. 870 #[cfg(procmacro2_semver_exempt)] new_raw(string: &str, span: Span) -> Ident871 pub fn new_raw(string: &str, span: Span) -> Ident { 872 Ident::_new_raw(string, span) 873 } 874 _new_raw(string: &str, span: Span) -> Ident875 fn _new_raw(string: &str, span: Span) -> Ident { 876 Ident::_new(imp::Ident::new_raw(string, span.inner)) 877 } 878 879 /// Returns the span of this `Ident`. span(&self) -> Span880 pub fn span(&self) -> Span { 881 Span::_new(self.inner.span()) 882 } 883 884 /// Configures the span of this `Ident`, possibly changing its hygiene 885 /// context. set_span(&mut self, span: Span)886 pub fn set_span(&mut self, span: Span) { 887 self.inner.set_span(span.inner); 888 } 889 } 890 891 impl PartialEq for Ident { eq(&self, other: &Ident) -> bool892 fn eq(&self, other: &Ident) -> bool { 893 self.inner == other.inner 894 } 895 } 896 897 impl<T> PartialEq<T> for Ident 898 where 899 T: ?Sized + AsRef<str>, 900 { eq(&self, other: &T) -> bool901 fn eq(&self, other: &T) -> bool { 902 self.inner == other 903 } 904 } 905 906 impl Eq for Ident {} 907 908 impl PartialOrd for Ident { partial_cmp(&self, other: &Ident) -> Option<Ordering>909 fn partial_cmp(&self, other: &Ident) -> Option<Ordering> { 910 Some(self.cmp(other)) 911 } 912 } 913 914 impl Ord for Ident { cmp(&self, other: &Ident) -> Ordering915 fn cmp(&self, other: &Ident) -> Ordering { 916 self.to_string().cmp(&other.to_string()) 917 } 918 } 919 920 impl Hash for Ident { hash<H: Hasher>(&self, hasher: &mut H)921 fn hash<H: Hasher>(&self, hasher: &mut H) { 922 self.to_string().hash(hasher) 923 } 924 } 925 926 /// Prints the identifier as a string that should be losslessly convertible back 927 /// into the same identifier. 928 impl fmt::Display for Ident { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result929 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 930 self.inner.fmt(f) 931 } 932 } 933 934 impl fmt::Debug for Ident { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result935 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 936 self.inner.fmt(f) 937 } 938 } 939 940 /// A literal string (`"hello"`), byte string (`b"hello"`), character (`'a'`), 941 /// byte character (`b'a'`), an integer or floating point number with or without 942 /// a suffix (`1`, `1u8`, `2.3`, `2.3f32`). 943 /// 944 /// Boolean literals like `true` and `false` do not belong here, they are 945 /// `Ident`s. 946 #[derive(Clone)] 947 pub struct Literal { 948 inner: imp::Literal, 949 _marker: marker::PhantomData<Rc<()>>, 950 } 951 952 macro_rules! suffixed_int_literals { 953 ($($name:ident => $kind:ident,)*) => ($( 954 /// Creates a new suffixed integer literal with the specified value. 955 /// 956 /// This function will create an integer like `1u32` where the integer 957 /// value specified is the first part of the token and the integral is 958 /// also suffixed at the end. Literals created from negative numbers may 959 /// not survive rountrips through `TokenStream` or strings and may be 960 /// broken into two tokens (`-` and positive literal). 961 /// 962 /// Literals created through this method have the `Span::call_site()` 963 /// span by default, which can be configured with the `set_span` method 964 /// below. 965 pub fn $name(n: $kind) -> Literal { 966 Literal::_new(imp::Literal::$name(n)) 967 } 968 )*) 969 } 970 971 macro_rules! unsuffixed_int_literals { 972 ($($name:ident => $kind:ident,)*) => ($( 973 /// Creates a new unsuffixed integer literal with the specified value. 974 /// 975 /// This function will create an integer like `1` where the integer 976 /// value specified is the first part of the token. No suffix is 977 /// specified on this token, meaning that invocations like 978 /// `Literal::i8_unsuffixed(1)` are equivalent to 979 /// `Literal::u32_unsuffixed(1)`. Literals created from negative numbers 980 /// may not survive rountrips through `TokenStream` or strings and may 981 /// be broken into two tokens (`-` and positive literal). 982 /// 983 /// Literals created through this method have the `Span::call_site()` 984 /// span by default, which can be configured with the `set_span` method 985 /// below. 986 pub fn $name(n: $kind) -> Literal { 987 Literal::_new(imp::Literal::$name(n)) 988 } 989 )*) 990 } 991 992 impl Literal { _new(inner: imp::Literal) -> Literal993 fn _new(inner: imp::Literal) -> Literal { 994 Literal { 995 inner: inner, 996 _marker: marker::PhantomData, 997 } 998 } 999 _new_stable(inner: fallback::Literal) -> Literal1000 fn _new_stable(inner: fallback::Literal) -> Literal { 1001 Literal { 1002 inner: inner.into(), 1003 _marker: marker::PhantomData, 1004 } 1005 } 1006 1007 suffixed_int_literals! { 1008 u8_suffixed => u8, 1009 u16_suffixed => u16, 1010 u32_suffixed => u32, 1011 u64_suffixed => u64, 1012 usize_suffixed => usize, 1013 i8_suffixed => i8, 1014 i16_suffixed => i16, 1015 i32_suffixed => i32, 1016 i64_suffixed => i64, 1017 isize_suffixed => isize, 1018 } 1019 1020 #[cfg(u128)] 1021 suffixed_int_literals! { 1022 u128_suffixed => u128, 1023 i128_suffixed => i128, 1024 } 1025 1026 unsuffixed_int_literals! { 1027 u8_unsuffixed => u8, 1028 u16_unsuffixed => u16, 1029 u32_unsuffixed => u32, 1030 u64_unsuffixed => u64, 1031 usize_unsuffixed => usize, 1032 i8_unsuffixed => i8, 1033 i16_unsuffixed => i16, 1034 i32_unsuffixed => i32, 1035 i64_unsuffixed => i64, 1036 isize_unsuffixed => isize, 1037 } 1038 1039 #[cfg(u128)] 1040 unsuffixed_int_literals! { 1041 u128_unsuffixed => u128, 1042 i128_unsuffixed => i128, 1043 } 1044 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 f64_suffixed(f: f64) -> Literal1050 pub fn f64_suffixed(f: f64) -> Literal { 1051 assert!(f.is_finite()); 1052 Literal::_new(imp::Literal::f64_suffixed(f)) 1053 } 1054 1055 /// Creates a new unsuffixed floating-point literal. 1056 /// 1057 /// This constructor is similar to those like `Literal::i8_unsuffixed` where 1058 /// the float's value is emitted directly into the token but no suffix is 1059 /// used, so it may be inferred to be a `f64` later in the compiler. 1060 /// Literals created from negative numbers may not survive rountrips through 1061 /// `TokenStream` or strings and may be broken into two tokens (`-` and 1062 /// positive literal). 1063 /// 1064 /// # Panics 1065 /// 1066 /// This function requires that the specified float is finite, for example 1067 /// if it is infinity or NaN this function will panic. f32_unsuffixed(f: f32) -> Literal1068 pub fn f32_unsuffixed(f: f32) -> Literal { 1069 assert!(f.is_finite()); 1070 Literal::_new(imp::Literal::f32_unsuffixed(f)) 1071 } 1072 f32_suffixed(f: f32) -> Literal1073 pub fn f32_suffixed(f: f32) -> Literal { 1074 assert!(f.is_finite()); 1075 Literal::_new(imp::Literal::f32_suffixed(f)) 1076 } 1077 string(string: &str) -> Literal1078 pub fn string(string: &str) -> Literal { 1079 Literal::_new(imp::Literal::string(string)) 1080 } 1081 character(ch: char) -> Literal1082 pub fn character(ch: char) -> Literal { 1083 Literal::_new(imp::Literal::character(ch)) 1084 } 1085 byte_string(s: &[u8]) -> Literal1086 pub fn byte_string(s: &[u8]) -> Literal { 1087 Literal::_new(imp::Literal::byte_string(s)) 1088 } 1089 span(&self) -> Span1090 pub fn span(&self) -> Span { 1091 Span::_new(self.inner.span()) 1092 } 1093 set_span(&mut self, span: Span)1094 pub fn set_span(&mut self, span: Span) { 1095 self.inner.set_span(span.inner); 1096 } 1097 } 1098 1099 impl fmt::Debug for Literal { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1100 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1101 self.inner.fmt(f) 1102 } 1103 } 1104 1105 impl fmt::Display for Literal { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1106 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1107 self.inner.fmt(f) 1108 } 1109 } 1110 1111 /// Public implementation details for the `TokenStream` type, such as iterators. 1112 pub mod token_stream { 1113 use std::fmt; 1114 use std::marker; 1115 use std::rc::Rc; 1116 1117 use imp; 1118 pub use TokenStream; 1119 use TokenTree; 1120 1121 /// An iterator over `TokenStream`'s `TokenTree`s. 1122 /// 1123 /// The iteration is "shallow", e.g. the iterator doesn't recurse into 1124 /// delimited groups, and returns whole groups as token trees. 1125 #[derive(Clone)] 1126 pub struct IntoIter { 1127 inner: imp::TokenTreeIter, 1128 _marker: marker::PhantomData<Rc<()>>, 1129 } 1130 1131 impl Iterator for IntoIter { 1132 type Item = TokenTree; 1133 next(&mut self) -> Option<TokenTree>1134 fn next(&mut self) -> Option<TokenTree> { 1135 self.inner.next() 1136 } 1137 } 1138 1139 impl fmt::Debug for IntoIter { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1140 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1141 self.inner.fmt(f) 1142 } 1143 } 1144 1145 impl IntoIterator for TokenStream { 1146 type Item = TokenTree; 1147 type IntoIter = IntoIter; 1148 into_iter(self) -> IntoIter1149 fn into_iter(self) -> IntoIter { 1150 IntoIter { 1151 inner: self.inner.into_iter(), 1152 _marker: marker::PhantomData, 1153 } 1154 } 1155 } 1156 } 1157