cgp v0.1.0
Version 0.1.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, is its first release on crates.io. This page lists what the release provides.
Released on 2024-09-03.
- Crate:
cgp0.1.0 on crates.io - Tag: v0.1.0
Summary
A trait becomes a component with #[derive_component], and delegate_components! writes the table through which a context chooses a provider for each component. define_components! writes a reusable table, #[derive(HasField)] and symbol! read a context's fields by name, and HasErrorType with CanRaiseError gives generic code an error type to raise into. The release ships as 17 crates, with backends for eyre and standard errors.
Compatibility
- Minimum Rust version: 1.79.
- Released together: the workspace's 17 crates, all at 0.1.0. The facade crates are
cgp,cgp-core, andcgp-extra. The library crates arecgp-component,cgp-field,cgp-error,cgp-async,cgp-sync,cgp-run, andcgp-inner. The macro crates arecgp-component-macro,cgp-component-macro-lib,cgp-field-macro,cgp-field-macro-lib, andcgp-async-macro. The error backends arecgp-error-eyreandcgp-error-std. - Features: the crates declare none.
Upgrading
This is the first release, so there is nothing to upgrade from. A project adds cgp = "0.1.0" and writes use cgp::prelude::*;.
New features
Components and wiring
#[derive_component]turns a trait into a component. The attribute names the component and the provider trait positionally, as in#[derive_component(ErrorTypeComponent, ProvideErrorType<Context>)]. It generates the component's name struct, the provider trait with the context as an explicit first type parameter, a blanket impl of the consumer trait that forwards to the provider chosen by the context'sComponentstable, and a blanket impl of the provider trait for any table that delegates the component to a provider.delegate_components!writes a context's wiring table. Each entry ofdelegate_components! { Context { Component: Provider } }implementsDelegateComponent<Component>for the target type withProvideras itsDelegate. An entry may name several components in brackets, as in[A, B]: Provider, and the target and each component may carry generic parameters (#17). Seedelegate_components!.define_components!writes a reusable table. It takes the entries ofdelegate_components!and declares a struct that holds them, as indefine_components! { Name { ... } }(#17). Beside the struct it generates aDelegatesToNamemarker trait for the types that delegate every component of the table toName, and awith_name!macro that replaces each@Namein its input with the bracketed list of the table's components.DelegateComponentandHasComponentshold the table.DelegateComponent<Name>has an associatedDelegatetype that names the provider for a component, andHasComponentshas an associatedComponentstype that names the table of a context. SeeDelegateComponent.
Fields
HasField<Key>reads a field by a type-level key. Itsget_field(&self, key: PhantomData<Key>)returns a reference to the field, whose type is the associated typeField, and a blanket impl gives the same access to a context that dereferences to a type with the field (#19). SeeHasField.#[derive(HasField)]implementsHasFieldfor each named field of a struct. The key of each impl issymbol!of the field's name, and a tuple struct gets no impls. See#[derive(HasField)].symbol!("name")builds a type-level string. It expands to theChar<'c'>type of each character, separated by commas inside parentheses, whereChartakes acharas a const parameter.
Errors
HasErrorTypedeclares the one error type of a context. Its associatedErrortype must beAsync + Debug, andErrorOf<Context>names it. The component isErrorTypeComponent, with the provider traitProvideErrorType. SeeHasErrorType.CanRaiseError<E>converts a source error into the context's error.Context::raise_error(e)returnsSelf::Error. The component isErrorRaiserComponent, with the provider traitErrorRaiser, andDelegateErrorRaiserpicks the raiser for each source error type from a table. SeeCanRaiseError.cgp-error-eyreprovideseyre'sReportas the error type.ProvideEyreErrorsets the type, andRaiseStdError,RaiseDebugError, andRaiseDisplayErrorraise a source error that implementsstd::error::Error,Debug, orDisplay(#11).cgp-error-stdprovides a boxed standard error. ItsErrorisBox<dyn std::error::Error + Send + Sync + 'static>, andHandleErrorsWithStdErrorsets it as the context's error type and raises any standard error into it (#11).
Async
AsyncabbreviatesSized + Send + Sync + 'static.cgp-asyncdefines the trait with a blanket impl for every such type, and itsasync_traitattribute rewrites eachasync fnof a trait to returnimpl Future<Output = T> + Send.cgp-syncoffers the same names withoutSendandSync. ItsAsyncabbreviatesSized + 'static, and itsasync_traitattribute stripsasyncand.awaitfrom a trait, so the same code compiles as synchronous code.
Running and composing
CanRunruns a context. Itsasync fn run(&self) -> Result<(), Self::Error>is the componentRunnerComponent, with the provider traitRunner, incgp-run(#3). SeeCanRun.HasInnerexposes a wrapped context. It declares an associatedInnertype andinner(&self) -> &Self::Inner, as the componentInnerComponentwith the provider traitProvideInner, incgp-inner(#7).
Crates and the prelude
cgpre-exports the rest.cgp::coreiscgp-core, which re-exports the component, error, field, and inner crates and theAsyncitems,cgp::extraiscgp-extra, which re-exportscgp-runasrun, andcgp::preludeis the core prelude.- The prelude brings in the names a program writes. They are
async_trait,Async,define_components,delegate_components,derive_component,DelegateComponent,HasComponents,CanRaiseError,HasErrorType,symbol,Char, andHasField.
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.