Skip to main content

Implicit arguments

Context-Generic Programming (CGP) extends Rust with pluggable trait implementations whose providers read context values as if they were parameters. Implicit arguments name the context value a method needs, and CGP reads it from the context, so callers pass only the method's explicit arguments. This page explains the field access behind that shorthand, how argument types control borrowing and cloning, and when a getter trait is a better fit.

Reading a field explicitly​

A generic provider reads a context field through HasField, a trait keyed by the field's name. The following fragment assumes a Greeter component with a greet(&self) -> String method, with cgp::prelude::* and HasField from cgp::core::field::traits imported:

#[cgp_impl(new GreetByName)]
impl Greeter
where
Self: HasField<Symbol!("name"), Value = String>,
{
fn greet(&self) -> String {
let name = self.get_field(PhantomData::<Symbol!("name")>);
format!("Hello, {name}!")
}
}

HasField<Symbol!("name"), Value = String> requires the context to expose a String field named name. Symbol!("name") represents the name as a type, and PhantomData supplies that type to get_field so Rust can select the field. The bound is an impl-side dependency: it constrains this provider without adding a field requirement to the consumer trait.

The explicit form states the requirement and the read separately. When a provider only needs the value locally, an implicit argument can express both at once.

The same provider with an implicit argument​

An implicit argument names a field and declares the type the method body needs:

#[cgp_impl(new GreetByName)]
impl Greeter {
fn greet(&self, #[implicit] name: &str) -> String {
format!("Hello, {name}!")
}
}

#[implicit] removes name from the method's public signature and generates the field bound and read. The body receives a local name, while a caller still writes app.greet(). Here, &str borrows the contents of any field that implements AsRef<str>, such as a String field.

Implicit arguments are the usual choice for reading fields from a provider's own context. They keep each value's name and type beside the method that uses it, while the macro supplies the HasField bound and tagged access.

A trait from a function alone​

#[cgp_fn] combines implicit arguments with a single blanket implementation, so the operation needs neither a named provider nor wiring:

#[cgp_fn]
pub fn rectangle_area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}

The macro generates a RectangleArea trait and implements it for contexts exposing width and height through HasField, both with type f64. A struct can supply those implementations by carrying the matching fields and deriving HasField. Its values can then call rectangle_area().

This form suits an operation with one shared implementation. A component becomes useful when contexts need to select among alternative implementations of the same operation.

The declared type decides how the field is read​

The argument type determines whether the body receives an owned value or a borrow. These common forms follow the same access rules as CGP's automatic getters:

#[cgp_fn]
pub fn describe(
&self,
// Cloned from the context's String field.
#[implicit] name: String,
// Borrows any field implementing `AsRef<str>`, such as a String field.
#[implicit] title: &str,
// Borrows the Vec field directly.
#[implicit] tags: &Vec<String>,
) -> String {
format!("{title} {name} {tags:?}")
}

An owned argument calls .clone() on the field, leaving the stored value in the context. A &str argument reads any field implementing AsRef<str> with .as_ref(), and &Vec borrows the vector directly. Prefer a borrow when the body only needs to read the value, especially when cloning would allocate or copy substantial data.

The macro supports specific access forms rather than arbitrary conversions between types. The #[implicit] reference covers options, slices, mutable access, and the other supported forms.

When a getter trait is useful​

A getter trait is useful when field access must be expressed as a named interface. Implicit arguments read from the provider's own self, so they cannot directly read a field from a separate argument. For example, this provider requires a getter on Request:

#[cgp_impl(new AuthenticateByHeader)]
impl<Request> RequestAuthenticator<Request>
where
Request: HasAuthHeader,
{
fn authenticate(&self, request: &Request) -> bool {
request.auth_header().starts_with("Bearer ")
}
}

This fragment assumes RequestAuthenticator and HasAuthHeader are defined elsewhere. HasAuthHeader describes access on the request, while self is the application context. An implicit argument on authenticate would read the application instead.

A named getter also lets other code require the accessor through a trait bound or supertrait. A getter with an associated type can keep the field's type abstract for callers. These are reasons to use #[cgp_auto_getter]; sharing a context field between several providers alone is not. Each provider can declare the same implicit argument.

A wireable getter supports a further choice: which field supplies the value in each context. Use #[cgp_getter] when that mapping must vary, rather than fixing the field name in the implicit argument.

What it costs​

Field names become dependencies of providers. Renaming name breaks providers whose implicit argument requires that name, and the error appears where Rust checks the provider's requirements. The struct definition does not list the providers that depend on its fields.

The call site omits those field requirements. app.greet() does not show that GreetByName needs name; you find that requirement in the selected provider. Rust checks the name and type, but it cannot tell whether two fields with the same name and type have the same intended meaning.

Owned arguments incur the cost of cloning on each call. For a small scalar this is a copy; for a String or a large collection it may allocate and copy data. Declare a borrow when ownership is unnecessary.

Where to go next​

These pages connect implicit arguments to the rest of CGP:


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.