Debian Codegraph @

.cargo/vendor/proc-macro2/README.md

raw
1 # proc-macro2
2
3 [<img alt="github" src="https://img.shields.io/badge/github-dtolnay/proc--macro2-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/proc-macro2)
4 [<img alt="crates.io" src="https://img.shields.io/crates/v/proc-macro2.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/proc-macro2)
5 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-proc--macro2-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/proc-macro2)
6 [<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/proc-macro2/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/proc-macro2/actions?query=branch%3Amaster)
7
8 A wrapper around the procedural macro API of the compiler's `proc_macro` crate.
9 This library serves two purposes:
10
11 - **Bring proc-macro-like functionality to other contexts like build.rs and
12 main.rs.** Types from `proc_macro` are entirely specific to procedural macros
13 and cannot ever exist in code outside of a procedural macro. Meanwhile
14 `proc_macro2` types may exist anywhere including non-macro code. By developing
15 foundational libraries like [syn] and [quote] against `proc_macro2` rather
16 than `proc_macro`, the procedural macro ecosystem becomes easily applicable to
17 many other use cases and we avoid reimplementing non-macro equivalents of
18 those libraries.
19
20 - **Make procedural macros unit testable.** As a consequence of being specific
21 to procedural macros, nothing that uses `proc_macro` can be executed from a
22 unit test. In order for helper libraries or components of a macro to be
23 testable in isolation, they must be implemented using `proc_macro2`.
24
25 [syn]: https://github.com/dtolnay/syn
26 [quote]: https://github.com/dtolnay/quote
27
28 ## Usage
29
30 ```toml
31 [dependencies]
32 proc-macro2 = "1.0"
33 ```
34
35 The skeleton of a typical procedural macro typically looks like this:
36
37 ```rust
38 extern crate proc_macro;
39
40 #[proc_macro_derive(MyDerive)]
41 pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
42 let input = proc_macro2::TokenStream::from(input);
43
44 let output: proc_macro2::TokenStream = {
45 /* transform input */
46 };
47
48 proc_macro::TokenStream::from(output)
49 }
50 ```
51
52 If parsing with [Syn], you'll use [`parse_macro_input!`] instead to propagate
53 parse errors correctly back to the compiler when parsing fails.
54
55 [`parse_macro_input!`]: https://docs.rs/syn/2.0/syn/macro.parse_macro_input.html
56
57 ## Unstable features
58
59 The default feature set of proc-macro2 tracks the most recent stable compiler
60 API. Functionality in `proc_macro` that is not yet stable is not exposed by
61 proc-macro2 by default.
62
63 To opt into the additional APIs available in the most recent nightly compiler,
64 the `procmacro2_semver_exempt` config flag must be passed to rustc. We will
65 polyfill those nightly-only APIs back to Rust 1.68.0. As these are unstable APIs
66 that track the nightly compiler, minor versions of proc-macro2 may make breaking
67 changes to them at any time.
68
69 ```
70 RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
71 ```
72
73 Note that this must not only be done for your crate, but for any crate that
74 depends on your crate. This infectious nature is intentional, as it serves as a
75 reminder that you are outside of the normal semver guarantees.
76
77 Semver exempt methods are marked as such in the proc-macro2 documentation.
78
79 <br>
80
81 #### License
82
83 <sup>
84 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
85 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
86 </sup>
87
88 <br>
89
90 <sub>
91 Unless you explicitly state otherwise, any contribution intentionally submitted
92 for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
93 be dual licensed as above, without any additional terms or conditions.
94 </sub>