CRTP base for user-defined struct cells. More...

#include <struct.h>

Inheritance diagram for parcel::StructCell< Derived, Payload, StructId >:

[legend]

Collaboration diagram for parcel::StructCell< Derived, Payload, StructId >:

[legend]

Public Member Functions
std::string	to_string () const override
	Render the cell's value as a compact human-readable string.

json_t	to_json () const override
	Default JSON serialization for cells with JSON-convertible storage.

cell_t	clone () const override
	Deep-copy this cell.

std::partial_ordering	compare (ICell const &other) const override
	Three-way comparison over field values (and `extras` when `allow_extra_fields` is true); ignores display info.

Public Member Functions inherited from parcel::BaseCell< Derived, Payload >
	explicit (false) BaseCell(U &&v)
	Construct by forwarding into the storage (`v` becomes `Storage::value`).

Derived &	operator= (U &&v)
	Assign to the storage from `v`.

Payload &	get ()
	Mutable access to the held storage.

Payload const &	get () const
	Read-only access to the held storage.

void	inject_display_info (json_t &j) const
	Copy this cell's display info (if any) into the JSON object under `"d"`.

Public Member Functions inherited from parcel::ICell
virtual std::string	to_formatted_string () const
	Render the cell as a multi-line, indented string.

virtual std::size_t	hash_value () const noexcept
	Equality-consistent hash that mirrors `compare`'s display-info-insensitivity.

cell_t	with_display_info (DisplayInfo m) const
	Return a deep copy with the entire display info block replaced.

cell_t	with_name (std::string v) const
	Return a deep copy with `name` set to `v`.

cell_t	with_description (std::string v) const
	Return a deep copy with `description` set to `v`.

cell_t	with_icon (comms::Icon icon) const
	Return a deep copy with `icon` set to the typed `icon`.

