Skip to main content

cgp v0.5.0

Version 0.5.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, removes the Async trait and adds monadic computation, automatic dispatch over enums, and one derive for extensible data. This page lists every change a user can see and the steps that take a project there from v0.4.2.

Released on 2025-10-12.

Summary​

The Async trait and the async aliases are removed, and a project recovers Send where it spawns a future through a proxy trait such as CanSendRun. #[derive(CgpData)] derives extensible records and variants in one step, #[cgp_auto_dispatch] implements a trait for an enum from its variants, and the new cgp-monad crate composes handlers that short-circuit. Symbol! replaces symbol! and can produce a &'static str, and cgp-field moves its exports into submodules.

Compatibility​

  • Minimum Rust version: 1.89, up from 1.81.
  • Released together: the workspace's 23 crates published on crates.io, all at 0.5.0.
  • New crates: cgp-monad, for monadic computation; cgp-field-extra, for the optional builder and defaults; and cgp-extra-macro with cgp-extra-macro-lib, which hold #[cgp_computer], #[cgp_producer], and #[cgp_auto_dispatch].
  • Removed crates: cgp-async, cgp-sync, and cgp-inner; see the async removal and HasInner.
  • Features: cgp and cgp-core lose their full feature; see the features.

Upgrading​

A project moving from v0.4.2 takes these steps, in this order:

  1. Change the version to cgp = "0.5.0" on Rust 1.89 or newer, and delete features = ["full"] from a cgp or cgp-core dependency, per the features.
  2. Remove the Async constructs: replace HasAsyncErrorType, CanRaiseAsyncError, CanWrapAsyncError, and HasAsyncRuntimeType with their plain counterparts, and delete Async, MaybeSend, and MaybeSync bounds, per the removal.
  3. Recover Send where a future is spawned through a proxy trait, per the Send bound, and name a Code wherever CanRun is used, per CanRun.
  4. Rename the type-level strings: symbol! becomes Symbol!, and Char becomes Chars, per Symbol! and Chars.
  5. Update the imports of cgp-field items and of the names that moved, per the field modules and the moved names.
  6. Rewrite the handler code: promotions per the promotion chain, Result errors per the error rule, and #[cgp_handler] per its replacement.
  7. Rewrite the builder code that names a generated type or a trait that changed, per the partial types and FinalizeBuild, and replace HasInner per its removal.
  8. Build the crate and fix what the compiler reports.

Breaking changes​

Async and the async aliases are removed​

