Crate proc_macro2 [] [src]

A "shim crate" intended to multiplex the proc_macro API on to stable Rust.

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 proc_macro. This'll allow immediate usage of the beneficial upstream API, particularly around preserving span information.

Unstable Features

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 time.

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.