Class ArchiveObject¶

Defined in File archive.h

Inheritance Relationships¶

Derived Type¶

public portal::JsonArchive (Class JsonArchive)

Class Documentation¶

class ArchiveObject¶

Format-agnostic named-property serialization using the visitor pattern.

Intermediate object graph that can be serialized to JSON, XML, binary, etc. Uses named properties instead of ordered streams (see Serializer for stream-based alternative).

Use for: Config files, save games, human-readable formats, flexible schemas Avoid for: Network packets, performance-critical paths (use Serializer instead)

Supported types: Scalars, strings, GLM vectors, std::vector, std::map, enums (as strings), custom types, binary data

struct Config {
    void archive(ArchiveObject& ar) const {
        ar.add_property("name", name);
        ar.add_property("value", value);
    }
    static Config dearchive(ArchiveObject& ar) {
        Config c;
        ar.get_property("name", c.name);
        ar.get_property("value", c.value);
        return c;
    }
};

JsonArchive archive;
config.archive(archive);
archive.dump("config.json");

Subclassed by portal::JsonArchive

Public Types

using PropertyName = std::string_view¶

Public Functions

virtual ~ArchiveObject() = default¶

ArchiveObject() = default¶

ArchiveObject(const ArchiveObject &other) = default¶

ArchiveObject(ArchiveObject &&other) noexcept = default¶

ArchiveObject &operator=(const ArchiveObject &other) = default¶

ArchiveObject &operator=(ArchiveObject &&other) = default¶

void update(const ArchiveObject &other)¶

Merges properties from another ArchiveObject into this one.

Properties from the other object are copied into this object’s property map. If a property with the same name already exists, it will be replaced.

Parameters:: other – The source ArchiveObject containing properties to merge.

template<typename T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a scalar numeric property (integer or floating-point) to the archive.

Stores a copy of the scalar value with appropriate type metadata. Supports all integral types (int8_t through int64_t, unsigned variants) and floating-point types (float, double). Boolean values use a specialized template (see add_property<bool>).

Template Parameters:

T – Numeric type (integral or floating-point, excluding bool)

Parameters:

name – Property name identifier for serialization/deserialization
t – The scalar value to serialize

template<reflection::SmallVector T> inline void add_property(const PropertyName &name, const T &t)¶

Adds an llvm::SmallVector property to the archive.

Handles two cases:

If elements are Archiveable: Each element archives itself into a child ArchiveObject
Otherwise: Wraps each element in an ArchiveObject with property name “v” (maintains type uniformity)

Template Parameters:

T – SmallVector type satisfying reflection::SmallVector concept

Parameters:

name – Property name identifier
t – The SmallVector to serialize

template<reflection::Vector T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a std::vector property to the archive.

Handles two cases:

If elements are Archiveable: Each element archives itself into a child ArchiveObject
Otherwise: Wraps each element in an ArchiveObject with property name “v” (maintains type uniformity)

This dual approach enables serialization of both primitive types (int, float, string) and complex user-defined types in a consistent manner.

Template Parameters:

T – Vector type satisfying reflection::Vector concept (std::vector<…>)

Parameters:

name – Property name identifier
t – The vector to serialize

template<reflection::String T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a string property to the archive.

Handles std::string, std::string_view, and other types satisfying reflection::String concept. The string is copied with null terminator for safe deserialization.

Template Parameters:

T – String type satisfying reflection::String concept

Parameters:

name – Property name identifier
t – The string to serialize

template<reflection::GlmVec1 T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a GLM vec1 property (single-component vector).

Template Parameters:

T – GLM vec1 type (e.g., glm::vec1, glm::ivec1)

Parameters:

name – Property name identifier
t – The vector to serialize

template<reflection::GlmVec2 T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a GLM vec2 property (two-component vector).

Template Parameters:

T – GLM vec2 type (e.g., glm::vec2, glm::ivec2, glm::dvec2)

Parameters:

name – Property name identifier
t – The vector to serialize

template<reflection::GlmVec3 T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a GLM vec3 property (three-component vector).

Template Parameters:

T – GLM vec3 type (e.g., glm::vec3, glm::ivec3, glm::dvec3)

Parameters:

name – Property name identifier
t – The vector to serialize

template<reflection::GlmVec4 T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a GLM vec4 property (four-component vector).

Template Parameters:

T – GLM vec4 type (e.g., glm::vec4, glm::ivec4, glm::dvec4)

Parameters:

name – Property name identifier
t – The vector to serialize

template<reflection::Map T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a map property with string-convertible keys.

Creates a child ArchiveObject and populates it with key-value pairs from the map. Keys must be convertible to std::string_view. Values are serialized recursively.

Template Parameters:

T – Map type (std::unordered_map, std::map, etc.) with string-like keys

Parameters:

name – Property name identifier
t – The map to serialize

template<typename T> inline void add_property(const PropertyName &name, const T &e)

Adds an enum property serialized as a string.