Async, MaybeSend, and MaybeSync are removed, together with the traits built on them, HasAsyncErrorType, CanRaiseAsyncError, CanWrapAsyncError, and HasAsyncRuntimeType (#149). The crates cgp-async and cgp-sync are removed too, and cgp-async-macro exports only #[async_trait]: its native_async and strip_async macros are gone.

  • Old: Async aliased Send + Sync, and HasAsyncErrorType required it of the context and of its error type.
  • New: HasErrorType, CanRaiseError, CanWrapError, and HasRuntimeType carry no Send or Sync bound, and CanHandle requires HasErrorType where it required HasAsyncErrorType.
  • What to do: replace each removed trait with its plain counterpart, and delete Async, MaybeSend, and MaybeSync from bounds. A project that still wants an old trait can copy its definition into its own crate.

#[async_trait] no longer requires Send​

#[async_trait] desugars an async fn in a trait to a function that returns impl Future<Output = T>, without a Send bound on the future (#149). Every async trait that cgp defines is affected, among them CanRun, CanComputeAsync, and CanHandle.

  • Old: the desugared future was impl Future<Output = T> + MaybeSend, so generic code could pass the future of a call such as context.run() to tokio::spawn.
  • New: the future is impl Future<Output = T>, and generic code can no longer show that it is Send.
  • What to do: where generic code must spawn a future, require a proxy trait whose method returns impl Future + Send, such as CanSendRun. Implement its provider trait SendRunner on the concrete context by forwarding to run, where the compiler sees the concrete types. The release post works the pattern through in Emulating RTN. A trait of the project's own that promises a Send future needs a copy with the bound, for code that calls the traits cgp defines.

CanRun takes a Code parameter​

CanRun and its provider trait Runner take a Code type parameter, and run takes a PhantomData<Code> argument (#149). See CanRun.

  • Old: CanRun: HasAsyncErrorType with run(&self), and Runner<Context>.
  • New: CanRun<Code>: HasErrorType with run(&self, _code: PhantomData<Code>), and Runner<Context, Code>. A bound written as CanRun without a parameter fails with E0107.
  • What to do: name a Code type, such as a marker struct, wherever the project uses CanRun, and pass PhantomData to run. A context can choose a provider per code, because the component derives UseDelegate<Code>.

cgp-field exports move into submodules​

The root of cgp-field, which cgp::core::field re-exports, stops re-exporting its items (#150). They are in three public modules instead: traits, impls, and types.

  • Old: cgp::core::field::HasField, cgp::core::field::UseField, and cgp::core::field::Cons.
  • New: cgp::core::field::traits::HasField, cgp::core::field::impls::UseField, and cgp::core::field::types::Cons.
  • What to do: update each explicit import of a cgp-field item. The traits are in traits; the providers, the field-state markers, and the casting traits are in impls; and Cons, Nil, Either, Void, Field, Index, Chars, Symbol, and Life are in types. A glob import of cgp::prelude is unaffected for the names the prelude exports.

Several names move to other modules​

Four names change their import path, and a project that imports them explicitly updates the import:

  • TakeField leaves the prelude, and is imported from cgp::core::field::traits (#148).
  • Promote, PromoteRef, and TryPromote leave the prelude, and are imported from cgp::extra::handler (#137).
  • HandleFieldValue moves from cgp::extra::handler to cgp::extra::dispatch (#139).
  • #[cgp_computer] and #[cgp_producer] live in the new cgp-extra-macro crate, so the path cgp::core::macros::cgp_computer no longer resolves (#138). The prelude exports both.

symbol! becomes Symbol! and its expansion carries the length​

symbol! is removed, and Symbol! takes its place with a different expansion (#151, #159, #173).

  • Old: symbol!("abc") expanded to the nested Char<'a', Char<'b', Char<'c', Nil>>>, which the compiler printed as ΞΉ<'a', ΞΉ<'b', ΞΉ<'c', Ξ΅>>>.
  • New: Symbol!("abc") expands to Symbol<3, Chars<'a', Chars<'b', Chars<'c', Nil>>>>, with the length as the first parameter, and the compiler prints ψ<3, ΞΆ<'a', ΞΆ<'b', ΞΆ<'c', Ξ΅>>>>. The HasField impls that #[derive(HasField)] and the getter macros generate use the new type.
  • What to do: write Symbol! for symbol!, and give a type-level string that was written out by hand the new shape.

Char is renamed Chars​

Chars holds one character of a type-level string and the rest of the string, and replaces Char (#165, #159). Its short name changes from ΞΉ to ΞΆ, which avoids the confusable_idents warning that ΞΉ raised beside a variable named i.

  • Old: Char<CHAR, Tail>, written ΞΉ<CHAR, Tail>.
  • New: Chars<CHAR, Tail>, written ΞΆ<CHAR, Tail>.
  • What to do: rename each use. Neither Char nor ΞΉ exists any more.

HasInner and cgp-inner are removed​

The trait HasInner, its component, and the cgp-inner crate are removed, along with the cgp::extra::inner module (#170). UseField composes contexts more flexibly. Nothing replaces HasInner by name.

  • Old: HasInner with type Inner and fn inner(&self) -> &Self::Inner.
  • New: a getter or an abstract type read from a field with UseField.
  • What to do: read the inner context through UseField, or copy the old trait into the project's own crate.

Generated partial types gain the __Partial prefix​

The types that #[derive(BuildField)] and #[derive(ExtractField)] generate gain a __Partial prefix, which keeps them out of the user's namespace (#156).

  • Old: PartialPerson for a struct Person, and PartialShape and PartialRefShape for an enum Shape.
  • New: __PartialPerson, __PartialShape, and __PartialRefShape.
  • What to do: rename each generated type that the code names. Most code reaches them only through builder() and the traits.

FinalizeBuild takes its target from PartialData​

FinalizeBuild becomes a subtrait of the new PartialData, and its Output associated type is gone (#152). BuildField is now implemented for every type that implements UpdateField<Tag, IsPresent, Mapper = IsNothing> (#148).

  • Old: trait FinalizeBuild { type Output; fn finalize_build(self) -> Self::Output; }.
  • New: trait FinalizeBuild: PartialData { fn finalize_build(self) -> Self::Target; }, with Target the record the partial type completes.
  • What to do: write Target where a bound named FinalizeBuild::Output, and implement PartialData for a hand-written partial type. The derives generate both.

The handler promotion chain gains an async step​

Promote<Provider> lifts a provider one step: a Producer to a Computer, a Computer to a TryComputer, and an AsyncComputer to a Handler. The new PromoteAsync<Provider> lifts a Computer to an AsyncComputer and a TryComputer to a Handler (#136, #137). See Promote and PromoteAsync.

  • Old: Promote<P> turned a TryComputer into a Handler, Promote<Promote<P>> turned a Computer into one, and the aliases Promote2 and Promote3 stacked two and three levels.
  • New: PromoteAsync<P> turns a TryComputer into a Handler, and PromoteAsync<Promote<P>> turns a Computer into one. Promote2 and Promote3 are removed.
  • What to do: replace Promote<P> with PromoteAsync<P> where it produced a Handler from a TryComputer, and Promote<Promote<P>> with PromoteAsync<Promote<P>>.

TryPromote and function providers no longer convert errors​

TryPromote<Provider> requires the Result that its provider returns to carry Context::Error (#129, #136). The providers that #[cgp_computer] generates for a function that returns Result<T, E> promote through it, so they follow the same rule.

  • Old: TryPromote and #[cgp_handler] converted any error type E into Context::Error through CanRaiseError<E>.
  • New: E must be Context::Error; a provider whose E differs fails with a type mismatch.
  • What to do: return the context's error type from the function, or convert the error inside it before it returns.

#[cgp_handler] is folded into #[cgp_computer]​

#[cgp_handler] is removed, and #[cgp_computer] accepts an async function and generates the Handler that #[cgp_handler] generated (#137).

  • Old: #[cgp_handler] async fn double(x: u8) -> u8.
  • New: #[cgp_computer] async fn double(x: u8) -> u8, which derives an AsyncComputer and promotes it to a Handler.
  • What to do: change the attribute name, and apply the error rule to a function that returns a Result.

The full features are removed​

cgp and cgp-core lose their full feature, which forwarded to the removed async features and to cgp-extra (#149). cgp-extra keeps its own default full feature, and cgp now depends on cgp-extra with its default features.

  • Old: cgp = { version = "0.4.2", features = ["full"] } resolved, and default-features = false left out the providers that need an allocator, such as DebugError.
  • New: features = ["full"] fails to resolve, because cgp has no such feature, and DebugError is available even with default-features = false.
  • What to do: delete "full" from the feature list.

New features​

Derives and macros​

  • #[derive(CgpData)] derives the extensible-data traits for a struct or an enum. On a struct it derives HasField, HasFields, and the builder traits, and on an enum it derives HasFields, ExtractField, and FromVariant; #[derive(CgpRecord)] and #[derive(CgpVariant)] are its struct and enum forms (#154). See #[derive(CgpData)], #[derive(CgpRecord)], and #[derive(CgpVariant)].
  • #[cgp_auto_dispatch] implements a trait for an enum whose variants all implement it. HasArea for Circle and Rectangle gives Shape an implementation, and neither the trait nor the enum needs to know about the other, so it works across crates. A method may take self, &self, or &mut self and extra arguments, and may be async (#139, #142). See #[cgp_auto_dispatch].

Extensible records​

  • UpdateField<Tag, M> replaces a wrapped field value in a partial record. BuildField is implemented through it, and #[derive(CgpData)] derives it (#148). See UpdateField.
  • finalize_with_default completes a partial record. CanFinalizeWithDefault fills each unset field from Default, and CanBuildWithDefault<Source> builds a record from a source record and defaults the rest (#128, #130). See CanFinalizeWithDefault and CanBuildWithDefault.
  • The optional builder keeps one type while fields are set. The IsOptional marker stores each field as an Option, HasOptionalBuilder::optional_builder() starts one, SetOptional::set fills a field, and FinalizeOptional::finalize_optional returns the record, or the name of the first missing field as a &'static str (#152). The traits are in the new cgp-field-extra crate, which cgp::extra::field re-exports. See HasOptionalBuilder, SetOptional, and FinalizeOptional.

Extensible variants and visitors​

  • HasExtractorMut extracts from a mutable reference, and #[derive(ExtractField)] implements it for an enum (#135). See HasExtractorMut.
  • MapTypeRef maps a field type to a reference type. The markers IsRef, IsMut, and IsOwned implement it (#132, #135). See MapTypeRef.
  • The matchers cover a mutable reference and an input with extra arguments. MatchWithHandlersMut and MatchWithValueHandlersMut match a &mut value. MatchFirstWithHandlers, MatchFirstWithValueHandlers, and their Ref and Mut forms match the first element of a tuple (Value, Args) and pass Args on (#134, #135, #161). ExtractFirstFieldAndHandle and HandleFirstFieldValue are the providers they use. See MatchFirstWithHandlers and MatchWithValueHandlers.

Monadic computation​

  • The cgp-monad crate composes computations that short-circuit. PipeMonadic<M, Providers> runs providers in order under the monad M. ErrMonadic passes on the Ok value and stops at an Err, OkMonadic does the opposite, and IdentMonadic composes plainly. BindOk and BindErr lift a provider over Result, and OkMonadicTrans and ErrMonadicTrans stack monads. The traits behind them are MonadicBind, ContainsValue, LiftValue, and MonadicTrans (#127, #129). DispatchMatchers<Handlers> is now an alias for PipeMonadic<OkMonadic, Handlers>, and cgp::extra::monad re-exports the crate. See PipeMonadic, BindOk, BindErr, and MonadicBind.

Handlers​

  • AsyncComputer is the asynchronous counterpart of Computer. CanComputeAsync<Code, Input> returns an Output without a Result, and Handler remains the asynchronous counterpart of TryComputer. AsyncComputerRef and CanComputeAsyncRef take a reference (#136). See AsyncComputer and AsyncComputerRef.
  • #[cgp_computer] accepts an async function and derives an AsyncComputer for it (#137).
  • ComposeHandlers<A, B> runs one provider and passes its output to the next, for Computer, TryComputer, AsyncComputer, and Handler. PipeHandlers is built on it (#129, #136). See ComposeHandlers.
  • Five promotion providers collect what a provider can be promoted to: PromoteComputer, PromoteTryComputer, PromoteProducer, PromoteAsyncComputer, and PromoteHandler, each a table of the promotions for one kind of provider (#137). See PromoteComputer and PromoteHandler.
  • UseField<Tag> is a Computer and an AsyncComputer. It runs the CanCompute or CanComputeAsync implementation of the field named by Tag (#132, #136). See UseField.
  • NoCode is a value of type PhantomData<()> for calling a handler that has no code (#132).
  • ErrorOnly<E> is a context that carries only an error type, with HasErrorType::Error = E (#129).
  • CanSendRun<Code> and its provider trait SendRunner return a Send future (#149); see the Send bound.

Type-level strings and lifetimes​

  • StaticString produces a &'static str from a Symbol! type. <Symbol!("hello") as StaticString>::VALUE is "hello" in a const context, which the length that Symbol! now carries makes possible (#159). See StaticString.
  • Life<'a> writes a lifetime as a type (#145, #166). See Life.

Improvements​

  • A getter method may take a first argument other than self: #[cgp_getter] and #[cgp_auto_getter] accept fn foo_bar(foo: &Self::Foo) -> &Self::Bar, and UseField<Tag> implements the provider when Self::Foo has the field (#169). See #[cgp_getter] and #[cgp_auto_getter].
  • A component trait may declare lifetime parameters, which IsProviderFor carries as Life<'a> and check_components! accepts (#145). A component such as trait CanGreet<'a> compiles where v0.4.2 rejected it.
  • A bare identifier sets the provider name: #[cgp_getter(FooGetter)] and #[cgp_type(FooTypeProvider)] mean the same as provider: FooGetter and provider: FooTypeProvider (#143, #163). See #[cgp_type].
  • The prelude exports the new names: Chars, Symbol, Life, CgpData, CgpRecord, CgpVariant, UpdateField, PartialData, MapTypeRef, IsRef, IsMut, HasExtractorMut, AsyncComputer, #[cgp_auto_dispatch], and the MatchWithValueHandlers and MatchFirstWithValueHandlers providers, so use cgp::prelude::* reaches them (#154, #137, #139).
  • DelegateComponent<Name: ?Sized> accepts an unsized name: impl DelegateComponent<str> for Table compiles, where v0.4.2 failed with E0277 (#147). See DelegateComponent.

Fixes​

  • new with an array key: delegate_components! declares a struct named by new once, where an entry such as [FooKey, BarKey]: UseDelegate<new InnerComponents { … }> declared it once per key and failed with E0428 (#164). See delegate_components!.
  • CanUseComponent for an unsized parameter: a context whose provider implements IsProviderFor for str satisfies CanUseComponent<Component, str>, where v0.4.2 failed with E0277 (#166). See CanUseComponent.

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.