#include <Serializable.h>

Inheritance diagram for ne::Serializable:

Public Member Functions
std::optional< Error >	serialize (std::filesystem::path pathToFile, bool bEnableBackup, const std::unordered_map< std::string, std::string > &customAttributes={})

std::variant< std::string, Error >	serialize (toml::value &tomlData, const std::string &sEntityId="", const std::unordered_map< std::string, std::string > &customAttributes={}, const std::optional< std::filesystem::path > &optionalPathToFile={}, bool bEnableBackup=false)

std::variant< std::string, Error >	serialize (toml::value &tomlData, Serializable *pOriginalObject, std::string sEntityId="", const std::unordered_map< std::string, std::string > &customAttributes={}, const std::optional< std::filesystem::path > &optionalPathToFile={}, bool bEnableBackup=false)

std::optional< std::pair< std::string, std::string > >	getPathDeserializedFromRelativeToRes () const

Static Public Member Functions
static std::variant< std::pair< std::set< std::string >, toml::value >, Error >	getIdsFromFile (std::filesystem::path pathToFile)

static std::optional< Error >	serializeMultiple (std::filesystem::path pathToFile, std::vector< SerializableObjectInformation > vObjects, bool bEnableBackup)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserialize (const std::filesystem::path &pathToFile)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserialize (const std::filesystem::path &pathToFile, std::unordered_map< std::string, std::string > &customAttributes)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserialize (std::filesystem::path pathToFile, std::unordered_map< std::string, std::string > &customAttributes, const std::string &sEntityId)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserialize (const std::filesystem::path &pathToFile, const std::string &sEntityId)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::same_as<SmartPointer, sgc::GcPtr<Serializable>> \|\| std::same_as<SmartPointer, std::unique_ptr<Serializable>>
static std::variant< std::vector< DeserializedObjectInformation< SmartPointer > >, Error >	deserializeMultiple (std::filesystem::path pathToFile)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserialize (const toml::value &tomlData, std::unordered_map< std::string, std::string > &customAttributes, std::string sEntityId="", const std::optional< std::filesystem::path > &optionalPathToFile={})

Protected Member Functions
virtual void	onAfterDeserialized ()

Static Private Member Functions
static std::optional< Error >	resolvePathToToml (std::filesystem::path &pathToFile)

static const rfk::Class *	getClassForGuid (const std::string &sGuid)

static const rfk::Struct *	getClassForGuid (const rfk::Struct *pArchetypeToAnalyze, const std::string &sGuid)

template<typename SmartPointer , typename InnerType = typename SmartPointer::element_type> requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> \|\| std::same_as<SmartPointer, std::unique_ptr<InnerType>>)
static std::variant< SmartPointer, Error >	deserializeFromSection (const toml::value &tomlData, std::unordered_map< std::string, std::string > &customAttributes, const std::string &sSectionName, const std::string &sTypeGuid, const std::string &sEntityId, const std::optional< std::filesystem::path > &optionalPathToFile)

Private Attributes
std::optional< std::pair< std::string, std::string > >	pathDeserializedFromRelativeToRes

Static Private Attributes
static const auto	sSubEntityFieldNameKey = ".field_name"

static const auto	sPathRelativeToResKey = ".path_relative_to_res"

static const auto	sNothingToSerializeKey = ".none"

static constexpr std::string_view	sCustomAttributePrefix = ".."

Friends
class	SerializableObjectFieldSerializer

Detailed Description

Adds support for serialization/deserialization for your reflected type.

Inherit your class/struct from this class to add functions which will serialize the type and reflected fields (even inherited) that are marked with special properties.

Member Function Documentation

◆ deserialize() [1/5]

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserialize ( const std::filesystem::path & pathToFile )

static

Deserializes an object and all reflected fields (including inherited) from a file. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: You can use either sgc::GcPtr or std::unique_ptr as a smart pointer for deserialized object.

Parameters

pathToFile File to read reflected data from. The ".toml" extension will be added automatically if not specified in the path.

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserialize() [2/5]

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserialize	(	const std::filesystem::path &	pathToFile,
		const std::string &	sEntityId
	)

static

Deserializes an object and all reflected fields (including inherited) from a file. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: This is an overloaded function, see a more detailed documentation for the other overload.

Parameters

pathToFile	File to read reflected data from. The ".toml" extension will be added automatically if not specified in the path.
sEntityId	Unique ID of this object. When serializing multiple objects into one toml value provide different IDs for each object so they could be differentiated.

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserialize() [3/5]

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserialize	(	const std::filesystem::path &	pathToFile,
		std::unordered_map< std::string, std::string > &	customAttributes
	)

static

Deserializes an object and all reflected fields (including inherited) from a file. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: This is an overloaded function, see a more detailed documentation for the other overload.

Parameters

