UseFields
Implement a getter component by reading each method's value from the context field named after the method.
Overview
Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and
UseFields is the provider form of the convention "the method name reads the field name." A
getter component defined with #[cgp_getter] describes one or more
values the context can supply, and the most common arrangement is that each value lives in a
same-named field. The context is the type the method runs on,
which supplies the values it needs as its fields. UseFields is the provider that realizes the
arrangement: wiring a getter to UseFields makes every method read the context field whose name
equals the method name, looked up through HasField keyed by
a Symbol!.
This is the provider analogue of the blanket implementation that
#[cgp_auto_getter] emits. #[cgp_auto_getter] produces a single
blanket implementation that fires automatically for any context whose field names match the method
names, with nothing to wire. UseFields packages the same field-by-method-name behavior as a provider
that a #[cgp_getter] component can be wired to, so a getter that
participates in CGP wiring can still opt into the auto-getter convention when its fields line up with
its methods.
UseFields is distinct from its sibling UseField, and the singular-versus-plural
naming marks the difference. UseField<Tag> keys on a tag the wiring chooses, letting one method
read a field of any name, and it exists only for single-method getters; UseFields takes no
parameter, keys every method on its own name, and works for any number of methods. Reach for
UseField when the field name must differ from the method name, and for UseFields when the
convention holds. Like every CGP provider, UseFields carries no runtime value: it is a marker
named in wiring.
Usage
UseFields is not in the prelude; import it from cgp::core::component. It takes no type parameter
and appears as the value of a getter component's wiring entry:
delegate_components! {
App {
FooGetterComponent: UseFields,
}
}
Every method of the getter reads the context field whose name equals the method name. The context
must have a HasField implementation for each of those names, which
#[derive(HasField)] supplies. The return-type shorthands the
getter macros support apply here too, so a &str return reads a String field and wraps the read
in AsRef::as_ref.
Examples
A getter with two methods, each read from its same-named field, which is the case UseField cannot
serve:
use cgp::core::component::UseFields;
use cgp::prelude::*;
#[cgp_getter]
pub trait HasFooBar {
fn foo(&self) -> &str;
fn bar(&self) -> &u8;
}
#[derive(HasField)]
pub struct App {
pub foo: String,
pub bar: u8,
}
delegate_components! {
App {
FooBarGetterComponent: UseFields,
}
}
check_components! {
App {
FooBarGetterComponent,
}
}
pub fn demo() {
let app = App { foo: "hi".to_owned(), bar: 7 };
assert_eq!(app.foo(), "hi"); // reads the `foo` field
assert_eq!(*app.bar(), 7); // reads the `bar` field
}
Because App wires FooBarGetterComponent to UseFields, each method reads the field whose name
equals its own. App is a value context: the getters read
its own data. If one value were stored under a differently named field, that method would need a
single-method getter of its own, wired to UseField<Symbol!("...")> with the actual
field name.
When to use it
Reach for UseFields when a #[cgp_getter] component's methods each read a same-named field. It is
the wired counterpart of the #[cgp_auto_getter] convention, for the
case where the getter is a full component rather than a blanket impl.
Prefer #[cgp_auto_getter] when the getter does not need to be a
wireable component, and prefer an #[implicit] argument when a
provider needs a value from its own context, which is the common case and needs no getter
trait at all. Reach for UseField<Tag>
instead when the field name must differ from the method name.
Under the hood
#[cgp_getter] generates a UseFields implementation of the getter's
provider trait, reading each method's value from the field whose name matches the method, keyed by a
Symbol!. For the HasFooBar getter above, cargo cgp expand shows this implementation for the
generated FooBarGetter provider trait, with the macro's real placeholder identifiers:
impl<__Context__> FooBarGetter<__Context__> for UseFields
where
__Context__: HasField<Symbol!("foo"), Value = String>,
__Context__: HasField<Symbol!("bar"), Value = u8>,
{
fn foo(__context__: &__Context__) -> &str {
::core::convert::AsRef::as_ref(
HasField::get_field(
__context__,
::core::marker::PhantomData::<Symbol!("foo")>,
),
)
}
fn bar(__context__: &__Context__) -> &u8 {
HasField::get_field(__context__, ::core::marker::PhantomData::<Symbol!("bar")>)
}
}
Each method becomes a HasField bound keyed on the method name as a Symbol!, and the body reads
that field. The &str return makes the field Value a String and wraps the read in
AsRef::as_ref, the same shorthand #[cgp_auto_getter] uses. The
implementation carries one HasField bound and one body per method, each keyed by its own name. The
implementation is paired with a matching IsProviderFor, so
a check reports a missing field precisely.
This is one of three provider implementations #[cgp_getter] generates for a getter component, and
the only one a getter with several methods gets. The other two, UseField for a
wiring-chosen field name and WithProvider for adapting a foundational field
getter, are generated for single-method getters alone. A context picks among them at wiring time.
Related constructs
#[cgp_getter]— the macro that generates this implementation.#[cgp_auto_getter]— the blanket-impl form of the same convention, for a getter that need not be wired.UseField— the sibling that keys on a wiring-chosen tag instead of the method name.WithProvider— the third getter provider#[cgp_getter]emits.HasFieldand#[derive(HasField)]— the field access it reads, keyed bySymbol!on the method name.
The ideas behind it:
- Impl-side dependencies — value injection through a provider's own requirements, of which a getter is one form.
Source
- Struct:
use_fields.rs - The
#[cgp_getter]-generatedUseFieldsimpl:cgp_getter/to_use_fields_impl.rs
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.