Crate proc_macro2

source ·
Expand description

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.

Modules

Public implementation details for the TokenStream type, such as iterators.

Structs

A delimited token stream.
A word of Rust code, which may be a keyword or legal variable name.
Error returned from TokenStream::from_str.
A line-column pair representing the start or end of a Span.
A literal string ("hello"), byte string (b"hello"), character ('a'), byte character (b'a'), an integer or floating point number with or without a suffix (1, 1u8, 2.3, 2.3f32).
An Punct is an single punctuation character like +, - or #.
The source file of a given Span.
A region of source code, along with macro expansion information.
An abstract stream of tokens, or more concretely a sequence of token trees.

Enums

Describes how a sequence of token trees is delimited.
Whether an Punct is followed immediately by another Punct or followed by another token or whitespace.
A single token or a delimited sequence of token trees (e.g. [1, (), ..]).