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! |
6 | pub use proc_macro2::TokenStream as TokenStream2; |
7 | pub use syn::{parse2, parse_str, DeriveInput}; |
8 | pub 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 | ))] |
14 | pub 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 | ))] |
19 | pub 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 ] |
89 | macro_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 ] |
152 | macro_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 ] |
210 | macro_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!("\ |
246 | test_derive failed: |
247 | expected: |
248 | ``` |
249 | {} |
250 | ``` |
251 | |
252 | got: |
253 | ``` |
254 | {} |
255 | ``` \n" , |
256 | $crate::unpretty_print(&expected_toks), |
257 | $crate::unpretty_print(&res), |
258 | ); |
259 | } |
260 | } |
261 | }; |
262 | } |
263 | |