getset/lib.rs
1/*!
2Getset, we're ready to go!
3
4A procedural macro for generating the most basic getters and setters on fields.
5
6Getters are generated as `fn field(&self) -> &type`, while setters are generated as `fn field(&mut self, val: type)`.
7
8These macros are not intended to be used on fields which require custom logic inside of their setters and getters. Just write your own in that case!
9
10```rust
11use std::sync::Arc;
12
13use getset::{CloneGetters, CopyGetters, Getters, MutGetters, Setters, WithSetters};
14
15#[derive(Getters, Setters, WithSetters, MutGetters, CopyGetters, CloneGetters, Default)]
16pub struct Foo<T>
17where
18 T: Copy + Clone + Default,
19{
20 /// Doc comments are supported!
21 /// Multiline, even.
22 #[getset(get, set, get_mut, set_with)]
23 private: T,
24
25 /// Doc comments are supported!
26 /// Multiline, even.
27 #[getset(get_copy = "pub", set = "pub", get_mut = "pub", set_with = "pub")]
28 public: T,
29
30 /// Arc supported through CloneGetters
31 #[getset(get_clone = "pub", set = "pub", get_mut = "pub", set_with = "pub")]
32 arc: Arc<u16>,
33}
34```
35
36You can use `cargo-expand` to generate the output. Here are the functions that the above generates (Replicate with `cargo expand --example simple`):
37
38```rust,ignore
39use std::sync::Arc;
40use getset::{CloneGetters, CopyGetters, Getters, MutGetters, Setters, WithSetters};
41pub struct Foo<T>
42where
43 T: Copy + Clone + Default,
44{
45 /// Doc comments are supported!
46 /// Multiline, even.
47 #[getset(get, set, get_mut, set_with)]
48 private: T,
49 /// Doc comments are supported!
50 /// Multiline, even.
51 #[getset(get_copy = "pub", set = "pub", get_mut = "pub", set_with = "pub")]
52 public: T,
53 /// Arc supported through CloneGetters
54 #[getset(get_clone = "pub", set = "pub", get_mut = "pub", set_with = "pub")]
55 arc: Arc<u16>,
56}
57impl<T> Foo<T>
58where
59 T: Copy + Clone + Default,
60{
61 /// Doc comments are supported!
62 /// Multiline, even.
63 #[inline(always)]
64 fn private(&self) -> &T {
65 &self.private
66 }
67}
68impl<T> Foo<T>
69where
70 T: Copy + Clone + Default,
71{
72 /// Doc comments are supported!
73 /// Multiline, even.
74 #[inline(always)]
75 fn set_private(&mut self, val: T) -> &mut Self {
76 self.private = val;
77 self
78 }
79 /// Doc comments are supported!
80 /// Multiline, even.
81 #[inline(always)]
82 pub fn set_public(&mut self, val: T) -> &mut Self {
83 self.public = val;
84 self
85 }
86 /// Arc supported through CloneGetters
87 #[inline(always)]
88 pub fn set_arc(&mut self, val: Arc<u16>) -> &mut Self {
89 self.arc = val;
90 self
91 }
92}
93impl<T> Foo<T>
94where
95 T: Copy + Clone + Default,
96{
97 /// Doc comments are supported!
98 /// Multiline, even.
99 #[inline(always)]
100 fn with_private(mut self, val: T) -> Self {
101 self.private = val;
102 self
103 }
104 /// Doc comments are supported!
105 /// Multiline, even.
106 #[inline(always)]
107 pub fn with_public(mut self, val: T) -> Self {
108 self.public = val;
109 self
110 }
111 /// Arc supported through CloneGetters
112 #[inline(always)]
113 pub fn with_arc(mut self, val: Arc<u16>) -> Self {
114 self.arc = val;
115 self
116 }
117}
118impl<T> Foo<T>
119where
120 T: Copy + Clone + Default,
121{
122 /// Doc comments are supported!
123 /// Multiline, even.
124 #[inline(always)]
125 fn private_mut(&mut self) -> &mut T {
126 &mut self.private
127 }
128 /// Doc comments are supported!
129 /// Multiline, even.
130 #[inline(always)]
131 pub fn public_mut(&mut self) -> &mut T {
132 &mut self.public
133 }
134 /// Arc supported through CloneGetters
135 #[inline(always)]
136 pub fn arc_mut(&mut self) -> &mut Arc<u16> {
137 &mut self.arc
138 }
139}
140impl<T> Foo<T>
141where
142 T: Copy + Clone + Default,
143{
144 /// Doc comments are supported!
145 /// Multiline, even.
146 #[inline(always)]
147 pub fn public(&self) -> T {
148 self.public
149 }
150}
151impl<T> Foo<T>
152where
153 T: Copy + Clone + Default,
154{
155 /// Arc supported through CloneGetters
156 #[inline(always)]
157 pub fn arc(&self) -> Arc<u16> {
158 self.arc.clone()
159 }
160}
161```
162
163Attributes can be set on struct level for all fields in struct as well. Field level attributes take
164precedence.
165
166```rust
167mod submodule {
168 use getset::{Getters, MutGetters, CopyGetters, Setters, WithSetters};
169 #[derive(Getters, CopyGetters, Default)]
170 #[getset(get_copy = "pub")] // By default add a pub getting for all fields.
171 pub struct Foo {
172 public: i32,
173 #[getset(get_copy)] // Override as private
174 private: i32,
175 }
176 fn demo() {
177 let mut foo = Foo::default();
178 foo.private();
179 }
180}
181
182let mut foo = submodule::Foo::default();
183foo.public();
184```
185
186For some purposes, it's useful to have the `get_` prefix on the getters for
187either legacy of compatibility reasons. It is done with `with_prefix`.
188
189```rust
190use getset::{Getters, MutGetters, CopyGetters, Setters, WithSetters};
191
192#[derive(Getters, Default)]
193pub struct Foo {
194 #[getset(get = "pub with_prefix")]
195 field: bool,
196}
197
198
199let mut foo = Foo::default();
200let val = foo.get_field();
201```
202
203Skipping setters and getters generation for a field when struct level attribute is used
204is possible with `#[getset(skip)]`.
205
206```rust
207use getset::{CopyGetters, Setters, WithSetters};
208
209#[derive(CopyGetters, Setters, WithSetters)]
210#[getset(get_copy, set, set_with)]
211pub struct Foo {
212 // If the field was not skipped, the compiler would complain about moving
213 // a non-copyable type in copy getter.
214 #[getset(skip)]
215 skipped: String,
216
217 field1: usize,
218 field2: usize,
219}
220
221impl Foo {
222 // It is possible to write getters and setters manually,
223 // possibly with a custom logic.
224 fn skipped(&self) -> &str {
225 &self.skipped
226 }
227
228 fn set_skipped(&mut self, val: &str) -> &mut Self {
229 self.skipped = val.to_string();
230 self
231 }
232
233 fn with_skipped(mut self, val: &str) -> Self {
234 self.skipped = val.to_string();
235 self
236 }
237}
238```
239
240For a unary struct (a tuple struct with a single field),
241the macro generates the `get`, `get_mut`, and `set` functions to
242provide a getter, a mutable getter, and a setter, respectively.
243
244```rust
245use getset::{Getters, MutGetters, CopyGetters, Setters};
246
247#[derive(Setters, Getters, MutGetters)]
248struct UnaryTuple(#[getset(set, get, get_mut)] i32);
249
250let mut tup = UnaryTuple(42);
251assert_eq!(tup.get(), &42);
252assert_eq!(tup.get_mut(), &mut 42);
253tup.set(43);
254assert_eq!(tup.get(), &43);
255
256#[derive(CopyGetters)]
257struct CopyUnaryTuple(#[getset(get_copy)] i32);
258
259let tup = CopyUnaryTuple(42);
260```
261*/
262
263#[macro_use]
264extern crate quote;
265
266use std::{cell::RefCell, panic::UnwindSafe};
267
268use proc_macro::TokenStream;
269use proc_macro2::TokenStream as TokenStream2;
270use syn::{parse_macro_input, spanned::Spanned, DataStruct, DeriveInput, Meta};
271
272use crate::generate::{GenMode, GenParams};
273
274#[macro_use]
275mod macros;
276mod generate;
277
278// Temporary workaround for deprecation of proc-macro-error2. This will be fixed once
279// Diagnostic is stabilized upstream.
280thread_local! {
281 static ERROR_REPORTING: RefCell<Option<TokenStream2>> = const { RefCell::new(None) };
282}
283
284fn wrap_panic<F>(input: TokenStream, f: F) -> TokenStream
285where
286 F: UnwindSafe + Fn(TokenStream) -> TokenStream,
287{
288 match std::panic::catch_unwind(move || f(input)) {
289 Ok(ts) => ts,
290 Err(_) => ERROR_REPORTING.with(|o| match o.borrow_mut().take() {
291 Some(ts) => ts.clone().into(),
292 None => quote!(compile_error!("No info set for panic")).into(),
293 }),
294 }
295}
296
297#[proc_macro_derive(Getters, attributes(get, with_prefix, getset))]
298pub fn getters(input: TokenStream) -> TokenStream {
299 wrap_panic(input, getters_impl)
300}
301
302fn getters_impl(input: TokenStream) -> TokenStream {
303 let ast = parse_macro_input!(input as DeriveInput);
304 let params = GenParams {
305 mode: GenMode::Get,
306 global_attr: parse_global_attr(&ast.attrs, GenMode::Get),
307 };
308
309 produce(&ast, ¶ms).into()
310}
311
312#[proc_macro_derive(CloneGetters, attributes(get_clone, with_prefix, getset))]
313pub fn clone_getters(input: TokenStream) -> TokenStream {
314 wrap_panic(input, clone_getters_impl)
315}
316
317fn clone_getters_impl(input: TokenStream) -> TokenStream {
318 let ast = parse_macro_input!(input as DeriveInput);
319 let params = GenParams {
320 mode: GenMode::GetClone,
321 global_attr: parse_global_attr(&ast.attrs, GenMode::GetClone),
322 };
323
324 produce(&ast, ¶ms).into()
325}
326
327#[proc_macro_derive(CopyGetters, attributes(get_copy, with_prefix, getset))]
328pub fn copy_getters(input: TokenStream) -> TokenStream {
329 wrap_panic(input, copy_getters_impl)
330}
331
332fn copy_getters_impl(input: TokenStream) -> TokenStream {
333 let ast = parse_macro_input!(input as DeriveInput);
334 let params = GenParams {
335 mode: GenMode::GetCopy,
336 global_attr: parse_global_attr(&ast.attrs, GenMode::GetCopy),
337 };
338
339 produce(&ast, ¶ms).into()
340}
341
342#[proc_macro_derive(MutGetters, attributes(get_mut, getset))]
343pub fn mut_getters(input: TokenStream) -> TokenStream {
344 wrap_panic(input, mut_getters_impl)
345}
346
347fn mut_getters_impl(input: TokenStream) -> TokenStream {
348 let ast = parse_macro_input!(input as DeriveInput);
349 let params = GenParams {
350 mode: GenMode::GetMut,
351 global_attr: parse_global_attr(&ast.attrs, GenMode::GetMut),
352 };
353
354 produce(&ast, ¶ms).into()
355}
356
357#[proc_macro_derive(Setters, attributes(set, getset))]
358pub fn setters(input: TokenStream) -> TokenStream {
359 wrap_panic(input, setters_impl)
360}
361
362fn setters_impl(input: TokenStream) -> TokenStream {
363 let ast = parse_macro_input!(input as DeriveInput);
364 let params = GenParams {
365 mode: GenMode::Set,
366 global_attr: parse_global_attr(&ast.attrs, GenMode::Set),
367 };
368
369 produce(&ast, ¶ms).into()
370}
371
372#[proc_macro_derive(WithSetters, attributes(set_with, getset))]
373pub fn with_setters(input: TokenStream) -> TokenStream {
374 wrap_panic(input, with_setters_impl)
375}
376
377fn with_setters_impl(input: TokenStream) -> TokenStream {
378 let ast = parse_macro_input!(input as DeriveInput);
379 let params = GenParams {
380 mode: GenMode::SetWith,
381 global_attr: parse_global_attr(&ast.attrs, GenMode::SetWith),
382 };
383
384 produce(&ast, ¶ms).into()
385}
386
387fn parse_global_attr(attrs: &[syn::Attribute], mode: GenMode) -> Option<Meta> {
388 attrs.iter().filter_map(|v| parse_attr(v, mode)).next_back()
389}
390
391fn parse_attr(attr: &syn::Attribute, mode: GenMode) -> Option<syn::Meta> {
392 use syn::{punctuated::Punctuated, Token};
393
394 if attr.path().is_ident("getset") {
395 let meta_list =
396 match attr.parse_args_with(Punctuated::<syn::Meta, Token![,]>::parse_terminated) {
397 Ok(list) => list,
398 Err(e) => abort!(attr.span(), "Failed to parse getset attribute: {}", e),
399 };
400
401 let (last, skip, mut collected) = meta_list
402 .into_iter()
403 .inspect(|meta| {
404 if !(meta.path().is_ident("get")
405 || meta.path().is_ident("get_clone")
406 || meta.path().is_ident("get_copy")
407 || meta.path().is_ident("get_mut")
408 || meta.path().is_ident("set")
409 || meta.path().is_ident("set_with")
410 || meta.path().is_ident("skip"))
411 {
412 abort!(meta.path().span(), "unknown setter or getter")
413 }
414 })
415 .fold(
416 (None, None, Vec::new()),
417 |(last, skip, mut collected), meta| {
418 if meta.path().is_ident(mode.name()) {
419 (Some(meta), skip, collected)
420 } else if meta.path().is_ident("skip") {
421 (last, Some(meta), collected)
422 } else {
423 collected.push(meta);
424 (last, skip, collected)
425 }
426 },
427 );
428
429 if skip.is_some() {
430 // Check if there is any setter or getter used with skip, which is
431 // forbidden.
432 if last.is_none() && collected.is_empty() {
433 skip
434 } else {
435 abort!(
436 last.or_else(|| collected.pop()).unwrap().path().span(),
437 "use of setters and getters with skip is invalid"
438 );
439 }
440 } else {
441 last
442 }
443 } else if attr.path().is_ident(mode.name()) {
444 // If skip is not used, return the last occurrence of matching
445 // setter/getter, if there is any.
446 attr.meta.clone().into()
447 } else {
448 None
449 }
450}
451
452fn produce(ast: &DeriveInput, params: &GenParams) -> TokenStream2 {
453 let name = &ast.ident;
454 let generics = &ast.generics;
455 let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
456
457 // Is it a struct?
458 if let syn::Data::Struct(DataStruct { ref fields, .. }) = ast.data {
459 // Handle unary struct
460 if matches!(fields, syn::Fields::Unnamed(_)) {
461 if fields.len() != 1 {
462 abort_call_site!("Only support unary struct!");
463 }
464 // This unwrap is safe because we know there is exactly one field
465 let field = fields.iter().next().unwrap();
466 let generated = generate::implement_for_unnamed(field, params);
467
468 quote! {
469 impl #impl_generics #name #ty_generics #where_clause {
470 #generated
471 }
472 }
473 } else {
474 let generated = fields.iter().map(|f| generate::implement(f, params));
475
476 quote! {
477 impl #impl_generics #name #ty_generics #where_clause {
478 #(#generated)*
479 }
480 }
481 }
482 } else {
483 // Nope. This is an Enum. We cannot handle these!
484 abort_call_site!("#[derive(Getters)] is only defined for structs, not for enums!");
485 }
486}