`#[builder(getter)]` full batteries mode

Start with the initial discussion in issue #221 and review the design vision and unchecked checklist items in this issue. Determine the intended behavior for the remaining getter forms, including start_fn and field members, mutable getters, custom conversions, and multiple getters. Done means the agreed design is implemented and the Alternatives table in the documentation is updated.

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: https://github.com/elastio/bon/issues/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 short getter = 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.