Skip to main content

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.

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, which cgp::extra::dispatch re-exports.

Upgrading​

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

  1. Change the version to cgp = "0.4.2".
  2. Write Promote2<P> where Promote<P> turned a Computer into a Handler, per the promotion levels.
  3. Add Send bounds where generic code relied on CanHandle requiring 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> implemented Handler for a Computer provider P.
  • New: Promote<P> implements TryComputer for a Computer, Handler for a TryComputer, and Computer for a Producer. The aliases Promote2<P> and Promote3<P> stack two and three levels.
  • What to do: write Promote2<P> where a Computer was promoted to a Handler. TryPromote<P> now raises its error through CanRaiseError, 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> with type Output: Send, so generic code could rely on all three being Send.
  • New: none of them is bounded.
  • What to do: add Send to 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, and FinalizeBuild turns a complete builder into the record. IntoBuilder and TakeField<Tag> run the process backwards, moving fields out of a record (#112). See HasBuilder, BuildField, FinalizeBuild, IntoBuilder, and TakeField.
  • #[derive(BuildField)] implements the builder traits for a struct. It generates a partial struct with one type parameter per field, with HasField impls 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). See CanBuildFrom.

Extensible variants​

  • Extractor traits take an enum apart variant by variant. HasExtractor converts an enum to its extractor and back, HasExtractorRef borrows one, ExtractField<Tag> removes one variant and returns Result<Value, Remainder>, and FromVariant<Tag> builds an enum from one variant's value. FinalizeExtract and FinalizeExtractResult discharge a remainder with no variants left, so a match over every variant needs no wildcard (#112). See HasExtractor, ExtractField, FromVariant, and FinalizeExtract.
  • #[derive(ExtractField)] and #[derive(FromVariant)] implement them for an enum (#112). See #[derive(ExtractField)] and #[derive(FromVariant)].
  • IsPresent, IsNothing, and IsVoid implement MapType, which maps a type to itself, to (), or to Void, and MapFields applies such a mapping to a field list (#112). See MapType and MapFields.

Casting​

  • CanUpcast<Target> widens an enum and CanDowncast<Target> narrows it. upcast converts into an enum with a superset of the variants, and downcast returns Result<Target, Remainder>; CanDowncastFields does the same by field list (#112). See CanUpcast and CanDowncast.

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 from Output's empty builder, pipes it through the handlers, and finalizes it. See BuildWithHandlers.
  • BuildAndSetField<Tag, Provider> and BuildAndMerge<Provider> run a provider on a reference to the builder, then set one field or merge the result into the builder. See BuildAndSetField and BuildAndMerge.
  • BuildAndMergeOutputs<Output, Handlers> builds an output by merging what each handler returns. See BuildAndMergeOutputs.
  • 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, and DispatchMatchers<Handlers> runs the matchers in order. See MatchWithHandlers.
  • ExtractFieldAndHandle<Tag, Provider> and DowncastAndHandle<Inner, Provider> extract one variant, or downcast to a smaller enum, and run a provider on it. See ExtractFieldAndHandle and DowncastAndHandle.
  • MatchWithFieldHandlers<Provider> chooses a handler per variant from the input type, and MatchWithValueHandlers, MatchWithFieldHandlersRef, and MatchWithValueHandlersRef are its aliases for unwrapped values and references. See MatchWithFieldHandlers and MatchWithValueHandlers.

Handlers​

  • TryComputer is a fallible, synchronous computation. CanTryCompute<Code, Input> returns Result<Self::Output, Self::Error> and requires HasErrorType (#112). See TryComputer.
  • Reference variants take &Input. CanComputeRef, CanTryComputeRef, and CanHandleRef, with the provider traits ComputerRef, TryComputerRef, and HandlerRef, compute from a borrowed input, and PromoteRef<Provider> turns a reference provider into one for owned input (#118). See ComputerRef, HandlerRef, and PromoteRef.
  • Computer and the new components derive UseInputDelegate, so a context can choose a provider by input type as well as by Code, as Handler already could (#112, #118).
  • ReturnInput and HandleFieldValue are new providers. ReturnInput returns its input, and HandleFieldValue<Provider> passes the value inside a Field to Provider (#112). See ReturnInput and HandleFieldValue.
  • PipeHandlers serves TryComputer as well as Computer and Handler (#112).
  • Three attributes turn a function into a provider. #[cgp_computer] makes a Computer from a plain function, #[cgp_producer] makes a Producer from a function without parameters, and #[cgp_handler] makes a Handler from an async function. 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 what Other wires for the same key, where : names a provider (#111). See the operators.

Improvements​

  • cgp::prelude includes the extra crate's prelude. The prelude now exports PhantomData, the builder, extractor, and MapType traits and markers, the three new derives, Computer, TryComputer, Handler, Producer with their component keys, Promote, PromoteRef, TryPromote, and the three function attributes (#112).

Fixes​

  • #[derive(HasField)] on a tuple struct: it implements HasField<Index<0>>, HasField<Index<1>>, and so on for the fields, where v0.4.1 implemented nothing (#115).
  • Unsized parameters: IsProviderFor and the CanUseComponent trait accept an unsized parameter such as str, where v0.4.1 failed with E0277 (#114). The blanket CanUseComponent impl 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.