cell_t	with_icon (std::string const &v) const
	Return a deep copy with `icon` parsed from an Iconify `set:name` string (e.g.

cell_t	with_color (comms::Color color) const
	Return a deep copy with `color` set to the typed `color`.

cell_t	with_color (std::string const &v) const
	Return a deep copy with `color` parsed from a color string (hex like `"#ffcc00"`, a CSS-functional form, or a CSS color name).

Static Public Member Functions
static DisplayInfo	display_info ()
	Default cell-level display info (empty).

static cell_t	from_json (json_t const &j, ParcelRegistry const &reg)
	Deserialize the struct cell from JSON.

static cell_type_descriptor_t	descriptor ()
	Cached descriptor for this struct cell.

Static Public Member Functions inherited from parcel::BaseCell< Derived, Payload >
static std::shared_ptr< Derived >	of (Args &&... args)
	Construct a `shared_ptr<Derived>` forwarding the arguments.

static std::unique_ptr< Derived >	unique (Args &&... args)
	Construct a `unique_ptr<Derived>` forwarding the arguments.

static void	absorb_display_info (json_t const &j, Out &out)
	Read `"d"` (if present) from a JSON object and assign it onto a cell.

static cell_t	from_json_strict (json_t const &j)
	Strict shorthand for the recurring `cell_from_json + make_shared.`

Public Attributes
std::map< std::string, cell_t >	extras
	Unknown keys retained when `Derived::allow_extra_fields` is true.

Public Attributes inherited from parcel::BaseCell< Derived, Payload >
Payload	value
	Held value of the cell.

Static Public Attributes
static constexpr bool	allow_extra_fields = false
	Whether unknown JSON keys are tolerated.

static constexpr std::string_view	struct_id = StructId.view()
	Bare struct id, lifted from the `StructId` template arg.

static constexpr std::string_view	kind_id = id_join_lit_v<"s:", StructId>
	Wire kind id of this struct cell (`"s:" + struct_id`).

Static Public Attributes inherited from parcel::ICell
static constexpr std::string_view	KEY_KIND = "k"
	JSON key for the kind id (`"k"`).

static constexpr std::string_view	KEY_VALUE = "v"
	JSON key for the value payload (`"v"`).

static constexpr std::string_view	KEY_DESCRIPTION = "d"
	JSON key for the optional display info block (`"d"`).

Additional Inherited Members
Static Protected Member Functions inherited from parcel::BaseCell< Derived, Payload >
static T	cell_from_json (const json_t &j, const std::string_view expected_kind)
	Validate a wrapped `{"k","v"}` JSON object and extract its `"v"` as `T`.

Protected Attributes inherited from parcel::BaseCell< Derived, Payload >
std::optional< DisplayInfo >	display_info_
	Optional display info; omitted from JSON when empty.

Detailed Description

template<typename Derived, typename Payload, FixedString StructId>
class parcel::StructCell< Derived, Payload, StructId >

CRTP base for user-defined struct cells.

Concrete Derived declares its bare struct id as the third template argument; StructCell synthesizes the wire kind_id as "s:" + StructId so user-defined struct kinds always live in the "s:" namespace and never collide with primitive (i32) or container (l:, m:, u:) kinds.

class PersonCell : public parcel::StructCell<PersonCell, Person, "person"> {
    using StructCell::StructCell;
    // PersonCell::struct_id == "person"
    // PersonCell::kind_id   == "s:person"
};

The concrete Derived must additionally provide:

static auto field_descriptors() — built via FieldsBuilder<Payload>.
(optional) static DisplayInfo display_info() — cell-level display info; defaults to an empty DisplayInfo{} when not declared.
(optional) static constexpr bool allow_extra_fields — defaults to false.

Wire shape:

{"k": "s:<name>", "v": {"<field>": <wrapped cell>, …}}

Each field is itself a fully wrapped cell. When allow_extra_fields is true, unknown keys are kept in extras as registry-dispatched cells; otherwise unknown keys cause from_json to throw.

Template Parameters

Derived	The concrete struct cell.
Payload	The plain payload struct.
StructId	Bare struct id (no `"s:"` prefix); the prefix is added by the framework.

See also: FieldsBuilder; StructCellTypeDescriptor

Member Function Documentation

◆ clone()

template<typename Derived , typename Payload , FixedString StructId>

cell_t parcel::StructCell< Derived, Payload, StructId >::clone ( ) const

inlineoverridevirtual

Deep-copy this cell.

Returns: A new cell_t whose state is independent of the original.

Reimplemented from parcel::BaseCell< Derived, Payload >.

◆ compare()

template<typename Derived , typename Payload , FixedString StructId>

std::partial_ordering parcel::StructCell< Derived, Payload, StructId >::compare ( ICell const & other ) const

inlineoverridevirtual

Three-way comparison over field values (and extras when allow_extra_fields is true); ignores display info.

Walks declared fields in the order returned by field_descriptors(), delegating each comparison to the field descriptor's typed compare(Payload const&, Payload const&) hook (so e.g. nested struct cells go through their own field-by-field compare instead of a JSON projection). Short-circuits on the first non-equal result.

Optional fields follow std::optional's <=> (absent < present; both absent is equivalent). When allow_extra_fields is true, after declared fields agree the extras maps are compared lexicographically by key, with ICell <=> resolving each value pair (a null cell ranks before a non-null one).

Reimplemented from parcel::BaseCell< Derived, Payload >.

◆ descriptor()

template<typename Derived , typename Payload , FixedString StructId>

static cell_type_descriptor_t parcel::StructCell< Derived, Payload, StructId >::descriptor ( )

inlinestatic

Cached descriptor for this struct cell.

Returns: Shared StructCellTypeDescriptor<Derived, Payload> instance.

◆ display_info()

template<typename Derived , typename Payload , FixedString StructId>

static DisplayInfo parcel::StructCell< Derived, Payload, StructId >::display_info ( )

inlinestatic

Default cell-level display info (empty).

Concrete Derived types may shadow this with their own static DisplayInfo display_info() (e.g. to set a display name); when omitted, an empty DisplayInfo{} is used.

◆ from_json()

template<typename Derived , typename Payload , FixedString StructId>

static cell_t parcel::StructCell< Derived, Payload, StructId >::from_json	(	json_t const &	j,
		ParcelRegistry const &	reg
	)

inlinestatic

Deserialize the struct cell from JSON.

Each declared field is read in order; missing required fields throw. Unknown keys throw unless Derived::allow_extra_fields is true, in which case they are routed through the registry into extras.

Parameters

j	Input JSON object — must match `{"k": kind_id, "v": {…}}`.
reg	Registry used to dispatch nested cells.

Returns: Newly built cell handle.

Exceptions

std::runtime_error on shape or kind mismatch, missing required field, or unknown key when extras are not allowed.

◆ to_json()

template<typename Derived , typename Payload , FixedString StructId>

json_t parcel::StructCell< Derived, Payload, StructId >::to_json ( ) const

inlineoverridevirtual

Default JSON serialization for cells with JSON-convertible storage.

If Storage has a JSON adapter, emits {"k": kind_id, "v": value, optional "d": display info}. Otherwise the call throws — the derived cell must override to_json itself (ListCell, MapCell, etc.).

Returns: JSON object representation.

Exceptions

std::runtime_error if Storage is not JSON-convertible.

Reimplemented from parcel::BaseCell< Derived, Payload >.

◆ to_string()

template<typename Derived , typename Payload , FixedString StructId>

std::string parcel::StructCell< Derived, Payload, StructId >::to_string ( ) const

inlineoverridevirtual

Render the cell's value as a compact human-readable string.

Returns: String form — implementation-defined per cell type.

Implements parcel::ICell.

Member Data Documentation

◆ allow_extra_fields

template<typename Derived , typename Payload , FixedString StructId>

constexpr bool parcel::StructCell< Derived, Payload, StructId >::allow_extra_fields = false

staticconstexpr

Whether unknown JSON keys are tolerated.

Concrete Derived types may shadow this with true to opt into lenient deserialization; the default is strict (false).

◆ kind_id

template<typename Derived , typename Payload , FixedString StructId>

constexpr std::string_view parcel::StructCell< Derived, Payload, StructId >::kind_id = id_join_lit_v<"s:", StructId>

staticconstexpr

Wire kind id of this struct cell ("s:" + struct_id).

Synthesized at compile time from the StructId template argument. The "s:" prefix is framework-enforced — concrete struct cells never declare kind_id directly.

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

include/parcel/struct.h

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ clone()

◆ compare()

◆ descriptor()

◆ display_info()

◆ from_json()

◆ to_json()

◆ to_string()

Member Data Documentation

◆ allow_extra_fields

◆ kind_id