pathToFile	File to read reflected data from. The ".toml" extension will be added automatically if not specified in the path.
customAttributes	Pairs of values that were associated with this object.

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserialize() [4/5]

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserialize	(	const toml::value &	tomlData,
		std::unordered_map< std::string, std::string > &	customAttributes,
		std::string	sEntityId = `""`,
		const std::optional< std::filesystem::path > &	optionalPathToFile = `{}`
	)

static

Deserializes an object and all reflected fields (including inherited) from a toml value. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: This is an overloaded function, see a more detailed documentation for the other overload.

Parameters

tomlData	Toml value to retrieve an object from.
customAttributes	Pairs of values that were associated with this object.
sEntityId	Unique ID of this object. When serializing multiple objects into one toml value provide different IDs for each object so they could be differentiated.
optionalPathToFile	Optional. Path to the file that this TOML data is deserialized from. Used for fields marked as `Serialize(AsExternal)`

Warning: Don't use dots in the entity ID, dots are used in recursion when this function is called from this function to process reflected field (sub entity).

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserialize() [5/5]

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserialize	(	std::filesystem::path	pathToFile,
		std::unordered_map< std::string, std::string > &	customAttributes,
		const std::string &	sEntityId
	)

static

Deserializes an object and all reflected fields (including inherited) from a file. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: This is an overloaded function, see a more detailed documentation for the other overload.

Parameters

pathToFile	File to read reflected data from. The ".toml" extension will be added automatically if not specified in the path.
customAttributes	Pairs of values that were associated with this object.
sEntityId	Unique ID of this object. When serializing multiple objects into one toml value provide different IDs for each object so they could be differentiated.

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserializeFromSection()

template<typename SmartPointer , typename InnerType >
requires std::derived_from<InnerType, Serializable> && (std::same_as<SmartPointer, sgc::GcPtr<InnerType>> || std::same_as<SmartPointer, std::unique_ptr<InnerType>>)

std::variant< SmartPointer, Error > ne::Serializable::deserializeFromSection	(	const toml::value &	tomlData,
		std::unordered_map< std::string, std::string > &	customAttributes,
		const std::string &	sSectionName,
		const std::string &	sTypeGuid,
		const std::string &	sEntityId,
		const std::optional< std::filesystem::path > &	optionalPathToFile
	)

staticprivate

Deserializes an object and all reflected fields (including inherited) from a file. Specify the type of an object (that is located in the file) as the T template parameter, which can be entity's actual type or entity's parent (up to Serializable).

Remarks: This is an overloaded function, see a more detailed documentation for the other overload.

Parameters

tomlData	Toml value to retrieve an object from.
customAttributes	Pairs of values that were associated with this object.
sSectionName	Name of the TOML section to deserialize.
sTypeGuid	GUID of the type to deserialize (taken from section name).
sEntityId	Entity ID chain string.
optionalPathToFile	Optional. Path to the file that this TOML data is deserialized from. Used for fields marked as `Serialize(AsExternal)`

Returns: Error if something went wrong, otherwise a pointer to deserialized object.

◆ deserializeMultiple()

template<typename SmartPointer , typename InnerType >
requires std::same_as<SmartPointer, sgc::GcPtr<Serializable>> || std::same_as<SmartPointer, std::unique_ptr<Serializable>>

std::variant< std::vector< DeserializedObjectInformation< SmartPointer > >, Error > ne::Serializable::deserializeMultiple ( std::filesystem::path pathToFile )

static

Deserializes multiple objects and their reflected fields (including inherited) from a file.

Parameters

pathToFile File to read reflected data from. The ".toml" extension will be added automatically if not specified in the path.

Returns: Error if something went wrong, otherwise an array of pointers to deserialized objects.

◆ getClassForGuid() [1/2]

const rfk::Struct * ne::Serializable::getClassForGuid	(	const rfk::Struct *	pArchetypeToAnalyze,
		const std::string &	sGuid
	)

staticprivate

Looks for all children of the specified archetype to find a type that has the specified GUID.

Parameters

pArchetypeToAnalyze	Type which children to analyze.
sGuid	GUID to look for.

Returns: nullptr if not found, otherwise valid pointer.

◆ getClassForGuid() [2/2]

const rfk::Class * ne::Serializable::getClassForGuid ( const std::string & sGuid )

staticprivate

Returns archetype for the specified GUID.

Parameters

sGuid GUID to look for.

Returns: nullptr if not found, otherwise valid pointer.

◆ getIdsFromFile()

std::variant< std::pair< std::set< std::string >, toml::value >, Error > ne::Serializable::getIdsFromFile ( std::filesystem::path pathToFile )

static

Analyzes the file for serialized objects, gathers and returns unique IDs of those objects.

Parameters

