A "shim crate" intended to multiplex the
proc_macro API on to stable
Procedural macros in Rust operate over the upstream
proc_macro::TokenStream type. This type currently is quite
conservative and exposed no internal implementation details. Nightly
compilers, however, contain a much richer interface. This richer interface
allows fine-grained inspection of the token stream which avoids
stringification/re-lexing and also preserves span information.
The upcoming APIs added to
proc_macro upstream are the foundation for
productive procedural macros in the ecosystem. To help prepare the ecosystem
for using them this crate serves to both compile on stable and nightly and
mirrors the API-to-be. The intention is that procedural macros which switch
to use this crate will be trivially able to switch to the upstream
proc_macro crate once its API stabilizes.
In the meantime this crate also has a
nightly Cargo feature which
enables it to reimplement itself with the unstable API of
This'll allow immediate usage of the beneficial upstream API, particularly
around preserving span information.
proc-macro2 supports exporting some methods from
proc_macro which are
currently highly unstable, and may not be stabilized in the first pass of
proc_macro stabilizations. These features are not exported by default.
Minor versions of
proc-macro2 may make breaking changes to them at any
To enable these features, the
procmacro2_semver_exempt config flag must be
passed to rustc.
RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
Note that this must not only be done for your crate, but for any crate that depends on your crate. This infectious nature is intentional, as it serves as a reminder that you are outside of the normal semver guarantees.
Public implementation details for the
A delimited token stream.
A word of Rust code, which may be a keyword or legal variable name.
Error returned from
A literal string (
A region of source code, along with macro expansion information.
An abstract stream of tokens, or more concretely a sequence of token trees.
Describes how a sequence of token trees is delimited.
A single token or a delimited sequence of token trees (e.g.