tree-mutator.hpp File Reference

Go to the source code of this file.

Description

Customisable intermediary to abstract generic tree mutation operations.

This is the foundation for generic treatment of tree altering operations, and especially the handling of changes (diff) to hierarchical data structures. The goal is to represent a standard set of conceptual operations working on arbitrary data structures, without the need for these data structures to comply to any interface or base type. Rather, we allow each instance to define binding closures, which allows to tap into arbitrary internal data representation, without any need of disclosure. The only assumption is that the data to be treated is hierarchical and object-like, i.e. it has (named) attributes and it may have a collection of children. If necessary, typing constraints can be integrated through symbolic representation of types as chained identifiers. (path dependent types).

The interface implemented by the TreeMutator is shaped such as to support the primitives of Lumiera's tree diff handling language. By default, each of these primitives is implemented as a NOP – but each operation can be replaced by a binding closure, which allows to invoke arbitrary code in the context of the given object's implementation internals.

Builder/Adapter concept

TreeMutator is both an interface and a set of building blocks. On concrete usage, the (private, non disclosed) target data structure is assumed to build a subclass of TreeMutator. To this end, the TreeMutator is complemented by a builder DSL. Each call on this builder – typically providing some closure – will add yet another decorating layer on top of the basic TreeMutator (recall all the "mutation primitives" are implemented NOP within the base class). So the actual TreeMutator will be structured like an onion, where each layer cares for the sole concrete aspect it was tied for by the supplied closure. For example, there might be a decorator to handle setting of a "foobar" attribute. Thus, when the diff dictates to mutate "foobar", the corresponding closure will be invoked.

test dummy target

There is a special adapter binding to support writing unit tests. The corresponding API is only declared (forward) by default. The TestMutationTarget is a helper class, which can be attached through this binding and allows a unit test fixture to record and verify all the mutation operations encountered.

Lifecycle

The TreeMutator is conceived as a disposable, one-way-off object. On initialisation, it will _"grab" the contents of its target_ and push them back into place one by one while consuming a mutation diff. For this reason, TreeMutator is made non-copyable, just supporting move construction, as will happen when using the DSL functions on the builder. This is also the only supported usage pattern: you create an anonymous TreeMutator sub type by using the Builder functions right within the scope about to consume one strike of DiffStep entries from a MutationMessage. These diff steps should cover anything to confirm or reshape all of the target's contents. After that, you must not refer to the exhausted TreeMutator anymore, just let it fall out of scope. Incidentally, this also means that any failure or exception encountered while applying a diff will leave a corrupted target data structure. The basic assumption is that

• the target data structure will actually be built through diff messages solely
• and that all received diff messages are sane, as being drawn from a semantically and structurally equivalent source structure If unable to uphold this consistency assumption, it is the client's responsibility to care for transactional behaviour, i.e. create a clone copy of the data structure beforehand, and "commit" or "roll back" the result atomically.

Note

to improve readability, the actual implementation of the "binding layers" is defined in separate headers and included towards the bottom of this header.

See also

tree-mutator-test.cpp

tree-mutator-binding-test.cpp

usage for tree diff application especially DiffApplicationStrategy<TAR, enable_if<TreeDiffTraits<TAR>>> defined there

diff-language.hpp

DiffDetector

Definition in file tree-mutator.hpp.

#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/symbol.hpp"
#include "lib/meta/trait.hpp"
#include "lib/diff/gen-node.hpp"
#include "lib/opaque-holder.hpp"
#include "lib/iter-adapter-stl.hpp"
#include "lib/format-string.hpp"
#include "lib/idi/entry-id.hpp"
#include <utility>
#include <string>
#include "lib/diff/tree-mutator-gen-node-binding.hpp"
#include "lib/diff/tree-mutator-attribute-binding.hpp"
#include "lib/diff/tree-mutator-collection-binding.hpp"
#include "lib/diff/tree-mutator-listener-binding.hpp"
#include "lib/diff/tree-mutator-noop-binding.hpp"

Classes
struct	Builder< PAR >
	Builder-DSL to create and configure a concrete TreeMutator. More...
struct	Builder< PAR >
	Builder-DSL to create and configure a concrete TreeMutator. More...
class	TreeMutator
	Customisable intermediary to abstract mutating operations on arbitrary, hierarchical object-like data. More...

Namespaces
	lib
	Implementation namespace for support and library code.