cgp v0.4.0
Version 0.4.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, makes an unmet dependency show up in compiler errors, and adds presets, contexts, and datatype-generic traits. This page lists every change a user can see and the steps that take a project there from v0.3.1.
Released on 2025-05-09.
- Release post: CGP v0.4.0 Release: Unlocking Easier Debugging, Extensible Presets, and More
- Crate:
cgp0.4.0 on crates.io - Changes: v0.3.1...v0.4.0
Summary
IsProviderFor, CanUseComponent, check_components!, and delegate_and_check_components! put a missing dependency into the compiler's error, at the price of an attribute on every provider impl. cgp_preset! groups wirings and inherits other presets, #[cgp_context] declares a context's provider, and #[derive(HasFields)] exposes a type's fields as a type-level list. The getter macros read more kinds of field, and a getter trait may be generic. The release also renames HasComponents, replaces the macro crates with cgp-macro, and lowers the minimum Rust version to 1.81.
Compatibility
- Minimum Rust version: 1.81, down from 1.84 (#62).
- Released together: the workspace's 19 crates published on crates.io, all at 0.4.0.
- New crates:
cgp-macroandcgp-macro-lib, which replacecgp-component-macro,cgp-component-macro-lib,cgp-field-macro, andcgp-field-macro-lib; those four have no 0.4.0 version. See the macro crates. - Features: the
staticfeature ofcgp-asyncstays declared but gates nothing, becauseMaybeStaticis removed; see theAsyncbound.
Upgrading
A project moving from v0.3.1 takes these steps, in this order:
- Change the version to
cgp = "0.4.0". Rust 1.81 or newer builds it. - Annotate each provider impl with
#[cgp_provider]or#[cgp_new_provider], per the provider attribute. - Rename
HasComponentstoHasCgpProviderand itsComponentstype toCgpProvider, per the rename. - Replace each
cgp_type!with a#[cgp_type]trait and rename the generated provider traits and component keys, per the attribute. - Add
'staticwhere code relied onAsyncimplying it, per theAsyncbound. - Write symbols with
symbol!, per the symbol type. - Rename the items of each preset, per the preset module.
- Delete a hand-written
UseContextimpl of a component, per the generated impl. - Remove each
for_each_replace!, per the removal. - Import macros from
cgp::preludeorcgp-macro, per the macro crates. - Make the error
Asyncin a context that implementsCanRun, per theCanRunbound.
Breaking changes
Provider impls need #[cgp_provider]
Every provider trait has the supertrait IsProviderFor<Component, Context, Params> (#63, #73), which an impl of the provider trait must satisfy. #[cgp_provider] writes that impl under the provider's own bounds.
- Old:
impl<Context> Greeter<Context> for GreetHello { … }, with no attribute. - New:
#[cgp_provider]above the impl, which names the component as the provider trait's name followed byComponent, or#[cgp_provider(GreeterComponent)]to name it.#[cgp_new_provider]also declares the provider struct from the impl's self type (#67). - What to do: add the attribute to each provider impl, including impls of
ProvideType,ErrorRaiser, and the other provider traits. Without it, the build fails with the unsatisfied boundGreetHello: IsProviderFor<GreeterComponent, Context>.
HasComponents is renamed HasCgpProvider
The consumer trait's blanket impl reads the context's provider from HasCgpProvider, whose associated type is CgpProvider (#69, #97).
- Old:
impl HasComponents for App { type Components = AppComponents; }. - New:
impl HasCgpProvider for App { type CgpProvider = AppComponents; }, which#[cgp_context]writes. - What to do: rename the trait and its associated type, or replace the impl with
#[cgp_context]. The prelude exportsHasCgpProvider.
cgp_type! becomes the #[cgp_type] attribute
#[cgp_type] goes on a trait that declares one associated type (#68). The provider trait is named after the associated type, as {Type}TypeProvider, and the component after the provider trait.
- Old:
cgp_type! { Error: Debug }generatedHasErrorType,ProvideErrorType,ErrorTypeComponent, and the aliasErrorOf. - New:
#[cgp_type] pub trait HasErrorType { type Error: Debug; }generates the same trait and alias, the provider traitErrorTypeProvider, and the componentErrorTypeProviderComponent. - What to do: replace each
cgp_type!call with the trait and the attribute, and rename each use of a generated name.
| Crate | Old | New |
|---|---|---|
cgp-error | ProvideErrorType | ErrorTypeProvider |
cgp-error | ErrorTypeComponent | ErrorTypeProviderComponent |
cgp-runtime | ProvideRuntimeType | RuntimeTypeProvider |
cgp-runtime | RuntimeTypeComponent | RuntimeTypeProviderComponent |
Async no longer requires 'static
Async is MaybeSend + MaybeSync, and the trait MaybeStatic is removed (#89). An abstract type bounded by Async can now be a type that borrows.
- Old: with the default features,
AsyncmeantSend + Sync + 'static, and the prelude exportedMaybeStatic. - New:
AsyncmeansSend + Sync, andMaybeStaticdoes not exist. - What to do: add
'staticto each bound that needs it, such as a context passed totokio::spawn, and delete imports ofMaybeStatic.
symbol! builds a chain of Char types
Char<const CHAR: char, Tail> carries the rest of the string as its second parameter, so symbol!("name") expands to one nested type (#85).
- Old:
Cons<Char<'n'>, Cons<Char<'a'>, Cons<Char<'m'>, Cons<Char<'e'>, Nil>>>>. - New:
Char<'n', Char<'a', Char<'m', Char<'e', Nil>>>>. - What to do: write a field's key with
symbol!. Code that spelled out the old expansion, or namedCharwith one parameter, changes it. TheHasFieldimpls that#[derive(HasField)]generates use the new key.
cgp_preset! expands to a module
cgp_preset! declares a module named after the preset, in place of a struct (#72, #91). The module holds the provider struct Provider and a hidden trait IsPreset, and the trait DelegatesToMyPreset is no longer generated.
- Old:
cgp_preset! { MyPreset { … } }declared the structMyPresetand the traitIsMyPreset, and a table wired[…]: MyPreset. - New:
MyPreset::Providerreplaces the struct andMyPreset::IsPresetreplaces the trait, so a table wires[…]: MyPreset::Provider. - What to do: rename each use of the preset's struct and trait.
#[cgp_component] implements the provider trait for UseContext
The macro writes the impl of the provider trait for UseContext, and its IsProviderFor impl, for each component (#88). See UseContext.
- Old: a component that needed the impl had it written by hand.
- New: the macro writes it, so a hand-written
impl Greeter<Context> for UseContextconflicts with it and fails withE0119. - What to do: delete the hand-written impl.
for_each_replace! is removed
for_each_replace!, which repeated a body for each type in a list, is no longer exported (#77). replace_with! remains, and nothing replaces for_each_replace!.
- What to do: write the repeated items out.
The macro crates are replaced by cgp-macro
cgp-macro holds every macro and derive, and cgp-macro-lib their implementation (#83). cgp::core::macros re-exports cgp-macro, and cgp::re_export_imports exports the attribute of that name.
- Old:
use cgp_component_macro::cgp_component;anduse cgp_field_macro::symbol;. - New: the macros come from
cgp::prelude, or fromcgp_macrofor a crate that depends on it directly. - What to do: write
use cgp::prelude::*;. A crate that depends on the old macro crates changes its manifest tocgp-macro.
CanRun requires an Async error type
CanRun requires HasAsyncErrorType (#90), which also requires the context's Error to be Async.
- Old:
CanRun: Async + HasErrorType, which left the error type unconstrained. - New:
CanRun: HasAsyncErrorType. - What to do: make the error type
Send + Syncfor a context that implements or wiresCanRun.
New features
Checking wiring
IsProviderForandCanUseComponentname the missing dependency.IsProviderFor<Component, Context, Params = ()>is an empty trait that each provider trait carries as a supertrait and#[cgp_provider]implements under the provider's ownwherebounds. A dependency the provider needs but the context lacks then appears in the error.CanUseComponent<Component, Params = ()>holds for a context whoseHasCgpProviderprovider implementsIsProviderForfor the component (#63, #65, #73). SeeIsProviderForandCanUseComponent.check_components!asserts that a context can use components.check_components! { CanUseApp for App { GreeterComponent, FooGetterComponent: [Index<0>, Index<1>] } }implements the traitCanUseAppforApponce per entry, and each impl requiresCanUseComponent. A component with type parameters lists them after a colon, in brackets for several, and the macro accepts impl generics and awhereclause (#78). Seecheck_components!.delegate_and_check_components!wires and checks in one step.delegate_and_check_components! { CanUseApp for App; AppComponents { … } }wires the entries and checks each of them (#98). Seedelegate_and_check_components!.
Components, providers, and contexts
#[cgp_component(Greeter)]takes only the provider name. The component is named by addingComponentto it, and the context type parameter isContext(#96). See#[cgp_component].- A component trait may declare associated constants. A provider impl defines each one with
const CONSTANT: u64 = CONSTANT;(#95). #[cgp_context]declares a context.#[cgp_context] pub struct App;declares the provider structAppComponentsand implementsHasCgpProviderforApp.#[cgp_context(AppProvider)]names the provider struct, and#[cgp_context(AppProvider<T>)]serves a generic context (#66, #96).delegate_components!declares a new struct.delegate_components! { new MyComponents { … } }declaresMyComponentsand wires it,new MyComponents<T> { … }takes generic parameters, andUseDelegate<new Inner { … }>declares a nested table in the same way (#93). Seedelegate_components!.#[blanket_trait]defines a trait alias. A trait with supertraits, default methods, and associated types gets a blanket impl for every type that meets its supertraits (#79, #82). See#[blanket_trait].
Presets
- A preset inherits other presets.
cgp_preset! { Child: ParentA + ParentB { … } }copies the parents' entries into the child, an entry markedoverridereplaces a parent's entry for the same component, and presets may take generic parameters (#91, #92). - A context inherits a preset.
#[cgp_context(AppComponents: MyPreset)]wires every component of the preset toMyPreset::Provider, and the context's own entries add to it (#66, #91). #[cgp::re_export_imports]re-exports a module's imports. On a module, it re-exports theuseitems through a hiddenre_exportsmodule and the other items from the parent. A preset that inherits another can then import the parent's components (#70, #71, #72).
Getters and fields
- A getter trait may take generic parameters.
#[cgp_auto_getter]and#[cgp_getter]traits may be generic, and a getter method may take a secondPhantomData<Tag>argument that selects a field by a type parameter (#64, #76, #80, #81). See#[cgp_auto_getter]and#[cgp_getter]. - A getter returns more than
&T. A method may return&str, read from aStringfield;&[T], read from aVec<T>field;Option<&T>, read from anOption<T>field;MRef<'a, T>; or an owned value, which the impl clones from the field (#81, #87).MRefis an enum of a borrowed&'a Tor an ownedTthat dereferences toT. #[cgp_getter]names its provider by convention. A trait namedHasNamegets the providerNameGetterand the componentNameGetterComponentwhen the attribute names neither (#94).ChainGettersandUseFieldRefread nested and referenced fields.ChainGetters<Product![UseField<symbol!("inner")>, UseField<symbol!("name")>]>reads a field through a chain of getters, andUseFieldRef<Tag, Value>reads a field throughAsRef.FieldMapperandMapFieldcarry the lifetimes the chain needs (#81, #94). SeeChainGetters,UseFieldRef,FieldMapper, andMapField.
Data shapes
#[derive(HasFields)]lists a type's fields.HasFields::Fieldsis aConslist ofField<Tag, Value>entries for a struct's fields, and anEitherlist for an enum's variants.HasFieldsRefgives the borrowed form, andToFields,FromFields, andToFieldsRefconvert a value to and from it (#84). See#[derive(HasFields)],HasFields,ToFields, andFromFields.
Improvements
- The type-level types are declared under Greek letters.
πisCons,εisNil,σisEither,θisVoid,ωisField,ιisChar, andδisIndex, with the English names as aliases, so existing code compiles unchanged and compiler output prints the shorter names (#85). - Type-level types implement more traits. A
Charlist implementsDisplayand prints its text, andCons,Nil,Either,Void,Field, andIndeximplementDebug,PartialEq, andEqwhere their parameters do (#85, #86). - Core traits explain an unmet bound.
DelegateComponent,IsProviderFor,HasField, andHasFieldMutcarry#[diagnostic::on_unimplemented]messages, and theDerefblanket impl ofHasFieldcarries#[diagnostic::do_not_recommend](#63, #74). HasFieldreads throughDerefwithout a'statictarget. A context that dereferences to a struct borrowing other data can use the field traits (#94).
An AI agent wrote this page from the release's source changes and the CGP knowledge base. Its content was verified against the library's source at the release's tag. See How AI is used in this project.