Uses portal::to_string() to convert the enum to its string representation, making the serialized format human-readable. Deserialization uses portal::from_string().

Template Parameters:

T – Enum type

Parameters:

name – Property name identifier
e – The enum value to serialize

void add_property(const PropertyName &name, const char *t)¶

Adds a C-string property.

Parameters:

name – Property name identifier
t – Null-terminated C-string

void add_property(const PropertyName &name, const std::filesystem::path &t)¶

Adds a filesystem path property.

Parameters:

name – Property name identifier
t – Filesystem path

void add_property(const PropertyName &name, const StringId &string_id)¶

inline void add_binary_block(const PropertyName &name, const std::vector<std::byte> &data)¶

Adds a binary data block property from a byte vector.

Stores arbitrary binary data that doesn’t fit standard types (images, compressed data, etc.). The data is copied internally and marked with PropertyType::binary for special handling during serialization (e.g., base64 encoding in JSON).

Parameters:

name – Property name identifier
data – Binary data as a vector of bytes

inline void add_binary_block(const PropertyName &name, const Buffer &buffer)¶

Adds a binary data block property from a Buffer.

Parameters:

name – Property name identifier
buffer – Buffer containing the binary data (will be copied)

template<ArchiveableConcept T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a custom Archiveable type as a nested property.

Creates a child ArchiveObject and calls the type’s archive() method to populate it. This enables hierarchical serialization of user-defined types.

Template Parameters:

T – Type satisfying the Archiveable concept

Parameters:

name – Property name identifier
t – The object to serialize

template<ExternalArchiveableConcept T> inline void add_property(const PropertyName &name, const T &t)¶

Adds a type with an Archivable<T> specialization as a nested property.

Creates a child ArchiveObject and calls Archivable<T>::archive() to populate it. This enables non-intrusive hierarchical serialization of external types.

Template Parameters:

T – Type satisfying the ExternalArchiveableConcept

Parameters:

name – Property name identifier
t – The object to serialize

template<typename T> inline void add_property(const PropertyName &name, const T &t)

Adds a property using glaze reflection for types with reflection metadata.

Automatically serializes types that have glaze reflection metadata defined. Uses compile-time reflection to extract field names and values, creating a nested ArchiveObject with each field as a named property. Fallback overload for types that don’t implement archive() but have glaze metadata.

Template Parameters:

T – Type with glaze reflection metadata (glz::reflect)

Parameters:

name – Property name identifier
t – The object to serialize

template<typename T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves an enum property deserialized from its string representation.

Reads the property as a string and converts it back to the enum using portal::from_string().

Template Parameters:

T – Enum type

Parameters:

name – Property name identifier
out – Output parameter to store the enum value

Returns:

true if property exists and conversion succeeds, false otherwise

template<typename T> inline bool get_property(const PropertyName &name, T &out)

Retrieves an integral property value.

Reads a scalar integer value (int8_t through int64_t, unsigned variants).

Template Parameters:

T – Integral type (excluding bool)

Parameters:

name – Property name identifier
out – Output parameter to store the value

Returns:

true if property exists and type matches, false otherwise

template<typename T> inline bool get_property(const PropertyName &name, T &out)

Retrieves a floating-point property value with automatic float/double conversion.

Handles JSON’s ambiguity between float and double by automatically converting between the two when necessary.

Template Parameters:

T – Floating-point type (float or double)

Parameters:

name – Property name identifier
out – Output parameter to store the value

Returns:

true if property exists and is numeric, false otherwise

template<reflection::Vector T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a std::vector property.

Clears the output vector and populates it with elements from the archived array. Handles both primitive element types and Archiveable custom types.

Template Parameters:

T – Vector type satisfying reflection::Vector concept

Parameters:

name – Property name identifier
out – Output vector to populate

Returns:

true if property exists and is an array, false otherwise

template<reflection::SmallVector T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves an llvm::SmallVector property.

Clears the output SmallVector and populates it with elements from the archived array.

Template Parameters:

T – SmallVector type satisfying reflection::SmallVector concept

Parameters:

name – Property name identifier
out – Output SmallVector to populate

Returns:

true if property exists and is an array, false otherwise

template<reflection::String T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a string property.

Handles both null-terminated and length-prefixed string storage.

Template Parameters:

T – String type satisfying reflection::String concept

Parameters:

name – Property name identifier
out – Output string to populate

Returns:

true if property exists and is a string, false otherwise

template<reflection::GlmVec1 T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a GLM vec1 property (single-component vector).

Template Parameters:

T – GLM vec1 type (e.g., glm::vec1, glm::ivec1)

Parameters:

name – Property name identifier
out – Output parameter to store the vector

Returns:

true if property exists and is a 1-component vector, false otherwise

template<reflection::GlmVec2 T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a GLM vec2 property (two-component vector).

Template Parameters:

T – GLM vec2 type (e.g., glm::vec2, glm::ivec2, glm::dvec2)

Parameters:

name – Property name identifier
out – Output parameter to store the vector

Returns:

