Crate proc_macro2

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

token_stream

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

Structs

Group	A delimited token stream.
Ident	A word of Rust code, which may be a keyword or legal variable name.
LexError	Error returned from TokenStream::from_str.
Literal	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).
Punct	An Punct is an single punctuation character like +, - or #.
Span	A region of source code, along with macro expansion information.
TokenStream	An abstract stream of tokens, or more concretely a sequence of token trees.

Enums

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