Description
This is a tracking issue for the #[builder(getter)]
attribute feature. The stabilization of the design for this attribute requires some more feedback from the community.
If you think the current design is already solid and covers your current or potential future use cases, then just leave a 👍 reaction.
If you'd like to change something about the #[builder(getter)]
attribute syntax and behavior or just extend it, then feel free to leave a comment. We'd be glad to hear your ideas!
Design Vision
Part of the following behaviors are already implemented, but not all.
#[builder(
// For optional members automatically does `Option::as_ref` (reference
// is moved under the Option).
//
// &T | Option<&T>
getter,
// For optional members does no conversion, because `&mut Option<_>` makes
// sense if the caller wants to reset the `Option` to `None`.
//
// &mut T | &mut Option<T>
getter(mut),
// Deref is only supported for readonly getters. One probably doesn't
// need deref for mutable getters, because returning e.g. `&mut String`
// or `&mut Vec<T>` makes perfect sense.
//
// The argument to `deref` specifies the return type of the getter
// (i.e. the target of the deref coercion). However, it can be omitted
// (i.e. just `getter(deref)`) for some well-known types such as:
// - String
// - Vec<T>
// - Box<T>
// - Rc<T>
// - Arc<T>
// - Cow<T>
// - PathBuf
// - OsString
// - CString
// - Utf8PathBuf
// - ...
// Just look up the `Deref` impls in `std` here: https://doc.rust-lang.org/stable/std/ops/trait.Deref.html,
// and in `camino` crate, we may extend this list in the future.
//
// &str | Option<&str>
getter(deref(str)),
// Useful for primitive types (e.g. `u32`)
// Getter by `Copy` -> T | Option<T>
getter(copy),
// Getter by `Clone` -> T | Option<T>
getter(clone),
// Some other standard additional attributes
getter(
name = getter_name,
vis = "",
docs {
/// Docs for getter_name
}
)
// Multiple getters need to have name specified explicitly
getter(name = getter_name_1),
getter(name = getter_name_2, clone),
// Custom readonly getter. Accepts a readonly reference and transforms it.
// Only `&_` type is accepted (_ is replaced with member's type)
getter = |value: &_| -> Ty { expr }
// Custom mutable getter. Accepts a mutable reference and transforms it.
// Only `&mut _` type is accepted (_ is replaced with member's type)
getter = |value: &mut _| -> Ty { expr }
// Give a name to the getter if there are several getters
getter(name = foo, with = |value: &mut _| -> Ty { expr }),
)]
Initial discussion on this attribute: #221
Checklist
- Support getters for
&T
- Support getters for
#[builder(start_fn)]
members - Support getters for
#[builder(field)]
members - Support getters for
self
receiver of methods - Support by-
copy
and by-clone
getters - Support
deref(...)
config - Support
mut
getters - Support custom conversions (
with
closure and shortgetter = closure
syntax) - Support multiple getters
- Don't forget to extend Alternatives table in the docs with this new feature
A note for the community from the maintainers
Please vote on this issue by adding a 👍 reaction to help the maintainers with prioritizing it. You may add a comment describing your real use case related to this issue for us to better understand the problem domain.