The foundation for data structures supporting runtime reflection. More...

#include <properties.h>

Inheritance diagram for core::PropertySet:

Public Member Functions
vector< Property * >	properties ()
	Accessor to the list of properties.

vector< const Property * >	properties () const
	Accessor to the list of properties.

void	resetToDefaultValues ()
	Resets all the properties to the default values.

void	copyFrom (const PropertySet &src)
	Transfer values between two property sets.

void	seal (bool sealed=true)
	After sealing a PropertySet, all attempts to modify it through the Property interface will throw an exception (even if setting to the same value)

bool	sealed () const
	Returns `true` if the property set is sealed.

void	onPropertyChange (const Property *property)
	Called before updating a property value.

json	toJson () const
	Serialize all the properties to a json object. More...

void	fromJson (const json &json_obj)
	Deserialize a set of properties from a json object. More...

Detailed Description

The foundation for data structures supporting runtime reflection.

PropertySet provides portable-C++ support for structures containing self-describing properties (no build time pre-processing or external tools are required, this is a compiler-only solution)

Each property has a name, type, default value and a brief description string
Properties map directly to a C++ struct data member with the specified type
Each instance of PropertySet-derived structs includes its own reflection metadata

Usage

In order to support the runtime reflection, a structure must derive from core::Properties. The individual properties are then declared using the PROPERTY() macro, for example:

// PROPERTY(name, type, default_value, description)
struct Config : public core::PropertySet {
  PROPERTY(max_value, int, 100, "Maximum value");
  PROPERTY(resolution, float, 0.3f, "Display resolution");
  PROPERTY(name, string, "darwin", "Name");
  PROPERTY(layers, vector<int>, {}, "Hidden layer sizes");
};

Direct member access (as regular struct members)

This zero-overhead compared with regular C++ structs was one of the key requirements, since the reflected structures are commonly configuration values which could be read on the hot paths (in contrast, the high PropertySet instantiation cost and the reflection path overhead were deemed acceptable)

Config config;
// set Config::max_value
config.max_value = 75;
// read Config::name
auto name = config.name;

Using the runtime reflection support

void printProperties(const core::PropertySet* config) {
  // enumerate properties
  for (const auto& property : config->properties()) {
    // read the property name and value as strings
    core::log("%s = %s\n", property->name(), property->value());
  }
}

Note: This is a specialized reflection solution intended to support dynamic UIs and serializing configuration values. Since every instance of PropertySet-derived structures builds its own internal reflection metadata it may not be appropriate for use cases where there are lots of instances of the reflected structures, or when the object creation performance is critical.

See also: Property

Member Function Documentation

◆ fromJson()

void core::PropertySet::fromJson ( const json & json_obj )

inline

Deserialize a set of properties from a json object.

The deserialization is not strict:

Extra json properties are ignored
Missing properties will be set to the default values

◆ toJson()

json core::PropertySet::toJson ( ) const