record.hpp File Reference

Special collection to represent object-like data. More...

Go to the source code of this file.

Description

Special collection to represent object-like data.

To be used in a context where introspection, open, extensible definitions and loose coupling of data representation matters. Typically, structures defined in terms of Record elements are linked to the actual core representation of the same entities relying on diff messages. Record is one of the supported flavours within the DataCap of GenNode elements, which in turn serve as the standard handle to refer to other elements, entities, attributes or references within the "backbone" of the Lumiera GUI.

A Record holds

• (optionally) a type-ID string
• a collection of named attributes (key-value data)
• a list of enclosed children (contents within the "scope" of this Record)

design decisions

The Record type is shaped from its intended use: It serves to symbolically represent objects in the "external tree description". Here, "objects" means objects for real, i.e. with types, fields and an enclosed scope. Yet the term external means that we do not work on these objects right here, we only represent them, for later referral, symbolically.

rationale

The underlying theme and motivation of this design is negative: we do not want to build yet another object system. The object model of C++ is deemed adequate.

This leads to the following decisions

• the Record entity is itself an object and thus has an inner side, privately. The entrails of the Record can be reworked and tuned for performance
• yet the Record has an external appearance, which makes it look flat and passive. This is to say, a Record has no visible functionality.
• the parts or realms within this symbolic representation are distinguished by convention solely
  • metadata is very limited and boils down to a type attribute known by name
  • children (scope contents) can be recognised by not bearing a name

Record entities are meant to be immutable. The proper way to alter a Record is to apply a diff. Yet for the implementation of this diff handling, a Record::Mutator is provided, to allow controlled partial re-building of a given data element. Moreover, especially for Record<GenNode>, this mutator can be used for a DSL-style compact notation of a complete "object tree" – a feature intended for writing unit tests.

Remarks

• the implementation is focused on the intended primary use case, which is to exchange diff messages drawn against a symbolic representation of a typed object tree. Especially, we assume that there is only a small number of attributes (so linear search for access by key is adequate).
• moreover, we assume that the value type allows for somehow embedding the key of each attribute; the implementation needs an explicit specialisation of the binding functions for each value type.
• this header defines a specialisation for VAL = std::string – while the most relevant specialisation for GenNode is provided alongside with this special, monadic value type.
• an alternative implementation approach would have been to use a dedicated helper type to represent the collection of attributes. This type might then be specialised, e.g. to utilise an index table for key-value lookup. However, in the light of the intended usage of Record entities as tree nodes within a GenNode monad, such a more elaborate approach was deemed unnecessary for the time being.

See also

GenericRecord_test

Definition in file record.hpp.

#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/iter-adapter.hpp"
#include "lib/iter-adapter-stl.hpp"
#include "lib/itertools.hpp"
#include "lib/format-util.hpp"
#include "lib/util.hpp"
#include <algorithm>
#include <utility>
#include <vector>
#include <string>

Namespaces
namespace	lib
	Implementation namespace for support and library code.
namespace	lib::idi
	Identification Schemes.
namespace	lib::diff

Classes
class	Record< VAL >
	object-like record of data. More...
class	Record< VAL >::Mutator
class	RecordRef< VAL >
	wrapped record reference. More...
struct	RecordSetup< string >
	Type configuration (extension point). More...

Functions
template<typename VAL >
Record< VAL >::Mutator &	mutateInPlace (Record< VAL > &record_to_mutate)
	open an existing record for modification in-place.

---

Class Documentation

lib::diff::RecordSetup< string >

struct lib::diff::RecordSetup< string >

Class Members
typedef vector< string >	Storage
typedef const_iterator	ElmIter
typedef string	Access	data access by value copy

Collaboration diagram for RecordSetup< string >: