Skip to main content

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.

The ideas behind it:

  • Impl-side dependencies — value injection through a provider's own requirements, of which a getter is one form.

Source​


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.