cgp v0.4.2
Version 0.4.2 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, adds extensible records and variants, which build and take apart structs and enums one field at a time. This page lists every change a user can see and the steps that take a project there from v0.4.1.
Released on 2025-07-07.
- Release post: Programming Extensible Data Types in Rust with CGP - Part 1: Modular App Construction and Extensible Builders, the first of four parts
- Crate:
cgp0.4.2 on crates.io - Changes: v0.4.1...v0.4.2
Summary
Builder and extractor traits with three derives let a record be assembled field by field and an enum be taken apart variant by variant, and the new cgp-dispatch crate turns them into handler providers. Casts convert between enums that share variants. The handler family gains TryComputer, reference variants, and new providers, and delegate_components! gains a direct delegation mode. Promote now promotes one level at a time, which changes how a Computer becomes a Handler.
Compatibility
- Minimum Rust version: 1.81, unchanged from v0.4.1.
- Released together: the workspace's 21 crates published on crates.io, all at 0.4.2.
- New crates:
cgp-dispatch, whichcgp::extra::dispatchre-exports.
Upgrading
A project moving from v0.4.1 takes these steps, in this order:
- Change the version to
cgp = "0.4.2". - Write
Promote2<P>wherePromote<P>turned aComputerinto aHandler, per the promotion levels. - Add
Sendbounds where generic code relied onCanHandlerequiring them, per the handler bounds.
Breaking changes
Promote promotes one level at a time
Promote<Provider> lifts a provider one step along Producer, Computer, TryComputer, and Handler (#112). See Promote.
- Old:
Promote<P>implementedHandlerfor aComputerproviderP. - New:
Promote<P>implementsTryComputerfor aComputer,Handlerfor aTryComputer, andComputerfor aProducer. The aliasesPromote2<P>andPromote3<P>stack two and three levels. - What to do: write
Promote2<P>where aComputerwas promoted to aHandler.TryPromote<P>now raises its error throughCanRaiseError, so it no longer needs the context's error type to equal the computer's.
CanHandle no longer requires Send
CanHandle<Code, Input> and its provider trait Handler drop the Send bounds on Code and Input, and Output no longer has to be Send (#117).
- Old:
CanHandle<Code: Send, Input: Send>withtype Output: Send, so generic code could rely on all three beingSend. - New: none of them is bounded.
- What to do: add
Sendto the bounds of generic code that needs it, such as code that spawns the result.
New features
Extensible records
- Builder traits assemble a record field by field.
HasBuilder::builder()returns a record's empty builder,BuildField<Tag>sets one field and returns a builder whose type records the change, andFinalizeBuildturns a complete builder into the record.IntoBuilderandTakeField<Tag>run the process backwards, moving fields out of a record (#112). SeeHasBuilder,BuildField,FinalizeBuild,IntoBuilder, andTakeField. #[derive(BuildField)]implements the builder traits for a struct. It generates a partial struct with one type parameter per field, withHasFieldimpls for the fields that are set (#112). See#[derive(BuildField)].CanBuildFrom<Source>merges one record into another. It sets every field of a builder that the source supplies (#112). SeeCanBuildFrom.
Extensible variants
- Extractor traits take an enum apart variant by variant.
HasExtractorconverts an enum to its extractor and back,HasExtractorRefborrows one,ExtractField<Tag>removes one variant and returnsResult<Value, Remainder>, andFromVariant<Tag>builds an enum from one variant's value.FinalizeExtractandFinalizeExtractResultdischarge a remainder with no variants left, so a match over every variant needs no wildcard (#112). SeeHasExtractor,ExtractField,FromVariant, andFinalizeExtract. #[derive(ExtractField)]and#[derive(FromVariant)]implement them for an enum (#112). See#[derive(ExtractField)]and#[derive(FromVariant)].IsPresent,IsNothing, andIsVoidimplementMapType, which maps a type to itself, to(), or toVoid, andMapFieldsapplies such a mapping to a field list (#112). SeeMapTypeandMapFields.
Casting
CanUpcast<Target>widens an enum andCanDowncast<Target>narrows it.upcastconverts into an enum with a superset of the variants, anddowncastreturnsResult<Target, Remainder>;CanDowncastFieldsdoes the same by field list (#112). SeeCanUpcastandCanDowncast.
Dispatch providers
cgp-dispatch holds the handler providers that build records and match variants (#112, #116, #117, #119, #120). Each provider serves Computer, TryComputer, and Handler.
BuildWithHandlers<Output, Handlers>starts fromOutput's empty builder, pipes it through the handlers, and finalizes it. SeeBuildWithHandlers.BuildAndSetField<Tag, Provider>andBuildAndMerge<Provider>run a provider on a reference to the builder, then set one field or merge the result into the builder. SeeBuildAndSetFieldandBuildAndMerge.BuildAndMergeOutputs<Output, Handlers>builds an output by merging what each handler returns. SeeBuildAndMergeOutputs.MatchWithHandlers<Handlers>converts its input to an extractor and tries each handler on one variant. It then finalizes the remainder.MatchWithHandlersRef<Handlers>does the same on a reference, andDispatchMatchers<Handlers>runs the matchers in order. SeeMatchWithHandlers.ExtractFieldAndHandle<Tag, Provider>andDowncastAndHandle<Inner, Provider>extract one variant, or downcast to a smaller enum, and run a provider on it. SeeExtractFieldAndHandleandDowncastAndHandle.MatchWithFieldHandlers<Provider>chooses a handler per variant from the input type, andMatchWithValueHandlers,MatchWithFieldHandlersRef, andMatchWithValueHandlersRefare its aliases for unwrapped values and references. SeeMatchWithFieldHandlersandMatchWithValueHandlers.
Handlers
TryComputeris a fallible, synchronous computation.CanTryCompute<Code, Input>returnsResult<Self::Output, Self::Error>and requiresHasErrorType(#112). SeeTryComputer.- Reference variants take
&Input.CanComputeRef,CanTryComputeRef, andCanHandleRef, with the provider traitsComputerRef,TryComputerRef, andHandlerRef, compute from a borrowed input, andPromoteRef<Provider>turns a reference provider into one for owned input (#118). SeeComputerRef,HandlerRef, andPromoteRef. Computerand the new components deriveUseInputDelegate, so a context can choose a provider by input type as well as byCode, asHandleralready could (#112, #118).ReturnInputandHandleFieldValueare new providers.ReturnInputreturns its input, andHandleFieldValue<Provider>passes the value inside aFieldtoProvider(#112). SeeReturnInputandHandleFieldValue.PipeHandlersservesTryComputeras well asComputerandHandler(#112).- Three attributes turn a function into a provider.
#[cgp_computer]makes aComputerfrom a plain function,#[cgp_producer]makes aProducerfrom a function without parameters, and#[cgp_handler]makes aHandlerfrom anasyncfunction. The provider is named by writing the function name in CamelCase unless the attribute names it. A function with one reference parameter also gets the reference providers (#112, #121). See#[cgp_computer]and#[cgp_producer].
Wiring
->delegates a key to another table's entry.delegate_components! { App { [A, B] -> Other } }sets each key's delegate to whatOtherwires for the same key, where:names a provider (#111). See the operators.
Improvements
cgp::preludeincludes the extra crate's prelude. The prelude now exportsPhantomData, the builder, extractor, andMapTypetraits and markers, the three new derives,Computer,TryComputer,Handler,Producerwith their component keys,Promote,PromoteRef,TryPromote, and the three function attributes (#112).
Fixes
#[derive(HasField)]on a tuple struct: it implementsHasField<Index<0>>,HasField<Index<1>>, and so on for the fields, where v0.4.1 implemented nothing (#115).- Unsized parameters:
IsProviderForand theCanUseComponenttrait accept an unsized parameter such asstr, where v0.4.1 failed withE0277(#114). The blanketCanUseComponentimpl for a context still requires a sized parameter.
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.