Expand description
A wrapper around the procedural macro API of the compiler’s proc_macro
crate. This library serves two purposes:
-
Bring proc-macro-like functionality to other contexts like build.rs and main.rs. Types from
proc_macro
are entirely specific to procedural macros and cannot ever exist in code outside of a procedural macro. Meanwhileproc_macro2
types may exist anywhere including non-macro code. By developing foundational libraries like syn and quote againstproc_macro2
rather thanproc_macro
, the procedural macro ecosystem becomes easily applicable to many other use cases and we avoid reimplementing non-macro equivalents of those libraries. -
Make procedural macros unit testable. As a consequence of being specific to procedural macros, nothing that uses
proc_macro
can be executed from a unit test. In order for helper libraries or components of a macro to be testable in isolation, they must be implemented usingproc_macro2
.
§Usage
The skeleton of a typical procedural macro typically looks like this:
extern crate proc_macro;
#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
let input = proc_macro2::TokenStream::from(input);
let output: proc_macro2::TokenStream = {
/* transform input */
};
proc_macro::TokenStream::from(output)
}
If parsing with Syn, you’ll use parse_macro_input!
instead to
propagate parse errors correctly back to the compiler when parsing fails.
§Unstable features
The default feature set of proc-macro2 tracks the most recent stable
compiler API. Functionality in proc_macro
that is not yet stable is not
exposed by proc-macro2 by default.
To opt into the additional APIs available in the most recent nightly
compiler, the procmacro2_semver_exempt
config flag must be passed to
rustc. We will polyfill those nightly-only APIs back to Rust 1.56.0. As
these are unstable APIs that track the nightly compiler, minor versions of
proc-macro2 may make breaking changes to them at any time.
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.
Semver exempt methods are marked as such in the proc-macro2 documentation.
§Thread-Safety
Most types in this crate are !Sync
because the underlying compiler
types make use of thread-local memory, meaning they cannot be accessed from
a different thread.
Modules§
- Items which do not have a correspondence to any API in the proc_macro crate, but are necessary to include in proc-macro2.
- 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
). - A
Punct
is a single punctuation character like+
,-
or#
. - 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 a
Punct
is followed immediately by anotherPunct
or followed by another token or whitespace. - A single token or a delimited sequence of token trees (e.g.
[1, (), ..]
).