#[cgp_auto_getter]
Define a getter as a blanket impl over HasField, keyed by the method name.
Overview
In Context-Generic Programming (CGP), #[cgp_auto_getter] publishes a context field as a
named, reusable accessor. You write a trait of getter
methods, and the macro implements it for every context that happens to carry fields of the matching
names. The context is the type the method runs on, and it supplies the values it needs as its
own fields. For example:
#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}
Any struct with a name: String field now implements HasName, and self.name() works. Nothing is
wired and no impl is written: the macro emits one
blanket implementation
covering every qualifying context, keyed on each method's own name.
It hides the field-access trait CGP reads fields through, which is precise and unpleasant to write by
hand: a bound naming the field as a type-level string, and a PhantomData tag at every read. Being
able to state the same thing as fn name(&self) -> &str; is the point.
Use it sparingly. For the ordinary case, a provider reading a field of its own context, an
#[implicit] argument does the same job with no trait to declare, using the
same field access and the same conversion rules, so a getter trait declared only to read a field adds a
name and gives nothing back. A getter trait does give you one thing: an accessor other code can depend on by name.
The cases where that matters are in
When to use it.
Usage
Apply the attribute to a trait definition. It takes no arguments. The body is getter methods, each taking
&self or &mut self and returning a reference:
#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}
A trait may declare several methods, and each maps independently to its own field:
#[cgp_auto_getter]
pub trait HasDimensions {
fn width(&self) -> &f64;
fn height(&self) -> &f64;
}
The method name is the field name. That is the whole convention, and also the construct's one real limitation: a context must expose a field of exactly that name.
How the return type decides the read
The return type controls how the field is read, and several shorthands exist so the signature stays natural. The field's type is inferred from what you return:
| The method returns | The field's type | How it is read |
|---|---|---|
&T | T | by reference, no conversion |
&str | String | .as_ref() |
&[T] | any 'static type implementing AsRef<[T]> | .as_ref() |
Option<&T> | Option<T> | .as_ref() |
Option<&str> | Option<String> | .option_as_ref() |
MRef<'_, T> | T | by reference, wrapped as MRef::Ref(…) |
An owned type (f64, String, a tuple, an array) | the same type | by reference, then .clone() |
A &mut self receiver reads mutably, through HasFieldMut, and each reference form has a mutable
mirror: &mut T, &mut str from a String via .as_mut(), &mut [T] through AsMut<[T]>,
Option<&mut T> via .as_mut(), and Option<&mut str> via .as_deref_mut(). A &mut anywhere
in the return type needs that receiver, and under &self the macro rejects it with
&mut self is required for mutable field reference.
Two combinations fall outside the table. Option<&[T]> and Option<&dyn Trait> have no rule of their
own, and the macro rejects them, since an Option<[T]> field cannot exist. And a shared
Option return under &mut self does not compile, as Common Mistakes records.
The &str row is the one most often wanted and least obvious: the context stores a String and the
getter hands out a borrow of it, so no context ever has to hold a &str. These are the same rules an
#[implicit] argument follows, so learning them once covers everywhere CGP
reads a field. There is one difference worth remembering. A getter takes its mutability from the
receiver, while an implicit argument takes it from the argument's type. So
fn name(&mut self) -> &mut String reads mutably because of the &mut self, whereas
#[implicit] name: &String on a &mut self method still reads through a shared borrow.
Reading a field of another type
The first argument need not be self. A typed reference stands in for it, which is how a getter reaches
a field on something the context only names:
#[cgp_auto_getter]
pub trait HasFooBar: HasFooType + HasBarType {
fn foo_bar(foo: &Self::Foo) -> &Self::Bar;
}
The generated bound now falls on Self::Foo rather than on the context, and the method is called as an
associated function: App::foo_bar(&foo). The macro rewrites Self inside the argument and return
types to the context, and & versus &mut decides the access mode exactly as a receiver would.
This is the one getter shape an #[implicit] argument cannot reach,
because there is no self field to read. This makes it the clearest case for declaring a getter at
all.
An optional PhantomData argument
A getter method may take one further argument, and it must be a PhantomData:
#[cgp_auto_getter]
pub trait HasFoo {
fn foo(&self, _tag: PhantomData<Foo>) -> &Foo;
}
It is forwarded to the generated method untouched and plays no part in the field lookup; it is there so a
getter can carry a type-level argument in its signature. Anything else in that position is rejected with
only PhantomData is allowed as second argument, and a third argument with
getter method must contain exactly one &self argument.
A type inferred from the field
A getter may declare a single associated type and return it, which keeps the type abstract for callers while letting the context's field decide it:
#[cgp_auto_getter]
pub trait HasName {
type Name: Display;
fn name(&self) -> &Self::Name;
}
The bound is enforced on whatever the field holds. When an associated type is present the trait must
contain exactly one getter method, whose return type reads that type, most often as
&Self::AssocType. There is only one field for the type to be inferred from. A second associated
type, a generic associated type, a second method, or a return type that reads some other type is
rejected.
Companion attributes and trait generics
The macro runs the attribute collector of #[cgp_component], so
#[extend(...)] and #[use_type(...)]
apply. Each becomes a bound on the context in the blanket impl, alongside any supertrait written
natively, and #[use_type] rewrites a bare abstract type in the signatures:
#[cgp_auto_getter]
#[use_type(HasScalarType.Scalar)]
pub trait HasSide {
fn side(&self) -> &Scalar;
}
A trait may also carry generic parameters, which stay on the blanket impl and flow into the field
bound, so trait HasValue<T> { fn value(&self) -> &T; } reads a value field of any type.
Methods the macro rejects
A getter method is a plain signature, and the macro rejects anything more with a message naming the
problem: a const, async, or unsafe method, a method with generic parameters or a where
clause, a method without a return type, and a by-value self receiver. So is any trait item other
than a method or the one associated type.
Examples
A getter trait and a context that satisfies it by having the right field:
use cgp::prelude::*;
#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}
#[derive(HasField)]
pub struct Person {
pub name: String,
}
pub fn greet(person: &Person) {
println!("Hello, {}!", person.name());
}
Person derives HasField, which is its entire qualification. The
blanket impl applies automatically, with no wiring anywhere in the program.
The reason to declare the trait at all is that other code can now require it. A provider states the dependency by name and never mentions a field:
#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self);
}
#[cgp_impl(new GreetHello)]
#[uses(HasName)]
impl Greeter {
fn greet(&self) {
println!("Hello, {}!", self.name());
}
}
Any context with a name field satisfies HasName and therefore satisfies GreetHello. A context that
stores the name elsewhere can implement the trait by hand instead, which the blanket impl does not
prevent:
pub struct Employee {
pub full_name: String,
}
impl HasName for Employee {
fn name(&self) -> &str {
&self.full_name
}
}
That hand-written impl is worth seeing, because it shows the trait is an ordinary Rust trait. The macro's only job was to save you writing the body.
When to use it
Prefer an #[implicit] argument, and use a getter trait only when one
cannot do the job. An implicit argument reads a field of the provider's own context as an ordinary
parameter, with no trait, no declaration, and the same access rules, so it covers the common read
directly, including a field several providers each consume, declared as the same implicit argument in
each.
A getter trait is worth declaring in a few cases an implicit argument cannot reach.
- The field lives on another type. An implicit argument reads only from
self, so a value held by a request, a payload, or any other type needs a getter that can be demanded as a bound on that type, as inRequest: HasBasicAuthHeader<Self>. There is noselffield to read. - The accessor must be a named trait. When other code depends on "this context can tell you its
name" rather than on a field, that dependency needs a trait to point at, importable with
#[uses]or usable as a supertrait via#[extend]. - The getter carries a type inferred from the field. The associated-type form above keeps the type abstract for callers in a way a concrete implicit parameter cannot.
Between the two getter macros the line is narrow and worth stating plainly.
#[cgp_auto_getter]is the default getter. One blanket impl, no wiring, field name fixed to the method name.#[cgp_getter]is the advanced one, and not a general upgrade. Use it only when a context needs to choose which field the getter reads, as a different name per context, or an implementation selected by wiring. That control costs a line of wiring per context, and most getters do not want it.
So the ordering is: implicit argument by default, #[cgp_auto_getter] for the cases above, and
#[cgp_getter] only for per-context field choice.
Under the hood
The macro re-emits the trait unchanged and adds one blanket impl over a generic context. From this input:
#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}
it produces the trait verbatim plus:
impl<__Context__> HasName for __Context__
where
__Context__: HasField<Symbol!("name"), Value = String>,
{
fn name(&self) -> &str {
self.get_field(PhantomData::<Symbol!("name")>).as_ref()
}
}
A few things to recognize. The context parameter is literally __Context__, a reserved name chosen so it
cannot collide with one of yours. Symbol!("name") is a type-level string standing for the
field name. The compiler prints its expanded Symbol<4, Chars<'n', …>> form in errors, and
cargo cgp expand resugars it back to this. And because the return type is &str, the bound asks for a
String field and the body appends .as_ref(), which is the conversion table in action.
A trait with several methods produces one predicate and one body per field, all in the same impl:
impl<__Context__> HasDimensions for __Context__
where
__Context__: HasField<Symbol!("width"), Value = f64>,
__Context__: HasField<Symbol!("height"), Value = f64>,
{
fn width(&self) -> &f64 {
self.get_field(PhantomData::<Symbol!("width")>)
}
fn height(&self) -> &f64 {
self.get_field(PhantomData::<Symbol!("height")>)
}
}
The associated-type form lifts the type into an extra generic parameter on the impl and binds it through the field's value, which lets the field decide it:
impl<__Context__, Name> HasName for __Context__
where
Name: Display,
__Context__: HasField<Symbol!("name"), Value = Name>,
{
type Name = Name;
fn name(&self) -> &Self::Name {
self.get_field(PhantomData::<Symbol!("name")>)
}
}
The declared bound moves onto that parameter, so Display is required of whatever the field holds. Note
that the field tag still comes from the method name rather than from the associated type's.
Common Mistakes
The field name is fixed to the method name. A context storing the value under any other name does not satisfy the trait, and because the failure is an unmet bound on a blanket impl the method reads as missing rather than the field:
error[E0599]: the method `name` exists for reference `&Person`, but its trait bounds were not satisfied
Either rename the field, implement the trait by hand, or use #[cgp_getter], which
exists precisely to decouple the two.
An associated type forces a single method, since the type is inferred from one field and two getters give it nothing to choose between:
error: if associated type is defined, exactly one getter method must be defined
The macro takes no arguments. Unlike its sibling #[cgp_getter] there is no
provider trait to name, because no component is generated, and an argument is rejected rather than
ignored:
error: #[cgp_auto_getter] does not accept any attribute argument
The trait still has to be in scope to call its method. That is ordinary Rust, but it surprises readers
here, because nothing else about the getter had to be declared. A missing use reports the method as not
found rather than the trait as not imported.
A &mut self getter cannot return a shared Option. The macro picks the conversion from the
receiver, so fn maybe(&mut self) -> Option<&u32> reads with .as_mut(), produces an
Option<&mut u32>, and fails, because that type does not coerce to Option<&u32>:
error[E0308]: mismatched types
The plain reference, &str, slice, and MRef forms are unaffected, because a &mut result
coerces to the shared one. Return Option<&mut T> from a &mut self getter, or take &self.
Option<&[T]> is not a supported return type, and neither is Option<&dyn Trait>. The macro rejects
them, since the field they would read cannot exist, and names the container to read with the type you
wrote, here for Option<&[u8]>:
error: `Option<&[u8]>` would read an `Option<[u8]>` field, which cannot exist because a slice is unsized; read an `Option<Vec<u8>>` field as `Option<&Vec>` instead
A type named by a path, such as Option<&Path>, has a size only the compiler knows, so it still reaches
the compiler, as an E0277 on the attribute naming [u8].
From an Option<Vec<T>> field, return Option<&Vec, or return &Option and convert
at the call site.
#[prefix] and #[derive_delegate] are accepted and dropped. The macro runs the attribute
collector of #[cgp_component] so that #[extend] and #[use_type] apply, but
it does not generate a component, so those two attributes register nothing and report nothing. A getter that
must live in a namespace, or dispatch per type, is a #[cgp_getter] component.
Related constructs
#[implicit]— the default way to read a field, and the form to prefer.#[cgp_getter]— the wireable counterpart, for per-context field choice.#[derive(HasField)]— what a context derives to qualify.HasField— the trait the generated bound is written against.Symbol!— the type-level field name the bound is keyed on.#[uses]— how a provider depends on a getter by name.#[cgp_type]— for an abstract type standing on its own rather than inferred from a field.
The ideas behind it:
- Implicit arguments — the lighter way to read a field, and why a getter is the exception.
- Impl-side dependencies — why the field requirement stays off the trait interface.
Source
- Entry point:
cgp_auto_getter.rs - Implementation:
types/cgp_auto_getter/ - Getter parsing and the return-type shorthands:
functions/getter/parse.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.