1//! This module provides two utility macros for testing custom derives. They can
2//! be used together to eliminate some of the boilerplate required in order to
3//! declare and test custom derive implementations.
4
5// Re-exports used by the decl_derive! and test_derive!
6pub use proc_macro2::TokenStream as TokenStream2;
7pub use syn::{parse2, parse_str, DeriveInput};
8pub use quote::quote;
9
10#[cfg(all(
11 not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))),
12 feature = "proc-macro"
13))]
14pub use proc_macro::TokenStream;
15#[cfg(all(
16 not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))),
17 feature = "proc-macro"
18))]
19pub use syn::parse;
20
21/// The `decl_derive!` macro declares a custom derive wrapper. It will parse the
22/// incoming `TokenStream` into a `synstructure::Structure` object, and pass it
23/// into the inner function.
24///
25/// Your inner function should take a `synstructure::Structure` by value, and
26/// return a type implementing `synstructure::MacroResult`, for example:
27///
28/// ```
29/// fn derive_simple(input: synstructure::Structure) -> proc_macro2::TokenStream {
30/// unimplemented!()
31/// }
32///
33/// fn derive_result(input: synstructure::Structure)
34/// -> syn::Result<proc_macro2::TokenStream>
35/// {
36/// unimplemented!()
37/// }
38/// ```
39///
40/// # Usage
41///
42/// ### Without Attributes
43/// ```
44/// fn derive_interesting(_input: synstructure::Structure) -> proc_macro2::TokenStream {
45/// quote::quote! { ... }
46/// }
47///
48/// # const _IGNORE: &'static str = stringify! {
49/// decl_derive!([Interesting] => derive_interesting);
50/// # };
51/// ```
52///
53/// ### With Attributes
54/// ```
55/// # fn main() {}
56/// fn derive_interesting(_input: synstructure::Structure) -> proc_macro2::TokenStream {
57/// quote::quote! { ... }
58/// }
59///
60/// # const _IGNORE: &'static str = stringify! {
61/// decl_derive!([Interesting, attributes(interesting_ignore)] => derive_interesting);
62/// # };
63/// ```
64///
65/// ### Decl Attributes & Doc Comments
66/// ```
67/// # fn main() {}
68/// fn derive_interesting(_input: synstructure::Structure) -> proc_macro2::TokenStream {
69/// quote::quote! { ... }
70/// }
71///
72/// # const _IGNORE: &'static str = stringify! {
73/// decl_derive! {
74/// [Interesting] =>
75/// #[allow(some_lint)]
76/// /// Documentation Comments
77/// derive_interesting
78/// }
79/// # };
80/// ```
81///
82/// *This macro is available if `synstructure` is built with the `"proc-macro"`
83/// feature.*
84#[cfg(all(
85 not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))),
86 feature = "proc-macro"
87))]
88#[macro_export]
89macro_rules! decl_derive {
90 // XXX: Switch to using this variant everywhere?
91 ([$derives:ident $($derive_t:tt)*] => $(#[$($attrs:tt)*])* $inner:path) => {
92 #[proc_macro_derive($derives $($derive_t)*)]
93 #[allow(non_snake_case)]
94 $(#[$($attrs)*])*
95 pub fn $derives(
96 i: $crate::macros::TokenStream
97 ) -> $crate::macros::TokenStream {
98 match $crate::macros::parse::<$crate::macros::DeriveInput>(i) {
99 ::core::result::Result::Ok(p) => {
100 match $crate::Structure::try_new(&p) {
101 ::core::result::Result::Ok(s) => $crate::MacroResult::into_stream($inner(s)),
102 ::core::result::Result::Err(e) => {
103 ::core::convert::Into::into(e.to_compile_error())
104 }
105 }
106 }
107 ::core::result::Result::Err(e) => {
108 ::core::convert::Into::into(e.to_compile_error())
109 }
110 }
111 }
112 };
113}
114
115/// The `decl_attribute!` macro declares a custom attribute wrapper. It will
116/// parse the incoming `TokenStream` into a `synstructure::Structure` object,
117/// and pass it into the inner function.
118///
119/// Your inner function should have the following type:
120///
121/// ```
122/// fn attribute(
123/// attr: proc_macro2::TokenStream,
124/// structure: synstructure::Structure,
125/// ) -> proc_macro2::TokenStream {
126/// unimplemented!()
127/// }
128/// ```
129///
130/// # Usage
131///
132/// ```
133/// fn attribute_interesting(
134/// _attr: proc_macro2::TokenStream,
135/// _structure: synstructure::Structure,
136/// ) -> proc_macro2::TokenStream {
137/// quote::quote! { ... }
138/// }
139///
140/// # const _IGNORE: &'static str = stringify! {
141/// decl_attribute!([interesting] => attribute_interesting);
142/// # };
143/// ```
144///
145/// *This macro is available if `synstructure` is built with the `"proc-macro"`
146/// feature.*
147#[cfg(all(
148 not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))),
149 feature = "proc-macro"
150))]
151#[macro_export]
152macro_rules! decl_attribute {
153 ([$attribute:ident] => $(#[$($attrs:tt)*])* $inner:path) => {
154 #[proc_macro_attribute]
155 $(#[$($attrs)*])*
156 pub fn $attribute(
157 attr: $crate::macros::TokenStream,
158 i: $crate::macros::TokenStream,
159 ) -> $crate::macros::TokenStream {
160 match $crate::macros::parse::<$crate::macros::DeriveInput>(i) {
161 ::core::result::Result::Ok(p) => match $crate::Structure::try_new(&p) {
162 ::core::result::Result::Ok(s) => {
163 $crate::MacroResult::into_stream(
164 $inner(::core::convert::Into::into(attr), s)
165 )
166 }
167 ::core::result::Result::Err(e) => {
168 ::core::convert::Into::into(e.to_compile_error())
169 }
170 },
171 ::core::result::Result::Err(e) => {
172 ::core::convert::Into::into(e.to_compile_error())
173 }
174 }
175 }
176 };
177}
178
179/// Run a test on a custom derive. This macro expands both the original struct
180/// and the expansion to ensure that they compile correctly, and confirms that
181/// feeding the original struct into the named derive will produce the written
182/// output.
183///
184/// You can add `no_build` to the end of the macro invocation to disable
185/// checking that the written code compiles. This is useful in contexts where
186/// the procedural macro cannot depend on the crate where it is used during
187/// tests.
188///
189/// # Usage
190///
191/// ```
192/// fn test_derive_example(_s: synstructure::Structure)
193/// -> Result<proc_macro2::TokenStream, syn::Error>
194/// {
195/// Ok(quote::quote! { const YOUR_OUTPUT: &'static str = "here"; })
196/// }
197///
198/// fn main() {
199/// synstructure::test_derive!{
200/// test_derive_example {
201/// struct A;
202/// }
203/// expands to {
204/// const YOUR_OUTPUT: &'static str = "here";
205/// }
206/// }
207/// }
208/// ```
209#[macro_export]
210macro_rules! test_derive {
211 ($name:path { $($i:tt)* } expands to { $($o:tt)* }) => {
212 {
213 #[allow(dead_code)]
214 fn ensure_compiles() {
215 $($i)*
216 $($o)*
217 }
218
219 $crate::test_derive!($name { $($i)* } expands to { $($o)* } no_build);
220 }
221 };
222
223 ($name:path { $($i:tt)* } expands to { $($o:tt)* } no_build) => {
224 {
225 let i = $crate::macros::quote!( $($i)* );
226 let parsed = $crate::macros::parse2::<$crate::macros::DeriveInput>(i)
227 .expect(::core::concat!(
228 "Failed to parse input to `#[derive(",
229 ::core::stringify!($name),
230 ")]`",
231 ));
232
233 let raw_res = $name($crate::Structure::new(&parsed));
234 let res = $crate::MacroResult::into_result(raw_res)
235 .expect(::core::concat!(
236 "Procedural macro failed for `#[derive(",
237 ::core::stringify!($name),
238 ")]`",
239 ));
240
241 let expected_toks = $crate::macros::quote!( $($o)* );
242 if <$crate::macros::TokenStream2 as ::std::string::ToString>::to_string(&res)
243 != <$crate::macros::TokenStream2 as ::std::string::ToString>::to_string(&expected_toks)
244 {
245 panic!("\
246test_derive failed:
247expected:
248```
249{}
250```
251
252got:
253```
254{}
255```\n",
256 $crate::unpretty_print(&expected_toks),
257 $crate::unpretty_print(&res),
258 );
259 }
260 }
261 };
262}
263