projects/linux·blob master · refs

1355 lines · 44.4 KiB

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3// When fixdep scans this, it will find this string `CONFIG_RUSTC_VERSION_TEXT`
4// and thus add a dependency on `include/config/RUSTC_VERSION_TEXT`, which is
5// touched by Kconfig when the version string from the compiler changes.
6
7//! [![github]](https://github.com/dtolnay/proc-macro2) [![crates-io]](https://crates.io/crates/proc-macro2) [![docs-rs]](crate)
8//!
9//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
10//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
11//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
12//!
13//! <br>
14//!
15//! A wrapper around the procedural macro API of the compiler's [`proc_macro`]
16//! crate. This library serves two purposes:
17//!
18//! - **Bring proc-macro-like functionality to other contexts like build.rs and
19//! main.rs.** Types from `proc_macro` are entirely specific to procedural
20//! macros and cannot ever exist in code outside of a procedural macro.
21//! Meanwhile `proc_macro2` types may exist anywhere including non-macro code.
22//! By developing foundational libraries like [syn] and [quote] against
23//! `proc_macro2` rather than `proc_macro`, the procedural macro ecosystem
24//! becomes easily applicable to many other use cases and we avoid
25//! reimplementing non-macro equivalents of those libraries.
26//!
27//! - **Make procedural macros unit testable.** As a consequence of being
28//! specific to procedural macros, nothing that uses `proc_macro` can be
29//! executed from a unit test. In order for helper libraries or components of
30//! a macro to be testable in isolation, they must be implemented using
31//! `proc_macro2`.
32//!
33//! [syn]: https://github.com/dtolnay/syn
34//! [quote]: https://github.com/dtolnay/quote
35//!
36//! # Usage
37//!
38//! The skeleton of a typical procedural macro typically looks like this:
39//!
40//! ```
41//! extern crate proc_macro;
42//!
43//! # const IGNORE: &str = stringify! {
44//! #[proc_macro_derive(MyDerive)]
45//! # };
46//! # #[cfg(wrap_proc_macro)]
47//! pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
48//! let input = proc_macro2::TokenStream::from(input);
49//!
50//! let output: proc_macro2::TokenStream = {
51//! /* transform input */
52//! # input
53//! };
54//!
55//! proc_macro::TokenStream::from(output)
56//! }
57//! ```
58//!
59//! If parsing with [Syn], you'll use [`parse_macro_input!`] instead to
60//! propagate parse errors correctly back to the compiler when parsing fails.
61//!
62//! [`parse_macro_input!`]: https://docs.rs/syn/2.0/syn/macro.parse_macro_input.html
63//!
64//! # Unstable features
65//!
66//! The default feature set of proc-macro2 tracks the most recent stable
67//! compiler API. Functionality in `proc_macro` that is not yet stable is not
68//! exposed by proc-macro2 by default.
69//!
70//! To opt into the additional APIs available in the most recent nightly
71//! compiler, the `procmacro2_semver_exempt` config flag must be passed to
72//! rustc. We will polyfill those nightly-only APIs back to Rust 1.56.0. As
73//! these are unstable APIs that track the nightly compiler, minor versions of
74//! proc-macro2 may make breaking changes to them at any time.
75//!
76//! ```sh
77//! RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
78//! ```
79//!
80//! Note that this must not only be done for your crate, but for any crate that
81//! depends on your crate. This infectious nature is intentional, as it serves
82//! as a reminder that you are outside of the normal semver guarantees.
83//!
84//! Semver exempt methods are marked as such in the proc-macro2 documentation.
85//!
86//! # Thread-Safety
87//!
88//! Most types in this crate are `!Sync` because the underlying compiler
89//! types make use of thread-local memory, meaning they cannot be accessed from
90//! a different thread.
91
92// Proc-macro2 types in rustdoc of other crates get linked to here.
93#![doc(html_root_url = "https://docs.rs/proc-macro2/1.0.101")]
94#![cfg_attr(any(proc_macro_span, super_unstable), feature(proc_macro_span))]
95#![cfg_attr(super_unstable, feature(proc_macro_def_site))]
96#![cfg_attr(docsrs, feature(doc_cfg))]
97#![deny(unsafe_op_in_unsafe_fn)]
98#![allow(
99 clippy::cast_lossless,
100 clippy::cast_possible_truncation,
101 clippy::checked_conversions,
102 clippy::doc_markdown,
103 clippy::elidable_lifetime_names,
104 clippy::incompatible_msrv,
105 clippy::items_after_statements,
106 clippy::iter_without_into_iter,
107 clippy::let_underscore_untyped,
108 clippy::manual_assert,
109 clippy::manual_range_contains,
110 clippy::missing_panics_doc,
111 clippy::missing_safety_doc,
112 clippy::must_use_candidate,
113 clippy::needless_doctest_main,
114 clippy::needless_lifetimes,
115 clippy::new_without_default,
116 clippy::return_self_not_must_use,
117 clippy::shadow_unrelated,
118 clippy::trivially_copy_pass_by_ref,
119 clippy::unnecessary_wraps,
120 clippy::unused_self,
121 clippy::used_underscore_binding,
122 clippy::vec_init_then_push
123)]
124#![allow(unknown_lints, mismatched_lifetime_syntaxes)]
125
126#[cfg(all(procmacro2_semver_exempt, wrap_proc_macro, not(super_unstable)))]
127compile_error! {"\
128 Something is not right. If you've tried to turn on \
129 procmacro2_semver_exempt, you need to ensure that it \
130 is turned on for the compilation of the proc-macro2 \
131 build script as well.
132"}
133
134#[cfg(all(
135 procmacro2_nightly_testing,
136 feature = "proc-macro",
137 not(proc_macro_span)
138))]
139compile_error! {"\
140 Build script probe failed to compile.
141"}
142
143extern crate alloc;
144
145#[cfg(feature = "proc-macro")]
146extern crate proc_macro;
147
148mod marker;
149mod parse;
150mod probe;
151mod rcvec;
152
153#[cfg(wrap_proc_macro)]
154mod detection;
155
156// Public for proc_macro2::fallback::force() and unforce(), but those are quite
157// a niche use case so we omit it from rustdoc.
158#[doc(hidden)]
159pub mod fallback;
160
161pub mod extra;
162
163#[cfg(not(wrap_proc_macro))]
164use crate::fallback as imp;
165#[path = "wrapper.rs"]
166#[cfg(wrap_proc_macro)]
167mod imp;
168
169#[cfg(span_locations)]
170mod location;
171
172use crate::extra::DelimSpan;
173use crate::marker::{ProcMacroAutoTraits, MARKER};
174use core::cmp::Ordering;
175use core::fmt::{self, Debug, Display};
176use core::hash::{Hash, Hasher};
177#[cfg(span_locations)]
178use core::ops::Range;
179use core::ops::RangeBounds;
180use core::str::FromStr;
181use std::error::Error;
182use std::ffi::CStr;
183#[cfg(span_locations)]
184use std::path::PathBuf;
185
186#[cfg(span_locations)]
187#[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
188pub use crate::location::LineColumn;
189
190/// An abstract stream of tokens, or more concretely a sequence of token trees.
191///
192/// This type provides interfaces for iterating over token trees and for
193/// collecting token trees into one stream.
194///
195/// Token stream is both the input and output of `#[proc_macro]`,
196/// `#[proc_macro_attribute]` and `#[proc_macro_derive]` definitions.
197#[derive(Clone)]
198pub struct TokenStream {
199 inner: imp::TokenStream,
200 _marker: ProcMacroAutoTraits,
201}
202
203/// Error returned from `TokenStream::from_str`.
204pub struct LexError {
205 inner: imp::LexError,
206 _marker: ProcMacroAutoTraits,
207}
208
209impl TokenStream {
210 fn _new(inner: imp::TokenStream) -> Self {
211 TokenStream {
212 inner,
213 _marker: MARKER,
214 }
215 }
216
217 fn _new_fallback(inner: fallback::TokenStream) -> Self {
218 TokenStream {
219 inner: imp::TokenStream::from(inner),
220 _marker: MARKER,
221 }
222 }
223
224 /// Returns an empty `TokenStream` containing no token trees.
225 pub fn new() -> Self {
226 TokenStream::_new(imp::TokenStream::new())
227 }
228
229 /// Checks if this `TokenStream` is empty.
230 pub fn is_empty(&self) -> bool {
231 self.inner.is_empty()
232 }
233}
234
235/// `TokenStream::default()` returns an empty stream,
236/// i.e. this is equivalent with `TokenStream::new()`.
237impl Default for TokenStream {
238 fn default() -> Self {
239 TokenStream::new()
240 }
241}
242
243/// Attempts to break the string into tokens and parse those tokens into a token
244/// stream.
245///
246/// May fail for a number of reasons, for example, if the string contains
247/// unbalanced delimiters or characters not existing in the language.
248///
249/// NOTE: Some errors may cause panics instead of returning `LexError`. We
250/// reserve the right to change these errors into `LexError`s later.
251impl FromStr for TokenStream {
252 type Err = LexError;
253
254 fn from_str(src: &str) -> Result<TokenStream, LexError> {
255 match imp::TokenStream::from_str_checked(src) {
256 Ok(tokens) => Ok(TokenStream::_new(tokens)),
257 Err(lex) => Err(LexError {
258 inner: lex,
259 _marker: MARKER,
260 }),
261 }
262 }
263}
264
265#[cfg(feature = "proc-macro")]
266#[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
267impl From<proc_macro::TokenStream> for TokenStream {
268 fn from(inner: proc_macro::TokenStream) -> Self {
269 TokenStream::_new(imp::TokenStream::from(inner))
270 }
271}
272
273#[cfg(feature = "proc-macro")]
274#[cfg_attr(docsrs, doc(cfg(feature = "proc-macro")))]
275impl From<TokenStream> for proc_macro::TokenStream {
276 fn from(inner: TokenStream) -> Self {
277 proc_macro::TokenStream::from(inner.inner)
278 }
279}
280
281impl From<TokenTree> for TokenStream {
282 fn from(token: TokenTree) -> Self {
283 TokenStream::_new(imp::TokenStream::from(token))
284 }
285}
286
287impl Extend<TokenTree> for TokenStream {
288 fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, streams: I) {
289 self.inner.extend(streams);
290 }
291}
292
293impl Extend<TokenStream> for TokenStream {
294 fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) {
295 self.inner
296 .extend(streams.into_iter().map(|stream| stream.inner));
297 }
298}
299
300/// Collects a number of token trees into a single stream.
301impl FromIterator<TokenTree> for TokenStream {
302 fn from_iter<I: IntoIterator<Item = TokenTree>>(streams: I) -> Self {
303 TokenStream::_new(streams.into_iter().collect())
304 }
305}
306impl FromIterator<TokenStream> for TokenStream {
307 fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self {
308 TokenStream::_new(streams.into_iter().map(|i| i.inner).collect())
309 }
310}
311
312/// Prints the token stream as a string that is supposed to be losslessly
313/// convertible back into the same token stream (modulo spans), except for
314/// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative
315/// numeric literals.
316impl Display for TokenStream {
317 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
318 Display::fmt(&self.inner, f)
319 }
320}
321
322/// Prints token in a form convenient for debugging.
323impl Debug for TokenStream {
324 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
325 Debug::fmt(&self.inner, f)
326 }
327}
328
329impl LexError {
330 pub fn span(&self) -> Span {
331 Span::_new(self.inner.span())
332 }
333}
334
335impl Debug for LexError {
336 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
337 Debug::fmt(&self.inner, f)
338 }
339}
340
341impl Display for LexError {
342 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
343 Display::fmt(&self.inner, f)
344 }
345}
346
347impl Error for LexError {}
348
349/// A region of source code, along with macro expansion information.
350#[derive(Copy, Clone)]
351pub struct Span {
352 inner: imp::Span,
353 _marker: ProcMacroAutoTraits,
354}
355
356impl Span {
357 fn _new(inner: imp::Span) -> Self {
358 Span {
359 inner,
360 _marker: MARKER,
361 }
362 }
363
364 fn _new_fallback(inner: fallback::Span) -> Self {
365 Span {
366 inner: imp::Span::from(inner),
367 _marker: MARKER,
368 }
369 }
370
371 /// The span of the invocation of the current procedural macro.
372 ///
373 /// Identifiers created with this span will be resolved as if they were
374 /// written directly at the macro call location (call-site hygiene) and
375 /// other code at the macro call site will be able to refer to them as well.
376 pub fn call_site() -> Self {
377 Span::_new(imp::Span::call_site())
378 }
379
380 /// The span located at the invocation of the procedural macro, but with
381 /// local variables, labels, and `$crate` resolved at the definition site
382 /// of the macro. This is the same hygiene behavior as `macro_rules`.
383 pub fn mixed_site() -> Self {
384 Span::_new(imp::Span::mixed_site())
385 }
386
387 /// A span that resolves at the macro definition site.
388 ///
389 /// This method is semver exempt and not exposed by default.
390 #[cfg(procmacro2_semver_exempt)]
391 #[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
392 pub fn def_site() -> Self {
393 Span::_new(imp::Span::def_site())
394 }
395
396 /// Creates a new span with the same line/column information as `self` but
397 /// that resolves symbols as though it were at `other`.
398 pub fn resolved_at(&self, other: Span) -> Span {
399 Span::_new(self.inner.resolved_at(other.inner))
400 }
401
402 /// Creates a new span with the same name resolution behavior as `self` but
403 /// with the line/column information of `other`.
404 pub fn located_at(&self, other: Span) -> Span {
405 Span::_new(self.inner.located_at(other.inner))
406 }
407
408 /// Convert `proc_macro2::Span` to `proc_macro::Span`.
409 ///
410 /// This method is available when building with a nightly compiler, or when
411 /// building with rustc 1.29+ *without* semver exempt features.
412 ///
413 /// # Panics
414 ///
415 /// Panics if called from outside of a procedural macro. Unlike
416 /// `proc_macro2::Span`, the `proc_macro::Span` type can only exist within
417 /// the context of a procedural macro invocation.
418 #[cfg(wrap_proc_macro)]
419 pub fn unwrap(self) -> proc_macro::Span {
420 self.inner.unwrap()
421 }
422
423 // Soft deprecated. Please use Span::unwrap.
424 #[cfg(wrap_proc_macro)]
425 #[doc(hidden)]
426 pub fn unstable(self) -> proc_macro::Span {
427 self.unwrap()
428 }
429
430 /// Returns the span's byte position range in the source file.
431 ///
432 /// This method requires the `"span-locations"` feature to be enabled.
433 ///
434 /// When executing in a procedural macro context, the returned range is only
435 /// accurate if compiled with a nightly toolchain. The stable toolchain does
436 /// not have this information available. When executing outside of a
437 /// procedural macro, such as main.rs or build.rs, the byte range is always
438 /// accurate regardless of toolchain.
439 #[cfg(span_locations)]
440 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
441 pub fn byte_range(&self) -> Range<usize> {
442 self.inner.byte_range()
443 }
444
445 /// Get the starting line/column in the source file for this span.
446 ///
447 /// This method requires the `"span-locations"` feature to be enabled.
448 ///
449 /// When executing in a procedural macro context, the returned line/column
450 /// are only meaningful if compiled with a nightly toolchain. The stable
451 /// toolchain does not have this information available. When executing
452 /// outside of a procedural macro, such as main.rs or build.rs, the
453 /// line/column are always meaningful regardless of toolchain.
454 #[cfg(span_locations)]
455 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
456 pub fn start(&self) -> LineColumn {
457 self.inner.start()
458 }
459
460 /// Get the ending line/column in the source file for this span.
461 ///
462 /// This method requires the `"span-locations"` feature to be enabled.
463 ///
464 /// When executing in a procedural macro context, the returned line/column
465 /// are only meaningful if compiled with a nightly toolchain. The stable
466 /// toolchain does not have this information available. When executing
467 /// outside of a procedural macro, such as main.rs or build.rs, the
468 /// line/column are always meaningful regardless of toolchain.
469 #[cfg(span_locations)]
470 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
471 pub fn end(&self) -> LineColumn {
472 self.inner.end()
473 }
474
475 /// The path to the source file in which this span occurs, for display
476 /// purposes.
477 ///
478 /// This might not correspond to a valid file system path. It might be
479 /// remapped, or might be an artificial path such as `"<macro expansion>"`.
480 #[cfg(span_locations)]
481 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
482 pub fn file(&self) -> String {
483 self.inner.file()
484 }
485
486 /// The path to the source file in which this span occurs on disk.
487 ///
488 /// This is the actual path on disk. It is unaffected by path remapping.
489 ///
490 /// This path should not be embedded in the output of the macro; prefer
491 /// `file()` instead.
492 #[cfg(span_locations)]
493 #[cfg_attr(docsrs, doc(cfg(feature = "span-locations")))]
494 pub fn local_file(&self) -> Option<PathBuf> {
495 self.inner.local_file()
496 }
497
498 /// Create a new span encompassing `self` and `other`.
499 ///
500 /// Returns `None` if `self` and `other` are from different files.
501 ///
502 /// Warning: the underlying [`proc_macro::Span::join`] method is
503 /// nightly-only. When called from within a procedural macro not using a
504 /// nightly compiler, this method will always return `None`.
505 pub fn join(&self, other: Span) -> Option<Span> {
506 self.inner.join(other.inner).map(Span::_new)
507 }
508
509 /// Compares two spans to see if they're equal.
510 ///
511 /// This method is semver exempt and not exposed by default.
512 #[cfg(procmacro2_semver_exempt)]
513 #[cfg_attr(docsrs, doc(cfg(procmacro2_semver_exempt)))]
514 pub fn eq(&self, other: &Span) -> bool {
515 self.inner.eq(&other.inner)
516 }
517
518 /// Returns the source text behind a span. This preserves the original
519 /// source code, including spaces and comments. It only returns a result if
520 /// the span corresponds to real source code.
521 ///
522 /// Note: The observable result of a macro should only rely on the tokens
523 /// and not on this source text. The result of this function is a best
524 /// effort to be used for diagnostics only.
525 pub fn source_text(&self) -> Option<String> {
526 self.inner.source_text()
527 }
528}
529
530/// Prints a span in a form convenient for debugging.
531impl Debug for Span {
532 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
533 Debug::fmt(&self.inner, f)
534 }
535}
536
537/// A single token or a delimited sequence of token trees (e.g. `[1, (), ..]`).
538#[derive(Clone)]
539pub enum TokenTree {
540 /// A token stream surrounded by bracket delimiters.
541 Group(Group),
542 /// An identifier.
543 Ident(Ident),
544 /// A single punctuation character (`+`, `,`, `$`, etc.).
545 Punct(Punct),
546 /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc.
547 Literal(Literal),
548}
549
550impl TokenTree {
551 /// Returns the span of this tree, delegating to the `span` method of
552 /// the contained token or a delimited stream.
553 pub fn span(&self) -> Span {
554 match self {
555 TokenTree::Group(t) => t.span(),
556 TokenTree::Ident(t) => t.span(),
557 TokenTree::Punct(t) => t.span(),
558 TokenTree::Literal(t) => t.span(),
559 }
560 }
561
562 /// Configures the span for *only this token*.
563 ///
564 /// Note that if this token is a `Group` then this method will not configure
565 /// the span of each of the internal tokens, this will simply delegate to
566 /// the `set_span` method of each variant.
567 pub fn set_span(&mut self, span: Span) {
568 match self {
569 TokenTree::Group(t) => t.set_span(span),
570 TokenTree::Ident(t) => t.set_span(span),
571 TokenTree::Punct(t) => t.set_span(span),
572 TokenTree::Literal(t) => t.set_span(span),
573 }
574 }
575}
576
577impl From<Group> for TokenTree {
578 fn from(g: Group) -> Self {
579 TokenTree::Group(g)
580 }
581}
582
583impl From<Ident> for TokenTree {
584 fn from(g: Ident) -> Self {
585 TokenTree::Ident(g)
586 }
587}
588
589impl From<Punct> for TokenTree {
590 fn from(g: Punct) -> Self {
591 TokenTree::Punct(g)
592 }
593}
594
595impl From<Literal> for TokenTree {
596 fn from(g: Literal) -> Self {
597 TokenTree::Literal(g)
598 }
599}
600
601/// Prints the token tree as a string that is supposed to be losslessly
602/// convertible back into the same token tree (modulo spans), except for
603/// possibly `TokenTree::Group`s with `Delimiter::None` delimiters and negative
604/// numeric literals.
605impl Display for TokenTree {
606 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
607 match self {
608 TokenTree::Group(t) => Display::fmt(t, f),
609 TokenTree::Ident(t) => Display::fmt(t, f),
610 TokenTree::Punct(t) => Display::fmt(t, f),
611 TokenTree::Literal(t) => Display::fmt(t, f),
612 }
613 }
614}
615
616/// Prints token tree in a form convenient for debugging.
617impl Debug for TokenTree {
618 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
619 // Each of these has the name in the struct type in the derived debug,
620 // so don't bother with an extra layer of indirection
621 match self {
622 TokenTree::Group(t) => Debug::fmt(t, f),
623 TokenTree::Ident(t) => {
624 let mut debug = f.debug_struct("Ident");
625 debug.field("sym", &format_args!("{}", t));
626 imp::debug_span_field_if_nontrivial(&mut debug, t.span().inner);
627 debug.finish()
628 }
629 TokenTree::Punct(t) => Debug::fmt(t, f),
630 TokenTree::Literal(t) => Debug::fmt(t, f),
631 }
632 }
633}
634
635/// A delimited token stream.
636///
637/// A `Group` internally contains a `TokenStream` which is surrounded by
638/// `Delimiter`s.
639#[derive(Clone)]
640pub struct Group {
641 inner: imp::Group,
642}
643
644/// Describes how a sequence of token trees is delimited.
645#[derive(Copy, Clone, Debug, Eq, PartialEq)]
646pub enum Delimiter {
647 /// `( ... )`
648 Parenthesis,
649 /// `{ ... }`
650 Brace,
651 /// `[ ... ]`
652 Bracket,
653 /// `∅ ... ∅`
654 ///
655 /// An invisible delimiter, that may, for example, appear around tokens
656 /// coming from a "macro variable" `$var`. It is important to preserve
657 /// operator priorities in cases like `$var * 3` where `$var` is `1 + 2`.
658 /// Invisible delimiters may not survive roundtrip of a token stream through
659 /// a string.
660 ///
661 /// <div class="warning">
662 ///
663 /// Note: rustc currently can ignore the grouping of tokens delimited by `None` in the output
664 /// of a proc_macro. Only `None`-delimited groups created by a macro_rules macro in the input
665 /// of a proc_macro macro are preserved, and only in very specific circumstances.
666 /// Any `None`-delimited groups (re)created by a proc_macro will therefore not preserve
667 /// operator priorities as indicated above. The other `Delimiter` variants should be used
668 /// instead in this context. This is a rustc bug. For details, see
669 /// [rust-lang/rust#67062](https://github.com/rust-lang/rust/issues/67062).
670 ///
671 /// </div>
672 None,
673}
674
675impl Group {
676 fn _new(inner: imp::Group) -> Self {
677 Group { inner }
678 }
679
680 fn _new_fallback(inner: fallback::Group) -> Self {
681 Group {
682 inner: imp::Group::from(inner),
683 }
684 }
685
686 /// Creates a new `Group` with the given delimiter and token stream.
687 ///
688 /// This constructor will set the span for this group to
689 /// `Span::call_site()`. To change the span you can use the `set_span`
690 /// method below.
691 pub fn new(delimiter: Delimiter, stream: TokenStream) -> Self {
692 Group {
693 inner: imp::Group::new(delimiter, stream.inner),
694 }
695 }
696
697 /// Returns the punctuation used as the delimiter for this group: a set of
698 /// parentheses, square brackets, or curly braces.
699 pub fn delimiter(&self) -> Delimiter {
700 self.inner.delimiter()
701 }
702
703 /// Returns the `TokenStream` of tokens that are delimited in this `Group`.
704 ///
705 /// Note that the returned token stream does not include the delimiter
706 /// returned above.
707 pub fn stream(&self) -> TokenStream {
708 TokenStream::_new(self.inner.stream())
709 }
710
711 /// Returns the span for the delimiters of this token stream, spanning the
712 /// entire `Group`.
713 ///
714 /// ```text
715 /// pub fn span(&self) -> Span {
716 /// ^^^^^^^
717 /// ```
718 pub fn span(&self) -> Span {
719 Span::_new(self.inner.span())
720 }
721
722 /// Returns the span pointing to the opening delimiter of this group.
723 ///
724 /// ```text
725 /// pub fn span_open(&self) -> Span {
726 /// ^
727 /// ```
728 pub fn span_open(&self) -> Span {
729 Span::_new(self.inner.span_open())
730 }
731
732 /// Returns the span pointing to the closing delimiter of this group.
733 ///
734 /// ```text
735 /// pub fn span_close(&self) -> Span {
736 /// ^
737 /// ```
738 pub fn span_close(&self) -> Span {
739 Span::_new(self.inner.span_close())
740 }
741
742 /// Returns an object that holds this group's `span_open()` and
743 /// `span_close()` together (in a more compact representation than holding
744 /// those 2 spans individually).
745 pub fn delim_span(&self) -> DelimSpan {
746 DelimSpan::new(&self.inner)
747 }
748
749 /// Configures the span for this `Group`'s delimiters, but not its internal
750 /// tokens.
751 ///
752 /// This method will **not** set the span of all the internal tokens spanned
753 /// by this group, but rather it will only set the span of the delimiter
754 /// tokens at the level of the `Group`.
755 pub fn set_span(&mut self, span: Span) {
756 self.inner.set_span(span.inner);
757 }
758}
759
760/// Prints the group as a string that should be losslessly convertible back
761/// into the same group (modulo spans), except for possibly `TokenTree::Group`s
762/// with `Delimiter::None` delimiters.
763impl Display for Group {
764 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
765 Display::fmt(&self.inner, formatter)
766 }
767}
768
769impl Debug for Group {
770 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
771 Debug::fmt(&self.inner, formatter)
772 }
773}
774
775/// A `Punct` is a single punctuation character like `+`, `-` or `#`.
776///
777/// Multicharacter operators like `+=` are represented as two instances of
778/// `Punct` with different forms of `Spacing` returned.
779#[derive(Clone)]
780pub struct Punct {
781 ch: char,
782 spacing: Spacing,
783 span: Span,
784}
785
786/// Whether a `Punct` is followed immediately by another `Punct` or followed by
787/// another token or whitespace.
788#[derive(Copy, Clone, Debug, Eq, PartialEq)]
789pub enum Spacing {
790 /// E.g. `+` is `Alone` in `+ =`, `+ident` or `+()`.
791 Alone,
792 /// E.g. `+` is `Joint` in `+=` or `'` is `Joint` in `'#`.
793 ///
794 /// Additionally, single quote `'` can join with identifiers to form
795 /// lifetimes `'ident`.
796 Joint,
797}
798
799impl Punct {
800 /// Creates a new `Punct` from the given character and spacing.
801 ///
802 /// The `ch` argument must be a valid punctuation character permitted by the
803 /// language, otherwise the function will panic.
804 ///
805 /// The returned `Punct` will have the default span of `Span::call_site()`
806 /// which can be further configured with the `set_span` method below.
807 pub fn new(ch: char, spacing: Spacing) -> Self {
808 if let '!' | '#' | '$' | '%' | '&' | '\'' | '*' | '+' | ',' | '-' | '.' | '/' | ':' | ';'
809 | '<' | '=' | '>' | '?' | '@' | '^' | '|' | '~' = ch
810 {
811 Punct {
812 ch,
813 spacing,
814 span: Span::call_site(),
815 }
816 } else {
817 panic!("unsupported proc macro punctuation character {:?}", ch);
818 }
819 }
820
821 /// Returns the value of this punctuation character as `char`.
822 pub fn as_char(&self) -> char {
823 self.ch
824 }
825
826 /// Returns the spacing of this punctuation character, indicating whether
827 /// it's immediately followed by another `Punct` in the token stream, so
828 /// they can potentially be combined into a multicharacter operator
829 /// (`Joint`), or it's followed by some other token or whitespace (`Alone`)
830 /// so the operator has certainly ended.
831 pub fn spacing(&self) -> Spacing {
832 self.spacing
833 }
834
835 /// Returns the span for this punctuation character.
836 pub fn span(&self) -> Span {
837 self.span
838 }
839
840 /// Configure the span for this punctuation character.
841 pub fn set_span(&mut self, span: Span) {
842 self.span = span;
843 }
844}
845
846/// Prints the punctuation character as a string that should be losslessly
847/// convertible back into the same character.
848impl Display for Punct {
849 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
850 Display::fmt(&self.ch, f)
851 }
852}
853
854impl Debug for Punct {
855 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
856 let mut debug = fmt.debug_struct("Punct");
857 debug.field("char", &self.ch);
858 debug.field("spacing", &self.spacing);
859 imp::debug_span_field_if_nontrivial(&mut debug, self.span.inner);
860 debug.finish()
861 }
862}
863
864/// A word of Rust code, which may be a keyword or legal variable name.
865///
866/// An identifier consists of at least one Unicode code point, the first of
867/// which has the XID_Start property and the rest of which have the XID_Continue
868/// property.
869///
870/// - The empty string is not an identifier. Use `Option<Ident>`.
871/// - A lifetime is not an identifier. Use `syn::Lifetime` instead.
872///
873/// An identifier constructed with `Ident::new` is permitted to be a Rust
874/// keyword, though parsing one through its [`Parse`] implementation rejects
875/// Rust keywords. Use `input.call(Ident::parse_any)` when parsing to match the
876/// behaviour of `Ident::new`.
877///
878/// [`Parse`]: https://docs.rs/syn/2.0/syn/parse/trait.Parse.html
879///
880/// # Examples
881///
882/// A new ident can be created from a string using the `Ident::new` function.
883/// A span must be provided explicitly which governs the name resolution
884/// behavior of the resulting identifier.
885///
886/// ```
887/// use proc_macro2::{Ident, Span};
888///
889/// fn main() {
890/// let call_ident = Ident::new("calligraphy", Span::call_site());
891///
892/// println!("{}", call_ident);
893/// }
894/// ```
895///
896/// An ident can be interpolated into a token stream using the `quote!` macro.
897///
898/// ```
899/// use proc_macro2::{Ident, Span};
900/// use quote::quote;
901///
902/// fn main() {
903/// let ident = Ident::new("demo", Span::call_site());
904///
905/// // Create a variable binding whose name is this ident.
906/// let expanded = quote! { let #ident = 10; };
907///
908/// // Create a variable binding with a slightly different name.
909/// let temp_ident = Ident::new(&format!("new_{}", ident), Span::call_site());
910/// let expanded = quote! { let #temp_ident = 10; };
911/// }
912/// ```
913///
914/// A string representation of the ident is available through the `to_string()`
915/// method.
916///
917/// ```
918/// # use proc_macro2::{Ident, Span};
919/// #
920/// # let ident = Ident::new("another_identifier", Span::call_site());
921/// #
922/// // Examine the ident as a string.
923/// let ident_string = ident.to_string();
924/// if ident_string.len() > 60 {
925/// println!("Very long identifier: {}", ident_string)
926/// }
927/// ```
928#[derive(Clone)]
929pub struct Ident {
930 inner: imp::Ident,
931 _marker: ProcMacroAutoTraits,
932}
933
934impl Ident {
935 fn _new(inner: imp::Ident) -> Self {
936 Ident {
937 inner,
938 _marker: MARKER,
939 }
940 }
941
942 fn _new_fallback(inner: fallback::Ident) -> Self {
943 Ident {
944 inner: imp::Ident::from(inner),
945 _marker: MARKER,
946 }
947 }
948
949 /// Creates a new `Ident` with the given `string` as well as the specified
950 /// `span`.
951 ///
952 /// The `string` argument must be a valid identifier permitted by the
953 /// language, otherwise the function will panic.
954 ///
955 /// Note that `span`, currently in rustc, configures the hygiene information
956 /// for this identifier.
957 ///
958 /// As of this time `Span::call_site()` explicitly opts-in to "call-site"
959 /// hygiene meaning that identifiers created with this span will be resolved
960 /// as if they were written directly at the location of the macro call, and
961 /// other code at the macro call site will be able to refer to them as well.
962 ///
963 /// Later spans like `Span::def_site()` will allow to opt-in to
964 /// "definition-site" hygiene meaning that identifiers created with this
965 /// span will be resolved at the location of the macro definition and other
966 /// code at the macro call site will not be able to refer to them.
967 ///
968 /// Due to the current importance of hygiene this constructor, unlike other
969 /// tokens, requires a `Span` to be specified at construction.
970 ///
971 /// # Panics
972 ///
973 /// Panics if the input string is neither a keyword nor a legal variable
974 /// name. If you are not sure whether the string contains an identifier and
975 /// need to handle an error case, use
976 /// <a href="https://docs.rs/syn/2.0/syn/fn.parse_str.html"><code
977 /// style="padding-right:0;">syn::parse_str</code></a><code
978 /// style="padding-left:0;">::&lt;Ident&gt;</code>
979 /// rather than `Ident::new`.
980 #[track_caller]
981 pub fn new(string: &str, span: Span) -> Self {
982 Ident::_new(imp::Ident::new_checked(string, span.inner))
983 }
984
985 /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). The
986 /// `string` argument must be a valid identifier permitted by the language
987 /// (including keywords, e.g. `fn`). Keywords which are usable in path
988 /// segments (e.g. `self`, `super`) are not supported, and will cause a
989 /// panic.
990 #[track_caller]
991 pub fn new_raw(string: &str, span: Span) -> Self {
992 Ident::_new(imp::Ident::new_raw_checked(string, span.inner))
993 }
994
995 /// Returns the span of this `Ident`.
996 pub fn span(&self) -> Span {
997 Span::_new(self.inner.span())
998 }
999
1000 /// Configures the span of this `Ident`, possibly changing its hygiene
1001 /// context.
1002 pub fn set_span(&mut self, span: Span) {
1003 self.inner.set_span(span.inner);
1004 }
1005}
1006
1007impl PartialEq for Ident {
1008 fn eq(&self, other: &Ident) -> bool {
1009 self.inner == other.inner
1010 }
1011}
1012
1013impl<T> PartialEq<T> for Ident
1014where
1015 T: ?Sized + AsRef<str>,
1016{
1017 fn eq(&self, other: &T) -> bool {
1018 self.inner == other
1019 }
1020}
1021
1022impl Eq for Ident {}
1023
1024impl PartialOrd for Ident {
1025 fn partial_cmp(&self, other: &Ident) -> Option<Ordering> {
1026 Some(self.cmp(other))
1027 }
1028}
1029
1030impl Ord for Ident {
1031 fn cmp(&self, other: &Ident) -> Ordering {
1032 self.to_string().cmp(&other.to_string())
1033 }
1034}
1035
1036impl Hash for Ident {
1037 fn hash<H: Hasher>(&self, hasher: &mut H) {
1038 self.to_string().hash(hasher);
1039 }
1040}
1041
1042/// Prints the identifier as a string that should be losslessly convertible back
1043/// into the same identifier.
1044impl Display for Ident {
1045 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1046 Display::fmt(&self.inner, f)
1047 }
1048}
1049
1050impl Debug for Ident {
1051 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1052 Debug::fmt(&self.inner, f)
1053 }
1054}
1055
1056/// A literal string (`"hello"`), byte string (`b"hello"`), character (`'a'`),
1057/// byte character (`b'a'`), an integer or floating point number with or without
1058/// a suffix (`1`, `1u8`, `2.3`, `2.3f32`).
1059///
1060/// Boolean literals like `true` and `false` do not belong here, they are
1061/// `Ident`s.
1062#[derive(Clone)]
1063pub struct Literal {
1064 inner: imp::Literal,
1065 _marker: ProcMacroAutoTraits,
1066}
1067
1068macro_rules! suffixed_int_literals {
1069 ($($name:ident => $kind:ident,)*) => ($(
1070 /// Creates a new suffixed integer literal with the specified value.
1071 ///
1072 /// This function will create an integer like `1u32` where the integer
1073 /// value specified is the first part of the token and the integral is
1074 /// also suffixed at the end. Literals created from negative numbers may
1075 /// not survive roundtrips through `TokenStream` or strings and may be
1076 /// broken into two tokens (`-` and positive literal).
1077 ///
1078 /// Literals created through this method have the `Span::call_site()`
1079 /// span by default, which can be configured with the `set_span` method
1080 /// below.
1081 pub fn $name(n: $kind) -> Literal {
1082 Literal::_new(imp::Literal::$name(n))
1083 }
1084 )*)
1085}
1086
1087macro_rules! unsuffixed_int_literals {
1088 ($($name:ident => $kind:ident,)*) => ($(
1089 /// Creates a new unsuffixed integer literal with the specified value.
1090 ///
1091 /// This function will create an integer like `1` where the integer
1092 /// value specified is the first part of the token. No suffix is
1093 /// specified on this token, meaning that invocations like
1094 /// `Literal::i8_unsuffixed(1)` are equivalent to
1095 /// `Literal::u32_unsuffixed(1)`. Literals created from negative numbers
1096 /// may not survive roundtrips through `TokenStream` or strings and may
1097 /// be broken into two tokens (`-` and positive literal).
1098 ///
1099 /// Literals created through this method have the `Span::call_site()`
1100 /// span by default, which can be configured with the `set_span` method
1101 /// below.
1102 pub fn $name(n: $kind) -> Literal {
1103 Literal::_new(imp::Literal::$name(n))
1104 }
1105 )*)
1106}
1107
1108impl Literal {
1109 fn _new(inner: imp::Literal) -> Self {
1110 Literal {
1111 inner,
1112 _marker: MARKER,
1113 }
1114 }
1115
1116 fn _new_fallback(inner: fallback::Literal) -> Self {
1117 Literal {
1118 inner: imp::Literal::from(inner),
1119 _marker: MARKER,
1120 }
1121 }
1122
1123 suffixed_int_literals! {
1124 u8_suffixed => u8,
1125 u16_suffixed => u16,
1126 u32_suffixed => u32,
1127 u64_suffixed => u64,
1128 u128_suffixed => u128,
1129 usize_suffixed => usize,
1130 i8_suffixed => i8,
1131 i16_suffixed => i16,
1132 i32_suffixed => i32,
1133 i64_suffixed => i64,
1134 i128_suffixed => i128,
1135 isize_suffixed => isize,
1136 }
1137
1138 unsuffixed_int_literals! {
1139 u8_unsuffixed => u8,
1140 u16_unsuffixed => u16,
1141 u32_unsuffixed => u32,
1142 u64_unsuffixed => u64,
1143 u128_unsuffixed => u128,
1144 usize_unsuffixed => usize,
1145 i8_unsuffixed => i8,
1146 i16_unsuffixed => i16,
1147 i32_unsuffixed => i32,
1148 i64_unsuffixed => i64,
1149 i128_unsuffixed => i128,
1150 isize_unsuffixed => isize,
1151 }
1152
1153 /// Creates a new unsuffixed floating-point literal.
1154 ///
1155 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1156 /// the float's value is emitted directly into the token but no suffix is
1157 /// used, so it may be inferred to be a `f64` later in the compiler.
1158 /// Literals created from negative numbers may not survive round-trips
1159 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1160 /// and positive literal).
1161 ///
1162 /// # Panics
1163 ///
1164 /// This function requires that the specified float is finite, for example
1165 /// if it is infinity or NaN this function will panic.
1166 pub fn f64_unsuffixed(f: f64) -> Literal {
1167 assert!(f.is_finite());
1168 Literal::_new(imp::Literal::f64_unsuffixed(f))
1169 }
1170
1171 /// Creates a new suffixed floating-point literal.
1172 ///
1173 /// This constructor will create a literal like `1.0f64` where the value
1174 /// specified is the preceding part of the token and `f64` is the suffix of
1175 /// the token. This token will always be inferred to be an `f64` in the
1176 /// compiler. Literals created from negative numbers may not survive
1177 /// round-trips through `TokenStream` or strings and may be broken into two
1178 /// tokens (`-` and positive literal).
1179 ///
1180 /// # Panics
1181 ///
1182 /// This function requires that the specified float is finite, for example
1183 /// if it is infinity or NaN this function will panic.
1184 pub fn f64_suffixed(f: f64) -> Literal {
1185 assert!(f.is_finite());
1186 Literal::_new(imp::Literal::f64_suffixed(f))
1187 }
1188
1189 /// Creates a new unsuffixed floating-point literal.
1190 ///
1191 /// This constructor is similar to those like `Literal::i8_unsuffixed` where
1192 /// the float's value is emitted directly into the token but no suffix is
1193 /// used, so it may be inferred to be a `f64` later in the compiler.
1194 /// Literals created from negative numbers may not survive round-trips
1195 /// through `TokenStream` or strings and may be broken into two tokens (`-`
1196 /// and positive literal).
1197 ///
1198 /// # Panics
1199 ///
1200 /// This function requires that the specified float is finite, for example
1201 /// if it is infinity or NaN this function will panic.
1202 pub fn f32_unsuffixed(f: f32) -> Literal {
1203 assert!(f.is_finite());
1204 Literal::_new(imp::Literal::f32_unsuffixed(f))
1205 }
1206
1207 /// Creates a new suffixed floating-point literal.
1208 ///
1209 /// This constructor will create a literal like `1.0f32` where the value
1210 /// specified is the preceding part of the token and `f32` is the suffix of
1211 /// the token. This token will always be inferred to be an `f32` in the
1212 /// compiler. Literals created from negative numbers may not survive
1213 /// round-trips through `TokenStream` or strings and may be broken into two
1214 /// tokens (`-` and positive literal).
1215 ///
1216 /// # Panics
1217 ///
1218 /// This function requires that the specified float is finite, for example
1219 /// if it is infinity or NaN this function will panic.
1220 pub fn f32_suffixed(f: f32) -> Literal {
1221 assert!(f.is_finite());
1222 Literal::_new(imp::Literal::f32_suffixed(f))
1223 }
1224
1225 /// String literal.
1226 pub fn string(string: &str) -> Literal {
1227 Literal::_new(imp::Literal::string(string))
1228 }
1229
1230 /// Character literal.
1231 pub fn character(ch: char) -> Literal {
1232 Literal::_new(imp::Literal::character(ch))
1233 }
1234
1235 /// Byte character literal.
1236 pub fn byte_character(byte: u8) -> Literal {
1237 Literal::_new(imp::Literal::byte_character(byte))
1238 }
1239
1240 /// Byte string literal.
1241 pub fn byte_string(bytes: &[u8]) -> Literal {
1242 Literal::_new(imp::Literal::byte_string(bytes))
1243 }
1244
1245 /// C string literal.
1246 pub fn c_string(string: &CStr) -> Literal {
1247 Literal::_new(imp::Literal::c_string(string))
1248 }
1249
1250 /// Returns the span encompassing this literal.
1251 pub fn span(&self) -> Span {
1252 Span::_new(self.inner.span())
1253 }
1254
1255 /// Configures the span associated for this literal.
1256 pub fn set_span(&mut self, span: Span) {
1257 self.inner.set_span(span.inner);
1258 }
1259
1260 /// Returns a `Span` that is a subset of `self.span()` containing only
1261 /// the source bytes in range `range`. Returns `None` if the would-be
1262 /// trimmed span is outside the bounds of `self`.
1263 ///
1264 /// Warning: the underlying [`proc_macro::Literal::subspan`] method is
1265 /// nightly-only. When called from within a procedural macro not using a
1266 /// nightly compiler, this method will always return `None`.
1267 pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> {
1268 self.inner.subspan(range).map(Span::_new)
1269 }
1270
1271 // Intended for the `quote!` macro to use when constructing a proc-macro2
1272 // token out of a macro_rules $:literal token, which is already known to be
1273 // a valid literal. This avoids reparsing/validating the literal's string
1274 // representation. This is not public API other than for quote.
1275 #[doc(hidden)]
1276 pub unsafe fn from_str_unchecked(repr: &str) -> Self {
1277 Literal::_new(unsafe { imp::Literal::from_str_unchecked(repr) })
1278 }
1279}
1280
1281impl FromStr for Literal {
1282 type Err = LexError;
1283
1284 fn from_str(repr: &str) -> Result<Self, LexError> {
1285 match imp::Literal::from_str_checked(repr) {
1286 Ok(lit) => Ok(Literal::_new(lit)),
1287 Err(lex) => Err(LexError {
1288 inner: lex,
1289 _marker: MARKER,
1290 }),
1291 }
1292 }
1293}
1294
1295impl Debug for Literal {
1296 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1297 Debug::fmt(&self.inner, f)
1298 }
1299}
1300
1301impl Display for Literal {
1302 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1303 Display::fmt(&self.inner, f)
1304 }
1305}
1306
1307/// Public implementation details for the `TokenStream` type, such as iterators.
1308pub mod token_stream {
1309 use crate::marker::{ProcMacroAutoTraits, MARKER};
1310 use crate::{imp, TokenTree};
1311 use core::fmt::{self, Debug};
1312
1313 pub use crate::TokenStream;
1314
1315 /// An iterator over `TokenStream`'s `TokenTree`s.
1316 ///
1317 /// The iteration is "shallow", e.g. the iterator doesn't recurse into
1318 /// delimited groups, and returns whole groups as token trees.
1319 #[derive(Clone)]
1320 pub struct IntoIter {
1321 inner: imp::TokenTreeIter,
1322 _marker: ProcMacroAutoTraits,
1323 }
1324
1325 impl Iterator for IntoIter {
1326 type Item = TokenTree;
1327
1328 fn next(&mut self) -> Option<TokenTree> {
1329 self.inner.next()
1330 }
1331
1332 fn size_hint(&self) -> (usize, Option<usize>) {
1333 self.inner.size_hint()
1334 }
1335 }
1336
1337 impl Debug for IntoIter {
1338 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1339 f.write_str("TokenStream ")?;
1340 f.debug_list().entries(self.clone()).finish()
1341 }
1342 }
1343
1344 impl IntoIterator for TokenStream {
1345 type Item = TokenTree;
1346 type IntoIter = IntoIter;
1347
1348 fn into_iter(self) -> IntoIter {
1349 IntoIter {
1350 inner: self.inner.into_iter(),
1351 _marker: MARKER,
1352 }
1353 }
1354 }
1355}