pathToFile File to read serialized data from. The ".toml" extension will be added automatically if not specified in the path.

Returns: Error if something went wrong, otherwise array of unique IDs of objects that exist in the specified file and parsed TOML data that you can reuse.

◆ getPathDeserializedFromRelativeToRes()

std::optional< std::pair< std::string, std::string > > ne::Serializable::getPathDeserializedFromRelativeToRes ( ) const

If this object was deserialized from a file that is located in the res directory of this project, returns a pair of values:

path to this file relative to the res directory,
unique ID of this object in this file.

This path will never point to a backup file and will always point to the original file (even if the backup file was used in deserialization).

Example: say this object is deserialized from the file located at .../res/game/test.toml, this value will be equal to the following pair: {game/test.toml, some.id}.

Returns: Empty if this object was not deserialized previously, otherwise path to the file that was used in deserialization relative to the res directory.

◆ onAfterDeserialized()

virtual void ne::Serializable::onAfterDeserialized ( )

inlineprotectedvirtual

Called after the object was successfully deserialized. Used to execute post-deserialization logic.

Warning: If overriding you must call the parent's version of this function first (before executing your login) to execute parent's logic.

Reimplemented in ne::DirectionalLightNode, ne::PointLightNode, ne::SpotlightNode, ne::MeshNode, ne::SpatialNode, ne::Material, and ne::RenderSettings.

◆ resolvePathToToml()

std::optional< Error > ne::Serializable::resolvePathToToml ( std::filesystem::path & pathToFile )

staticprivate

Adds ".toml" extension to the path (if needed) and copies a backup file to the specified path if the specified path does not exist but there is a backup file.

Parameters

