Skip to main content

HasOptionalBuilder

Starting a builder in which every field is already optional.

Overview​

Context-Generic Programming (CGP) assembles a struct generically through a builder family that is deliberately strict: a field is set exactly once, and a partial record becomes its concrete struct only when every field is present. That strictness is what catches a missing field at compile time, and it is too rigid for a record whose fields arrive in an unpredictable order, or more than once.

HasOptionalBuilder is the entry point that relaxes it. It hands back a partial value with every field marked IsOptional rather than IsNothing, so each slot holds an Option and absence becomes a runtime condition instead of a type-level one. Fields can then be set freely with SetOptional, in any order and as many times as you like, and the choice of how to end is deferred to the finalize call.

It stands to HasBuilder as the optional layer stands to the core one: same machinery, different starting marker.

Definition​

HasOptionalBuilder carries the partial builder type as an associated Builder and hands back an empty one:

pub trait HasOptionalBuilder {
type Builder;

fn optional_builder() -> Self::Builder;
}

Builder names the partial companion type the derive generated, with every field marked IsOptional. It is the same companion the core builder produces, at a configuration the core builder never starts from. optional_builder is an associated function without a receiver, so a caller writes Context::optional_builder(). The trait does not declare a supertrait, and it is implemented as a blanket impl over the core builder machinery, so any record that derives the builder gains it. It is not in the prelude; the whole optional-field layer lives in cgp-field-extra.

Usage​

It is not in the prelude. Nothing in the optional-field layer is. Import it from cgp::extra::field::impls:

use cgp::extra::field::impls::HasOptionalBuilder;

The impls are blanket ones over the core builder machinery, so any record deriving #[derive(BuildField)] (or #[derive(CgpData)]) gets this with nothing more to derive.

Two endings are available, and picking between them at the call site is the layer's real payoff: FinalizeOptional requires every field and reports a missing one, while CanFinalizeWithDefault fills unset fields from Default.

Examples​

An all-optional builder, set in any order and finished by each of the two endings:

use cgp::prelude::*;
use cgp::extra::field::impls::{
CanFinalizeWithDefault, FinalizeOptional, HasOptionalBuilder, SetOptional,
};

#[derive(Debug, PartialEq, CgpData)]
pub struct Context {
pub foo: String,
pub bar: u64,
}

pub fn demo() {
let context = Context::optional_builder()
.set(PhantomData::<Symbol!("bar")>, 42)
.set(PhantomData::<Symbol!("foo")>, "foo".to_owned())
.finalize_optional();
assert_eq!(
context,
Ok(Context {
foo: "foo".to_owned(),
bar: 42,
})
);

// The same kind of builder, with `bar` left unset, finalized each way.
let defaulted = Context::optional_builder()
.set(PhantomData::<Symbol!("foo")>, "foo".to_owned())
.finalize_with_default();
assert_eq!(defaulted.bar, 0);

let missing = Context::optional_builder()
.set(PhantomData::<Symbol!("foo")>, "foo".to_owned())
.finalize_optional();
assert_eq!(missing, Err("bar"));
}

The fields are set in reverse declaration order, which the core builder also allows. The core builder rejects an incomplete build at compile time, while here the same unfinished builder either fills bar with 0 or reports it by name, as the finalize call chooses.

When to use it​

Reach for it when fields must be settable in any order and more than once, which the core build_field cannot do, and stay on the core builder otherwise.

  • HasBuilder when every field is genuinely required and set once. You lose the compile-time completeness check by moving here, and that check is the reason the builder family exists.
  • HasOptionalBuilder when the fields arrive unpredictably: parsed configuration, accumulated defaults, or a value assembled across several passes.
  • ToOptional when you already hold a core builder and want to convert it rather than start fresh.
  • A hand-written builder when the logic is the point: validation at finalize, interdependent fields, or computed defaults that are not Default::default(). This layer models presence and defaulting, and nothing else.

Under the hood​

The trait's one impl is a blanket impl over the core builder and ToOptional:

impl<Context, Builder> HasOptionalBuilder for Context
where
Context: HasBuilder,
Context::Builder: ToOptional<Output = Builder>,
{
type Builder = Builder;

fn optional_builder() -> Self::Builder {
Self::builder().to_optional()
}
}

So optional_builder() starts at the all-IsNothing configuration and re-marks every field to IsOptional with a TransformMapFields walk carrying the TransformOptional marker. For the example's Context, the result is __PartialContext<IsOptional, IsOptional>, the same partial companion the core builder uses, at a configuration the core builder never reaches on its own.

Nothing about the companion type is special to this layer. The marker changes, and with it which operations apply: SetOptional resolves where BuildField does not, and the strict FinalizeBuild does not resolve at all until a finalize has re-marked the fields back to IsPresent.

Common Mistakes​

It is not in the prelude. Import from cgp::extra::field::impls, along with whatever else in the layer you use.

Moving here gives up the compile-time completeness check. With the core builder a missing field is a compile error; here it is an Err or a silently substituted default. That is the trade, and it is worth making consciously.

The builder's type does not record what you have set. Every field stays IsOptional throughout, which allows re-setting and is why finalizing has to check at run time. It also means finalize_with_default needs Default on every field's type, set or not.

optional_builder() is an associated function, so it is Context::optional_builder() with no receiver.

A field whose type is already Option<T> is not the same as an IsOptional field. The former is a value that happens to be optional and must still be set; the latter is a builder slot that may be empty. Conflating them produces an Option<Option<T>>.

The ideas behind it:

Source​

  • to_optional.rs: HasOptionalBuilder, ToOptional, and TransformOptional

An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.