parcel::FieldsBuilder< Payload > Class Template Reference

Fluent builder used inside Derived::field_descriptors() to declare struct fields. More...

#include <struct.h>

Public Member Functions
template<auto MemberPtr, CellLike CellT>
FieldsBuilder &	field (std::string key)
	Declare a field with an explicit cell wrapper CellT.
template<auto MemberPtr> requires HasDefaultCellWrapper< typename detail::member_pointer_traits<decltype(MemberPtr)>::field_type>
FieldsBuilder &	field (std::string key)
	Declare a field with cell wrapper inferred via default_cell_for.
FieldsBuilder &	name (std::string v)
	Set the name display info of the most recently declared field.
FieldsBuilder &	description (std::string v)
	Set the description display info of the most recently declared field.
FieldsBuilder &	icon (comms::Icon icon)
	Set the icon display info of the most recently declared field to the typed icon.
FieldsBuilder &	icon (std::string const &v)
	Set the icon display info of the most recently declared field, parsing an Iconify set:name string (e.g.
FieldsBuilder &	color (comms::Color color)
	Set the color display info of the most recently declared field to the typed color.
FieldsBuilder &	color (std::string const &v)
	Set the color display info of the most recently declared field, parsing a color string (hex, CSS-functional, or a CSS color name).
FieldsBuilder &	is_required (bool v=true)
	Override the required flag of the most recently declared field.
FieldsBuilder &	optional ()
	Shorthand for is_required(false).
template<CellLike ParentCell> requires std::is_base_of_v<typename ParentCell::payload_type, Payload>
FieldsBuilder &	extend ()
	Splice in every field declared by another struct cell.
FieldsBuilder &	remove_field (const std::string_view key)
	Drop a previously declared (or inherited) field by key.
payload_field_descriptors_t	build ()
	Move out the accumulated field descriptors.

Detailed Description

template<typename Payload>
class parcel::FieldsBuilder< Payload >

Fluent builder used inside Derived::field_descriptors() to declare struct fields.

Typical use:

return FieldsBuilder<Person>{}
    .field<&Person::id, I32Cell>("id").description("Primary key")
    .field<&Person::name>("name")           // type inferred via default_cell_for
    .field<&Person::email>("email").optional()
    .build();

Field-list reuse via extend<ParentCell>():

struct Address     { std::string street; std::string city; };
struct HomeAddress : Address { std::string label; };
 
// HomeAddressCell::field_descriptors():
return FieldsBuilder<HomeAddress>{}
    .extend<AddressCell>()                  // splice street + city
    .field<&HomeAddress::label>("label")    // add new field
    .build();

Duplicate keys are last-wins: a field<>() call with the same key as an already-declared field replaces it in place. remove_field(key) drops a previously declared (or inherited) field.

Template Parameters

Payload

The struct type whose fields are being declared.

See also

default_cell_for — drives the inference overload.

InheritedFieldDescriptor — backs extend<>.

Member Function Documentation

build()

template<typename Payload >

payload_field_descriptors_t parcel::FieldsBuilder< Payload >::build ( )

inline

Move out the accumulated field descriptors.

Returns

Vector of payload field descriptors.

color() [1/2]

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::color ( comms::Color  color )

inline

Set the color display info of the most recently declared field to the typed color.

Parameters

color

Color value.

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

color() [2/2]

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::color ( std::string const &  v )

inline

Set the color display info of the most recently declared field, parsing a color string (hex, CSS-functional, or a CSS color name).

Parameters

v	Color string accepted by comms::Color::parse.

Returns

*this for chaining.

Exceptions

std::runtime_error	if called before any field<>().
InvalidJsonException	if v does not parse to a color.

description()

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::description ( std::string  v )

inline

Set the description display info of the most recently declared field.

Parameters

v	Description text.

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

extend()

template<typename Payload >

template<CellLike ParentCell>
requires std::is_base_of_v<typename ParentCell::payload_type, Payload>

FieldsBuilder & parcel::FieldsBuilder< Payload >::extend ( )

inline

Splice in every field declared by another struct cell.

Each parent field is wrapped in InheritedFieldDescriptor and appended in declaration order. A subsequent field<>(key) with the same key replaces the inherited entry in place (last-wins). The constraint requires ParentCell's payload to be a base of (or the same as) Payload — extending from an unrelated struct cell will not compile.

After this call, last_ points at the most recently spliced field, so a chained .name(...) / .description(...) / .optional() mutates that inherited field's per-call descriptor copy without affecting the parent cell.

Template Parameters

ParentCell

A CellLike exposing payload_type whose payload is a base of (or same as) Payload.

Returns

*this for chaining.

field() [1/2]

template<typename Payload >

template<auto MemberPtr, CellLike CellT>

FieldsBuilder & parcel::FieldsBuilder< Payload >::field ( std::string  key )

inline

Declare a field with an explicit cell wrapper CellT.

Template Parameters

MemberPtr	Pointer-to-member of Payload.
CellT	Cell type used to wrap the field on the wire.

Parameters

key	JSON key for this field.

Returns

*this for chaining.

field() [2/2]

template<typename Payload >

template<auto MemberPtr>
requires HasDefaultCellWrapper< typename detail::member_pointer_traits<decltype(MemberPtr)>::field_type>

FieldsBuilder & parcel::FieldsBuilder< Payload >::field ( std::string  key )

inline

Declare a field with cell wrapper inferred via default_cell_for.

Available for any field type that has a default_cell_for specialization (every PrimitiveStorage type out of the box, plus std::vector, std::map, std::variant, and std::optional of those).

Template Parameters

MemberPtr

Pointer-to-member of Payload.

Parameters

key	JSON key for this field.

Returns

*this for chaining.

icon() [1/2]

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::icon ( comms::Icon  icon )

inline

Set the icon display info of the most recently declared field to the typed icon.

Parameters

icon	Icon value.

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

icon() [2/2]

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::icon ( std::string const &  v )

inline

Set the icon display info of the most recently declared field, parsing an Iconify set:name string (e.g.

"mdi:account").

Parameters

v	Iconify set:name identifier.

Returns

*this for chaining.

Exceptions

std::runtime_error	if called before any field<>().
std::invalid_argument	if v is not a valid set:name icon.

is_required()

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::is_required ( bool  v = true )

inline

Override the required flag of the most recently declared field.

Parameters

v	Whether the field must be present on deserialization.

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

name()

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::name ( std::string  v )

inline

Set the name display info of the most recently declared field.

Parameters

v	Display name.

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

optional()

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::optional ( )

inline

Shorthand for is_required(false).

Returns

*this for chaining.

Exceptions

std::runtime_error

if called before any field<>().

remove_field()

template<typename Payload >

FieldsBuilder & parcel::FieldsBuilder< Payload >::remove_field ( const std::string_view  key )

inline

Drop a previously declared (or inherited) field by key.

No-op if no field with key exists. Resets the "last declared field" pointer so a stray .name(...) / .optional() after remove_field throws instead of silently mutating an unrelated field.

Parameters

key	JSON key of the field to remove.

Returns

*this for chaining.

---

The documentation for this class was generated from the following file:

• include/parcel/struct.h