pathToFile Path to toml file (may point to non-existing path or don't have ".toml" extension).

Returns: Error if something went wrong.

◆ serialize() [1/3]

std::optional< Error > ne::Serializable::serialize	(	std::filesystem::path	pathToFile,
		bool	bEnableBackup,
		const std::unordered_map< std::string, std::string > &	customAttributes = `{}`
	)

Serializes the object and all reflected fields (including inherited) that are marked with ne::Serialize property into a file. Serialized object can later be deserialized using deserialize.

Parameters

pathToFile	File to write reflected data to. The ".toml" extension will be added automatically if not specified in the path. If the specified file already exists it will be overwritten. If the directories of the specified file do not exist they will be recursively created.
bEnableBackup	If 'true' will also use a backup (copy) file. deserialize can use backup file if the original file does not exist. Generally you want to use a backup file if you are saving important information, such as player progress, other cases such as player game settings and etc. usually do not need a backup but you can use it if you want.
customAttributes	Optional. Custom pairs of values that will be saved as this object's additional information and could be later retrieved in deserialize.

Remarks

If file's parent directories do no exist they will be created.

In order for a field to be serialized with the object, you need to mark it with ne::Serialize property like so:

using namespace ne;
RPROPERTY(Serialize)
int iMyValue = 0;

Note that not all reflected fields can be serialized, only specific types can be serialized. Const fields, pointer fields, lvalue references, rvalue references and C-arrays will always be ignored and will not be serialized (no error returned). Supported for serialization types are:

bool
int
unsigned int
long long
unsigned long long
float
double
std::string
T (where T is any type that derives from Serializable)
and more, see io/serializers directory for available field serializers (you don't need to use them directly, they will be automatically picked inside of this function).

Returns: Error if something went wrong, for example when found an unsupported for serialization reflected field.

◆ serialize() [2/3]

std::variant< std::string, Error > ne::Serializable::serialize	(	toml::value &	tomlData,
		const std::string &	sEntityId = `""`,
		const std::unordered_map< std::string, std::string > &	customAttributes = `{}`,
		const std::optional< std::filesystem::path > &	optionalPathToFile = `{}`,
		bool	bEnableBackup = `false`
	)

Serializes the object and all reflected fields (including inherited) into a toml value.

Remarks: This is an overloaded function. See full documentation for other overload.

Parameters

tomlData	Toml value to append this object to.
sEntityId	Unique ID of this object. When serializing multiple objects into one toml value provide different IDs for each object so they could be differentiated. Don't use dots in the entity ID, dots are used in recursion when this function is called from this function to process reflected field (sub entity).
customAttributes	Optional. Custom pairs of values that will be saved as this object's additional information and could be later retrieved in deserialize.
optionalPathToFile	Optional. Path to the file that this TOML data will be serialized. Used for fields marked as `Serialize(AsExternal)`.
bEnableBackup	Optional. If this TOML data will be serialized to file whether the backup file is needed or not. Used for fields marked as `Serialize(AsExternal)`.

Returns: Error if something went wrong, for example when found an unsupported for serialization reflected field, otherwise name of the section that was used to store this entity.

◆ serialize() [3/3]

std::variant< std::string, Error > ne::Serializable::serialize	(	toml::value &	tomlData,
		Serializable *	pOriginalObject,
		std::string	sEntityId = `""`,
		const std::unordered_map< std::string, std::string > &	customAttributes = `{}`,
		const std::optional< std::filesystem::path > &	optionalPathToFile = `{}`,
		bool	bEnableBackup = `false`
	)

Serializes the object and all reflected fields (including inherited) into a toml value.

Remarks: This is an overloaded function that takes an original object to serialize only changed values. See full documentation for other overload.

Parameters

tomlData	Toml value to append this object to.
pOriginalObject	Optional. Original object of the same type as the object being serialized, this object is a deserialized version of the object being serialized, used to compare serializable fields' values and only serialize changed values.
sEntityId	Unique ID of this object. When serializing multiple objects into one toml value provide different IDs for each object so they could be differentiated. Don't use dots in the entity ID, dots are used in recursion when this function is called from this function to process reflected field (sub entity).
customAttributes	Optional. Custom pairs of values that will be saved as this object's additional information and could be later retrieved in deserialize.
optionalPathToFile	Optional. Path to the file that this TOML data will be serialized. Used for fields marked as `Serialize(AsExternal)`.
bEnableBackup	Optional. If this TOML data will be serialized to file whether the backup file is needed or not. Used for fields marked as `Serialize(AsExternal)`.

Returns: Error if something went wrong, for example when found an unsupported for serialization reflected field, otherwise name of the section that was used to store this entity.

◆ serializeMultiple()

std::optional< Error > ne::Serializable::serializeMultiple	(	std::filesystem::path	pathToFile,
		std::vector< SerializableObjectInformation >	vObjects,
		bool	bEnableBackup
	)

static

Serializes multiple objects, their reflected fields (including inherited) and provided custom attributes (if any) into a file.

Parameters

pathToFile	File to write reflected data to. The ".toml" extension will be added automatically if not specified in the path. If the specified file already exists it will be overwritten.
vObjects	Array of objects to serialize, their unique IDs (so they could be differentiated in the file) and custom attributes (if any). Don't use dots in the entity IDs, dots are used internally.
bEnableBackup	If 'true' will also use a backup (copy) file. deserialize can use backup file if the original file does not exist. Generally you want to use a backup file if you are saving important information, such as player progress, other cases such as player game settings and etc. usually do not need a backup but you can use it if you want.

Returns: Error if something went wrong, for example when found an unsupported for serialization reflected field.

Member Data Documentation

◆ pathDeserializedFromRelativeToRes

std::optional<std::pair<std::string, std::string> > ne::Serializable::pathDeserializedFromRelativeToRes

private

If this object was deserialized from a file that is located in the res directory of this project, this field will contain a pair of values:

path to this file relative to the res directory,
unique ID of this object in this file.

This path will never point to a backup file and will always point to the original file (even if the backup file was used in deserialization).

Example: say this object is deserialized from the file located at .../res/game/test.toml, this value will be equal to game/test.toml.

◆ sCustomAttributePrefix

constexpr std::string_view ne::Serializable::sCustomAttributePrefix = ".."

staticconstexprprivate

Text that we add to custom (user-specified) attributes in TOML files.

◆ sNothingToSerializeKey

const auto ne::Serializable::sNothingToSerializeKey = ".none"

inlinestaticprivate

Name of the key which we use when there is nothing to serialize.

◆ sPathRelativeToResKey

const auto ne::Serializable::sPathRelativeToResKey = ".path_relative_to_res"

inlinestaticprivate

Name of the key which we use when we serialize an object that was previously deserialized from the res directory.

◆ sSubEntityFieldNameKey

const auto ne::Serializable::sSubEntityFieldNameKey = ".field_name"

inlinestaticprivate

Name of the key in which to store name of the field a section represents.

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

src/engine_lib/public/io/Serializable.h
src/engine_lib/private/io/Serializable.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Function Documentation

◆ deserialize() [1/5]

◆ deserialize() [2/5]

◆ deserialize() [3/5]

◆ deserialize() [4/5]

◆ deserialize() [5/5]

◆ deserializeFromSection()

◆ deserializeMultiple()

◆ getClassForGuid() [1/2]

◆ getClassForGuid() [2/2]

◆ getIdsFromFile()

◆ getPathDeserializedFromRelativeToRes()

◆ onAfterDeserialized()

◆ resolvePathToToml()

◆ serialize() [1/3]

◆ serialize() [2/3]

◆ serialize() [3/3]

◆ serializeMultiple()

Member Data Documentation

◆ pathDeserializedFromRelativeToRes

◆ sCustomAttributePrefix

◆ sNothingToSerializeKey

◆ sPathRelativeToResKey

◆ sSubEntityFieldNameKey