1 //! A wrapper around the procedural macro API of the compiler's [`proc_macro`]
2 //! crate. This library serves two purposes:
4 //! [`proc_macro`]: https://doc.rust-lang.org/proc_macro/
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.
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
21 //! [syn]: https://github.com/dtolnay/syn
22 //! [quote]: https://github.com/dtolnay/quote
26 //! The skeleton of a typical procedural macro typically looks like this:
29 //! extern crate proc_macro;
31 //! # const IGNORE: &str = stringify! {
32 //! #[proc_macro_derive(MyDerive)]
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);
38 //! let output: proc_macro2::TokenStream = {
39 //! /* transform input */
43 //! proc_macro::TokenStream::from(output)
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.
50 //! [`parse_macro_input!`]: https://docs.rs/syn/1.0/syn/macro.parse_macro_input.html
52 //! # Unstable features
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.
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.
65 //! RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
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.
72 //! Semver exempt methods are marked as such in the proc-macro2 documentation.
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.
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)]
86 #[cfg(use_proc_macro)]
87 extern crate proc_macro
;
92 #[cfg(wrap_proc_macro)]
95 // Public for proc_macro2::fallback::force() and unforce(), but those are quite
96 // a niche use case so we omit it from rustdoc.
100 #[cfg(not(wrap_proc_macro))]
101 use crate::fallback
as imp
;
102 #[path = "wrapper.rs"]
103 #[cfg(wrap_proc_macro)]
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
;
117 /// An abstract stream of tokens, or more concretely a sequence of token trees.
119 /// This type provides interfaces for iterating over token trees and for
120 /// collecting token trees into one stream.
122 /// Token stream is both the input and output of `#[proc_macro]`,
123 /// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions.
125 pub struct TokenStream
{
126 inner
: imp
::TokenStream
,
130 /// Error returned from `TokenStream::from_str`.
131 pub struct LexError
{
132 inner
: imp
::LexError
,
137 fn _new(inner
: imp
::TokenStream
) -> TokenStream
{
144 fn _new_stable(inner
: fallback
::TokenStream
) -> TokenStream
{
151 /// Returns an empty `TokenStream` containing no token trees.
152 pub fn new() -> TokenStream
{
153 TokenStream
::_new(imp
::TokenStream
::new())
156 /// Checks if this `TokenStream` is empty.
157 pub fn is_empty(&self) -> bool
{
158 self.inner
.is_empty()
162 /// `TokenStream::default()` returns an empty stream,
163 /// i.e. this is equivalent with `TokenStream::new()`.
164 impl Default
for TokenStream
{
165 fn default() -> Self {
170 /// Attempts to break the string into tokens and parse those tokens into a token
173 /// May fail for a number of reasons, for example, if the string contains
174 /// unbalanced delimiters or characters not existing in the language.
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
{
181 fn from_str(src
: &str) -> Result
<TokenStream
, LexError
> {
182 let e
= src
.parse().map_err(|e
| LexError
{
186 Ok(TokenStream
::_new(e
))
190 #[cfg(use_proc_macro)]
191 impl From
<proc_macro
::TokenStream
> for TokenStream
{
192 fn from(inner
: proc_macro
::TokenStream
) -> TokenStream
{
193 TokenStream
::_new(inner
.into())
197 #[cfg(use_proc_macro)]
198 impl From
<TokenStream
> for proc_macro
::TokenStream
{
199 fn from(inner
: TokenStream
) -> proc_macro
::TokenStream
{
204 impl From
<TokenTree
> for TokenStream
{
205 fn from(token
: TokenTree
) -> Self {
206 TokenStream
::_new(imp
::TokenStream
::from(token
))
210 impl Extend
<TokenTree
> for TokenStream
{
211 fn extend
<I
: IntoIterator
<Item
= TokenTree
>>(&mut self, streams
: I
) {
212 self.inner
.extend(streams
)
216 impl Extend
<TokenStream
> for TokenStream
{
217 fn extend
<I
: IntoIterator
<Item
= TokenStream
>>(&mut self, streams
: I
) {
219 .extend(streams
.into_iter().map(|stream
| stream
.inner
))
223 /// Collects a number of token trees into a single stream.
224 impl FromIterator
<TokenTree
> for TokenStream
{
225 fn from_iter
<I
: IntoIterator
<Item
= TokenTree
>>(streams
: I
) -> Self {
226 TokenStream
::_new(streams
.into_iter().collect())
229 impl FromIterator
<TokenStream
> for TokenStream
{
230 fn from_iter
<I
: IntoIterator
<Item
= TokenStream
>>(streams
: I
) -> Self {
231 TokenStream
::_new(streams
.into_iter().map(|i
| i
.inner
).collect())
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
{
240 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
241 Display
::fmt(&self.inner
, f
)
245 /// Prints token in a form convenient for debugging.
246 impl Debug
for TokenStream
{
247 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
248 Debug
::fmt(&self.inner
, f
)
252 impl Debug
for LexError
{
253 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
254 Debug
::fmt(&self.inner
, f
)
258 impl Display
for LexError
{
259 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
260 Display
::fmt(&self.inner
, f
)
264 impl Error
for LexError {}
266 /// The source file of a given `Span`.
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
,
276 #[cfg(procmacro2_semver_exempt)]
278 fn _new(inner
: imp
::SourceFile
) -> Self {
285 /// Get the path to this source file.
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.
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.
297 /// [`is_real`]: #method.is_real
298 pub fn path(&self) -> PathBuf
{
302 /// Returns `true` if this source file is a real source file, and not
303 /// generated by an external macro's expansion.
304 pub fn is_real(&self) -> bool
{
309 #[cfg(procmacro2_semver_exempt)]
310 impl Debug
for SourceFile
{
311 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
312 Debug
::fmt(&self.inner
, f
)
316 /// A line-column pair representing the start or end of a `Span`.
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
325 /// The 0-indexed column (in UTF-8 characters) in the source file on which
326 /// the span starts or ends (inclusive).
330 #[cfg(span_locations)]
331 impl Ord
for LineColumn
{
332 fn cmp(&self, other
: &Self) -> Ordering
{
335 .then(self.column
.cmp(&other
.column
))
339 #[cfg(span_locations)]
340 impl PartialOrd
for LineColumn
{
341 fn partial_cmp(&self, other
: &Self) -> Option
<Ordering
> {
342 Some(self.cmp(other
))
346 /// A region of source code, along with macro expansion information.
347 #[derive(Copy, Clone)]
354 fn _new(inner
: imp
::Span
) -> Span
{
361 fn _new_stable(inner
: fallback
::Span
) -> Span
{
368 /// The span of the invocation of the current procedural macro.
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.
373 pub fn call_site() -> Span
{
374 Span
::_new(imp
::Span
::call_site())
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`.
381 /// This function requires Rust 1.45 or later.
383 pub fn mixed_site() -> Span
{
384 Span
::_new(imp
::Span
::mixed_site())
387 /// A span that resolves at the macro definition site.
389 /// This method is semver exempt and not exposed by default.
390 #[cfg(procmacro2_semver_exempt)]
391 pub fn def_site() -> Span
{
392 Span
::_new(imp
::Span
::def_site())
395 /// Creates a new span with the same line/column information as `self` but
396 /// that resolves symbols as though it were at `other`.
397 pub fn resolved_at(&self, other
: Span
) -> Span
{
398 Span
::_new(self.inner
.resolved_at(other
.inner
))
401 /// Creates a new span with the same name resolution behavior as `self` but
402 /// with the line/column information of `other`.
403 pub fn located_at(&self, other
: Span
) -> Span
{
404 Span
::_new(self.inner
.located_at(other
.inner
))
407 /// Convert `proc_macro2::Span` to `proc_macro::Span`.
409 /// This method is available when building with a nightly compiler, or when
410 /// building with rustc 1.29+ *without* semver exempt features.
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)]
418 pub fn unwrap(self) -> proc_macro
::Span
{
422 // Soft deprecated. Please use Span::unwrap.
423 #[cfg(wrap_proc_macro)]
425 pub fn unstable(self) -> proc_macro
::Span
{
429 /// The original source file into which this span points.
431 /// This method is semver exempt and not exposed by default.
432 #[cfg(procmacro2_semver_exempt)]
433 pub fn source_file(&self) -> SourceFile
{
434 SourceFile
::_new(self.inner
.source_file())
437 /// Get the starting line/column in the source file for this span.
439 /// This method requires the `"span-locations"` feature to be enabled.
440 #[cfg(span_locations)]
441 pub fn start(&self) -> LineColumn
{
442 let imp
::LineColumn { line, column }
= self.inner
.start();
443 LineColumn { line, column }
446 /// Get the ending line/column in the source file for this span.
448 /// This method requires the `"span-locations"` feature to be enabled.
449 #[cfg(span_locations)]
450 pub fn end(&self) -> LineColumn
{
451 let imp
::LineColumn { line, column }
= self.inner
.end();
452 LineColumn { line, column }
455 /// Create a new span encompassing `self` and `other`.
457 /// Returns `None` if `self` and `other` are from different files.
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`.
463 /// [`proc_macro::Span::join`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.join
464 pub fn join(&self, other
: Span
) -> Option
<Span
> {
465 self.inner
.join(other
.inner
).map(Span
::_new
)
468 /// Compares two spans to see if they're equal.
470 /// This method is semver exempt and not exposed by default.
471 #[cfg(procmacro2_semver_exempt)]
472 pub fn eq(&self, other
: &Span
) -> bool
{
473 self.inner
.eq(&other
.inner
)
477 /// Prints a span in a form convenient for debugging.
478 impl Debug
for Span
{
479 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
480 Debug
::fmt(&self.inner
, f
)
484 /// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`).
487 /// A token stream surrounded by bracket delimiters.
491 /// A single punctuation character (`+`, `,`, `$`, etc.).
493 /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc.
498 /// Returns the span of this tree, delegating to the `span` method of
499 /// the contained token or a delimited stream.
500 pub fn span(&self) -> Span
{
502 TokenTree
::Group(t
) => t
.span(),
503 TokenTree
::Ident(t
) => t
.span(),
504 TokenTree
::Punct(t
) => t
.span(),
505 TokenTree
::Literal(t
) => t
.span(),
509 /// Configures the span for *only this token*.
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.
514 pub fn set_span(&mut self, span
: Span
) {
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
),
524 impl From
<Group
> for TokenTree
{
525 fn from(g
: Group
) -> TokenTree
{
530 impl From
<Ident
> for TokenTree
{
531 fn from(g
: Ident
) -> TokenTree
{
536 impl From
<Punct
> for TokenTree
{
537 fn from(g
: Punct
) -> TokenTree
{
542 impl From
<Literal
> for TokenTree
{
543 fn from(g
: Literal
) -> TokenTree
{
544 TokenTree
::Literal(g
)
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
{
553 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
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
),
563 /// Prints token tree in a form convenient for debugging.
564 impl Debug
for TokenTree
{
565 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
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
);
576 TokenTree
::Punct(t
) => Debug
::fmt(t
, f
),
577 TokenTree
::Literal(t
) => Debug
::fmt(t
, f
),
582 /// A delimited token stream.
584 /// A `Group` internally contains a `TokenStream` which is surrounded by
591 /// Describes how a sequence of token trees is delimited.
592 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
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
611 fn _new(inner
: imp
::Group
) -> Self {
615 fn _new_stable(inner
: fallback
::Group
) -> Self {
621 /// Creates a new `Group` with the given delimiter and token stream.
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`
626 pub fn new(delimiter
: Delimiter
, stream
: TokenStream
) -> Group
{
628 inner
: imp
::Group
::new(delimiter
, stream
.inner
),
632 /// Returns the delimiter of this `Group`
633 pub fn delimiter(&self) -> Delimiter
{
634 self.inner
.delimiter()
637 /// Returns the `TokenStream` of tokens that are delimited in this `Group`.
639 /// Note that the returned token stream does not include the delimiter
641 pub fn stream(&self) -> TokenStream
{
642 TokenStream
::_new(self.inner
.stream())
645 /// Returns the span for the delimiters of this token stream, spanning the
649 /// pub fn span(&self) -> Span {
652 pub fn span(&self) -> Span
{
653 Span
::_new(self.inner
.span())
656 /// Returns the span pointing to the opening delimiter of this group.
659 /// pub fn span_open(&self) -> Span {
662 pub fn span_open(&self) -> Span
{
663 Span
::_new(self.inner
.span_open())
666 /// Returns the span pointing to the closing delimiter of this group.
669 /// pub fn span_close(&self) -> Span {
672 pub fn span_close(&self) -> Span
{
673 Span
::_new(self.inner
.span_close())
676 /// Configures the span for this `Group`'s delimiters, but not its internal
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`.
682 pub fn set_span(&mut self, span
: Span
) {
683 self.inner
.set_span(span
.inner
)
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
{
691 fn fmt(&self, formatter
: &mut fmt
::Formatter
) -> fmt
::Result
{
692 Display
::fmt(&self.inner
, formatter
)
696 impl Debug
for Group
{
697 fn fmt(&self, formatter
: &mut fmt
::Formatter
) -> fmt
::Result
{
698 Debug
::fmt(&self.inner
, formatter
)
702 /// An `Punct` is an single punctuation character like `+`, `-` or `#`.
704 /// Multicharacter operators like `+=` are represented as two instances of
705 /// `Punct` with different forms of `Spacing` returned.
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)]
717 /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`.
719 /// E.g. `+` is `Joint` in `+=` or `'` is `Joint` in `'#`.
721 /// Additionally, single quote `'` can join with identifiers to form
722 /// lifetimes `'ident`.
727 /// Creates a new `Punct` from the given character and spacing.
729 /// The `ch` argument must be a valid punctuation character permitted by the
730 /// language, otherwise the function will panic.
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.
734 pub fn new(ch
: char, spacing
: Spacing
) -> Punct
{
738 span
: Span
::call_site(),
742 /// Returns the value of this punctuation character as `char`.
743 pub fn as_char(&self) -> char {
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.
752 pub fn spacing(&self) -> Spacing
{
756 /// Returns the span for this punctuation character.
757 pub fn span(&self) -> Span
{
761 /// Configure the span for this punctuation character.
762 pub fn set_span(&mut self, span
: Span
) {
767 /// Prints the punctuation character as a string that should be losslessly
768 /// convertible back into the same character.
769 impl Display
for Punct
{
770 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
771 Display
::fmt(&self.ch
, f
)
775 impl Debug
for Punct
{
776 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
);
785 /// A word of Rust code, which may be a keyword or legal variable name.
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
791 /// - The empty string is not an identifier. Use `Option<Ident>`.
792 /// - A lifetime is not an identifier. Use `syn::Lifetime` instead.
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`.
799 /// [`Parse`]: https://docs.rs/syn/1.0/syn/parse/trait.Parse.html
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.
808 /// use proc_macro2::{Ident, Span};
811 /// let call_ident = Ident::new("calligraphy", Span::call_site());
813 /// println!("{}", call_ident);
817 /// An ident can be interpolated into a token stream using the `quote!` macro.
820 /// use proc_macro2::{Ident, Span};
821 /// use quote::quote;
824 /// let ident = Ident::new("demo", Span::call_site());
826 /// // Create a variable binding whose name is this ident.
827 /// let expanded = quote! { let #ident = 10; };
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; };
835 /// A string representation of the ident is available through the `to_string()`
839 /// # use proc_macro2::{Ident, Span};
841 /// # let ident = Ident::new("another_identifier", Span::call_site());
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)
856 fn _new(inner
: imp
::Ident
) -> Ident
{
863 /// Creates a new `Ident` with the given `string` as well as the specified
866 /// The `string` argument must be a valid identifier permitted by the
867 /// language, otherwise the function will panic.
869 /// Note that `span`, currently in rustc, configures the hygiene information
870 /// for this identifier.
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.
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.
882 /// Due to the current importance of hygiene this constructor, unlike other
883 /// tokens, requires a `Span` to be specified at construction.
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`.
894 pub fn new(string
: &str, span
: Span
) -> Ident
{
895 Ident
::_new(imp
::Ident
::new(string
, span
.inner
))
898 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`).
900 /// This method is semver exempt and not exposed by default.
901 #[cfg(procmacro2_semver_exempt)]
902 pub fn new_raw(string
: &str, span
: Span
) -> Ident
{
903 Ident
::_new_raw(string
, span
)
906 fn _new_raw(string
: &str, span
: Span
) -> Ident
{
907 Ident
::_new(imp
::Ident
::new_raw(string
, span
.inner
))
910 /// Returns the span of this `Ident`.
911 pub fn span(&self) -> Span
{
912 Span
::_new(self.inner
.span())
915 /// Configures the span of this `Ident`, possibly changing its hygiene
917 pub fn set_span(&mut self, span
: Span
) {
918 self.inner
.set_span(span
.inner
);
922 impl PartialEq
for Ident
{
923 fn eq(&self, other
: &Ident
) -> bool
{
924 self.inner
== other
.inner
928 impl<T
> PartialEq
<T
> for Ident
930 T
: ?Sized
+ AsRef
<str>,
932 fn eq(&self, other
: &T
) -> bool
{
939 impl PartialOrd
for Ident
{
940 fn partial_cmp(&self, other
: &Ident
) -> Option
<Ordering
> {
941 Some(self.cmp(other
))
946 fn cmp(&self, other
: &Ident
) -> Ordering
{
947 self.to_string().cmp(&other
.to_string())
951 impl Hash
for Ident
{
952 fn hash
<H
: Hasher
>(&self, hasher
: &mut H
) {
953 self.to_string().hash(hasher
)
957 /// Prints the identifier as a string that should be losslessly convertible back
958 /// into the same identifier.
959 impl Display
for Ident
{
960 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
961 Display
::fmt(&self.inner
, f
)
965 impl Debug
for Ident
{
966 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
967 Debug
::fmt(&self.inner
, f
)
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`).
975 /// Boolean literals like `true` and `false` do not belong here, they are
983 macro_rules
! suffixed_int_literals
{
984 ($
($name
:ident
=> $kind
:ident
,)*) => ($
(
985 /// Creates a new suffixed integer literal with the specified value.
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).
993 /// Literals created through this method have the `Span::call_site()`
994 /// span by default, which can be configured with the `set_span` method
996 pub fn $
name(n
: $kind
) -> Literal
{
997 Literal
::_new(imp
::Literal
::$
name(n
))
1002 macro_rules
! unsuffixed_int_literals
{
1003 ($
($name
:ident
=> $kind
:ident
,)*) => ($
(
1004 /// Creates a new unsuffixed integer literal with the specified value.
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).
1014 /// Literals created through this method have the `Span::call_site()`
1015 /// span by default, which can be configured with the `set_span` method
1017 pub fn $
name(n
: $kind
) -> Literal
{
1018 Literal
::_new(imp
::Literal
::$
name(n
))
1024 fn _new(inner
: imp
::Literal
) -> Literal
{
1031 fn _new_stable(inner
: fallback
::Literal
) -> Literal
{
1033 inner
: inner
.into(),
1038 suffixed_int_literals
! {
1040 u16_suffixed
=> u16,
1041 u32_suffixed
=> u32,
1042 u64_suffixed
=> u64,
1043 u128_suffixed
=> u128
,
1044 usize_suffixed
=> usize,
1046 i16_suffixed
=> i16,
1047 i32_suffixed
=> i32,
1048 i64_suffixed
=> i64,
1049 i128_suffixed
=> i128
,
1050 isize_suffixed
=> isize,
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,
1068 /// Creates a new unsuffixed floating-point literal.
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).
1079 /// This function requires that the specified float is finite, for example
1080 /// if it is infinity or NaN this function will panic.
1081 pub fn f64_unsuffixed(f
: f64) -> Literal
{
1082 assert
!(f
.is_finite());
1083 Literal
::_new(imp
::Literal
::f64_unsuffixed(f
))
1086 /// Creates a new suffixed floating-point literal.
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).
1097 /// This function requires that the specified float is finite, for example
1098 /// if it is infinity or NaN this function will panic.
1099 pub fn f64_suffixed(f
: f64) -> Literal
{
1100 assert
!(f
.is_finite());
1101 Literal
::_new(imp
::Literal
::f64_suffixed(f
))
1104 /// Creates a new unsuffixed floating-point literal.
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).
1115 /// This function requires that the specified float is finite, for example
1116 /// if it is infinity or NaN this function will panic.
1117 pub fn f32_unsuffixed(f
: f32) -> Literal
{
1118 assert
!(f
.is_finite());
1119 Literal
::_new(imp
::Literal
::f32_unsuffixed(f
))
1122 /// Creates a new suffixed floating-point literal.
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).
1133 /// This function requires that the specified float is finite, for example
1134 /// if it is infinity or NaN this function will panic.
1135 pub fn f32_suffixed(f
: f32) -> Literal
{
1136 assert
!(f
.is_finite());
1137 Literal
::_new(imp
::Literal
::f32_suffixed(f
))
1141 pub fn string(string
: &str) -> Literal
{
1142 Literal
::_new(imp
::Literal
::string(string
))
1145 /// Character literal.
1146 pub fn character(ch
: char) -> Literal
{
1147 Literal
::_new(imp
::Literal
::character(ch
))
1150 /// Byte string literal.
1151 pub fn byte_string(s
: &[u8]) -> Literal
{
1152 Literal
::_new(imp
::Literal
::byte_string(s
))
1155 /// Returns the span encompassing this literal.
1156 pub fn span(&self) -> Span
{
1157 Span
::_new(self.inner
.span())
1160 /// Configures the span associated for this literal.
1161 pub fn set_span(&mut self, span
: Span
) {
1162 self.inner
.set_span(span
.inner
);
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`.
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`.
1173 /// [`proc_macro::Literal::subspan`]: https://doc.rust-lang.org/proc_macro/struct.Literal.html#method.subspan
1174 pub fn subspan
<R
: RangeBounds
<usize>>(&self, range
: R
) -> Option
<Span
> {
1175 self.inner
.subspan(range
).map(Span
::_new
)
1179 impl Debug
for Literal
{
1180 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
1181 Debug
::fmt(&self.inner
, f
)
1185 impl Display
for Literal
{
1186 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
1187 Display
::fmt(&self.inner
, f
)
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}
;
1197 pub use crate::TokenStream
;
1199 /// An iterator over `TokenStream`'s `TokenTree`s.
1201 /// The iteration is "shallow", e.g. the iterator doesn't recurse into
1202 /// delimited groups, and returns whole groups as token trees.
1204 pub struct IntoIter
{
1205 inner
: imp
::TokenTreeIter
,
1209 impl Iterator
for IntoIter
{
1210 type Item
= TokenTree
;
1212 fn next(&mut self) -> Option
<TokenTree
> {
1217 impl Debug
for IntoIter
{
1218 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
1219 Debug
::fmt(&self.inner
, f
)
1223 impl IntoIterator
for TokenStream
{
1224 type Item
= TokenTree
;
1225 type IntoIter
= IntoIter
;
1227 fn into_iter(self) -> IntoIter
{
1229 inner
: self.inner
.into_iter(),