true if property exists and is a 2-component vector, false otherwise

template<reflection::GlmVec3 T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a GLM vec3 property (three-component vector).

Template Parameters:

T – GLM vec3 type (e.g., glm::vec3, glm::ivec3, glm::dvec3)

Parameters:

name – Property name identifier
out – Output parameter to store the vector

Returns:

true if property exists and is a 3-component vector, false otherwise

template<reflection::GlmVec4 T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a GLM vec4 property (four-component vector).

Template Parameters:

T – GLM vec4 type (e.g., glm::vec4, glm::ivec4, glm::dvec4)

Parameters:

name – Property name identifier
out – Output parameter to store the vector

Returns:

true if property exists and is a 4-component vector, false otherwise

template<reflection::Map T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a map property with string-convertible keys.

Clears the output map and populates it with key-value pairs from the child ArchiveObject. Handles both primitive value types and Dearchiveable custom types.

Template Parameters:

T – Map type (std::unordered_map, std::map, etc.) with string-like keys

Parameters:

name – Property name identifier
out – Output map to populate

Returns:

true if property exists and is an object, false otherwise

template<ArchiveableConcept T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a custom Archiveable type from a nested property.

Gets the child ArchiveObject and calls the type’s static dearchive() method to reconstruct it.

Template Parameters:

T – Type satisfying the Archiveable concept

Parameters:

name – Property name identifier
out – Output parameter to store the dearchived object

Returns:

true if property exists and is an object, false otherwise

template<ExternalDearchiveableConcept T> inline bool get_property(const PropertyName &name, T &out)¶

Retrieves a type with an Archivable<T> specialization from a nested property.

Gets the child ArchiveObject and calls Archivable<T>::dearchive() to reconstruct it. This enables non-intrusive deserialization of external types.

Template Parameters:

T – Type satisfying the ExternalDearchiveableConcept

Parameters:

name – Property name identifier
out – Output parameter to store the dearchived object

Returns:

true if property exists and is an object, false otherwise

bool get_property(const PropertyName &name, std::filesystem::path &out)¶

Retrieves a filesystem path property.

Parameters:

name – Property name identifier
out – Output parameter to store the path

Returns:

true if property exists, false otherwise

bool get_property(const PropertyName &name, StringId &out)¶

inline bool get_binary_block(const PropertyName &name, Buffer &buffer)¶

Retrieves a binary data block property into a Buffer.

Parameters:

name – Property name identifier
buffer – Output Buffer to receive a copy of the binary data

Returns:

true if the property exists and is binary type, false otherwise

inline bool get_binary_block(const PropertyName &name, std::vector<std::byte> &data)¶

Retrieves a binary data block property into a byte vector.

Parameters:

name – Property name identifier
data – Output vector to receive the binary data

Returns:

true if the property exists and is binary type, false otherwise

template<typename T> inline bool get_property(const PropertyName &name, T &t)

Retrieves a property using glaze reflection for types with reflection metadata.

Automatically deserializes types that have glaze reflection metadata defined. Uses compile-time reflection to extract field names and populate each field from the nested ArchiveObject. Fallback overload for types that don’t implement dearchive() but have glaze metadata.

Template Parameters:

T – Type with glaze reflection metadata (glz::reflect)

Parameters:

name – Property name identifier
t – Output parameter to populate with deserialized values

Returns:

true if property exists and all fields were read, false otherwise

virtual ArchiveObject *create_child(PropertyName name)¶

Creates a new child ArchiveObject and adds it as a property.

Creates a nested ArchiveObject for hierarchical serialization. Used internally by add_property() when serializing Archiveable types or maps. The child becomes owned by this ArchiveObject and is stored in the property map.

Parameters:: name – Property name for the child object
Returns:: Pointer to the newly created child ArchiveObject (non-owning)

virtual ArchiveObject *get_object(PropertyName name) const¶

Retrieves a child ArchiveObject by name.

Used during deserialization to access nested objects. Returns null if no child with the given name exists.

Parameters:: name – Property name of the child object
Returns:: Pointer to the child ArchiveObject, or nullptr if not found

inline auto begin()¶

inline auto end()¶

inline auto begin() const¶

inline auto end() const¶

template<> inline void add_property(const PropertyName &name, const bool &b)¶

template<> inline void add_property(const PropertyName &name, const uint128_t &t)¶

template<> inline bool get_property(const PropertyName &name, bool &out)¶

template<> inline bool get_property(const PropertyName &name, uint128_t &out)¶

Protected Functions

template<typename T, typename ValueType> inline bool format_array(const PropertyName &name, const reflection::Property &prop, T &out) const¶

virtual reflection::Property &get_property_from_map(PropertyName name)¶

virtual const reflection::Property &get_property_from_map(PropertyName name) const¶

virtual reflection::Property &add_property_to_map(PropertyName name, reflection::Property &&property)¶

Protected Attributes

llvm::StringMap<reflection::Property> property_map¶

Friends

friend class JsonArchive