ImFusion::PropertiesIO Namespace Reference

Writing and reading Properties instances to/from structured file formats. More...

Detailed Description

Writing and reading Properties instances to/from structured file formats.

Note

The serialization functions of this namespace will only store the values of parameters but none of their runtime information such as default values, types. Attributes are only stored if the corresponding Format explicitly states so.

See also

Object Serialization

Enumerations
enum class	Format {   Xml1_1 , Xml1_1WithAttributes , Json2_0 , Json2_0NoPreamble ,   Json1_0 , Json1_0NoPreamble }
	Enumeration of supported file formats for Properties storage. More...

Functions
std::optional< std::string >	saveToString (const Properties &properties, Format format, const std::string &commentString="")
	Serialize the given Properties instance to a string using the specified format.
bool	saveToXML (const Properties &properties, const Filesystem::Path &filename, Format format, const std::string &commentString="")
	Serialize the given Properties instance to an XML file on the local filesystem.
bool	saveToJSON (const Properties &properties, const Filesystem::Path &filename, Format format, const std::string &commentString="")
	Serialize the given Properties instance to a JSON file on the local filesystem.
std::unique_ptr< Properties >	loadFromString (const std::string &input, Format format)
	Deserialize the given input string to a new Properties instance using the specified format.
std::unique_ptr< Properties >	loadFromXML (const Filesystem::Path &filename)
	Deserialize the given XML file to a new Properties instance.
std::unique_ptr< Properties >	loadFromJSON (const Filesystem::Path &filename)
	Deserialize the given JSON file to a new Properties instance.

Enumeration Type Documentation

Format

enum class Format

strong

Enumeration of supported file formats for Properties storage.

Enumerator
Xml1_1	XML format storing only parameter values and subproperties in the following form: <propertyfile version="1.1"> <param name="Parameter Name">Parameter Value</param> <property name="Subproperty Name"> <...> </property> </propertyfile>
Xml1_1WithAttributes	Extended XML format that additionally encodes the key-value pairs of parameter/subproperty attributes in the following form: <propertyfile version="1.1"> <param name="Parameter Name" type="<type>" [attrib-key="value"]*>Parameter Value</param> <property name="Subproperty Name" [attrib-key="value"]*> <...> </property> </propertyfile> The special attribute 'type' is included automatically and it provides the necessary information to restore the correct type of a parameter value.
Json2_0	Storage in Javascript Object Notation (JSON) form: { "version": "2.0", "propertyfile": { "Parameter Name": "Parameter value", "Subproperty name/index": { ... } } } In contrast to Json1_0 this format will use native JSON types for values where supported (e.g. numbers, booleans, ...) instead of storing them as strings. Furthermore, it will always produce valid JSONs, also in edge cases where there are multiple subproperties with the same name. Therefore, to avoid key duplication it will always add a /<index> suffix to the subproperty name, where <index> is in fact the index of appearance of that name within a given JSON scope. The subproperty index must start at 0 for a given subproperty name, and then it is incremented by 1 each time that the same subproperty name is repeated in its same scope. If a subproperty name is repeated within a nested scope, it must restart from index 0, as nested scopes can repeat the same name without ambiguity.
Json2_0NoPreamble	Storage in Javascript Object Notation (JSON) form without preamble and therefore lacking support for versioning and comments: { "Parameter Name": "Parameter value", "Subproperty name/index": { ... } } This format consists in just the "propertyfile" value of the Json2_0 format.
Json1_0	Storage in Javascript Object Notation (JSON) form: { "version": "1.0", "propertyfile": { "Parameter Name": "Parameter value", "Subproperty name": { ... } } } This format will always use the string representation of the parameters inside Properties to store the values. Furthermore, it will use the subproperty name as key when storing subproperties. This can produce invalid JSONs in case there are multiple subproperties with the same name, since the resulting JSONs may contain duplicate keys. When there are multiple subproperties with the same name, even at the same JSON scope, a new subproperty is added without overriding the value of any other subproperty with that same name in the same scope.
Json1_0NoPreamble	Storage in Javascript Object Notation (JSON) form without preamble and therefore lacking support for versioning and comments: { "Parameter Name": "Parameter value", "Subproperty name": { ... } } This format consists in just the "propertyfile" value of the Json1_0 format.