sheet_t Class Reference

The fundamental data structure for the Property Model engine. More...

#include <adam.hpp>

Inheritance diagram for sheet_t:

Classes
struct	relation_t
	Adam support class for related relationships. More...

Public Types
using	monitor_invariant_t
using	monitor_value_t
using	monitor_contributing_t
using	monitor_enabled_t
typedef boost::signals2::connection	connection_t

Public Member Functions
	sheet_t ()
	~sheet_t ()
any_regular_t	inspect (const array_t &expression)
void	set (name_t cell, const any_regular_t &value)
void	touch (const name_t *first, const name_t *last)
any_regular_t	get (name_t cell)
const any_regular_t &	operator[] (name_t cell) const
void	add_input (name_t name, const line_position_t &position, const array_t &initializer)
void	add_output (name_t name, const line_position_t &position, const array_t &expression)
void	add_constant (name_t name, const line_position_t &position, const array_t &initializer)
void	add_constant (name_t name, any_regular_t value)
void	add_logic (name_t name, const line_position_t &position, const array_t &expression)
void	add_invariant (name_t name, const line_position_t &position, const array_t &expression)
void	add_interface (name_t name, bool linked, const line_position_t &position1, const array_t &initializer, const line_position_t &position2, const array_t &expression)
void	add_interface (name_t name, any_regular_t initial)
void	add_relation (const line_position_t &position, const array_t &conditional, const relation_t *first, const relation_t *last)
connection_t	monitor_value (name_t name, const monitor_value_t &proc)
connection_t	monitor_contributing (name_t cell, const dictionary_t &mark, const monitor_contributing_t &proc)
connection_t	monitor_enabled (name_t cell, const name_t *first, const name_t *last, const monitor_enabled_t &proc)
connection_t	monitor_invariant_dependent (name_t output, const monitor_invariant_t &proc)
bool	has_input (name_t name) const
bool	has_output (name_t name) const
std::size_t	count_interface (name_t name) const
void	update ()
void	reinitialize ()
void	set (const dictionary_t &dictionary)
dictionary_t	contributing (const dictionary_t &mark) const
dictionary_t	contributing () const
dictionary_t	contributing_to_cell (name_t) const

Public Attributes
virtual_machine_t	machine_m

Detailed Description

Definition at line 56 of file adam.hpp.

Member Typedef Documentation

monitor_invariant_t

using monitor_invariant_t

Definition at line 60 of file adam.hpp.

monitor_value_t

using monitor_value_t

Definition at line 61 of file adam.hpp.

monitor_contributing_t

using monitor_contributing_t

Definition at line 62 of file adam.hpp.

monitor_enabled_t

using monitor_enabled_t

Definition at line 63 of file adam.hpp.

connection_t

typedef boost::signals2::connection connection_t

An object that maintains the function callback validity between the Adam engine and the client code. These are simply boost::signals2::connection objects, and are the responsibility of the client to maintain. They retain the same lifespans and semantics as described in the boost documentation. Typically the client code should group together all connections between and Adam sheet and their client code. When the time for destroying the client code or the Adam sheet comes, these connections should be disconnected to prevent communication between objects being destroyed.

Definition at line 78 of file adam.hpp.

Constructor & Destructor Documentation

sheet_t()

sheet_t

(

)

~sheet_t()

~sheet_t

(

)

Member Function Documentation

inspect()

any_regular_t inspect

(

const array_t &

expression

)

Parameters

expression

token stack describing a virtual machine expression.

Returns

The value evaluated out of the expression.

set() [1/2]

void set	(	name_t	cell,
		const any_regular_t &	value )

Parameters

cell	the input cell to which the value is to be set.
value	the value to set the input cell to.

touch()

void touch	(	const name_t *	first,
		const name_t *	last )

Touch a collection of input cells denoted by a range of names [first, last). Touching a cell raises the priority of the cell as if it were set, without changing the value of the cell. The relative priority of the cells within the range is preserved. Touching can be used to control which cells are selected for derivation in a relation.

Todo

(sparent) : I think that touch relationships will eventually need to be descriped within the sheet as opposed to simply being an imperative action for proper scripting. Also, a facility for user controlled touching which effects a collection of cells on any set operation should be added.

Parameters

first	Start of range [first, last) of input cells to touch.
last	End of range [first, last) of input cells to touch.

get()

any_regular_t get

(

name_t

cell

)

The get function is intended to be connected to the VM variable lookup by the client. During expression evaluation, triggered by initialization, reinitialize, or update the VM can call get() to return the value of a variable.

Parameters

cell	name of cell to calculate/get the value.

operator[]()

const any_regular_t & operator[]

(

name_t

cell

)

const

Returns the most recent ouput value of the cell cashed from the last call to update().

Parameters

cell	name of cell to lookup.

add_input()

void add_input	(	name_t	name,
		const line_position_t &	position,
		const array_t &	initializer )

Add an input cell to the sheet.

Parameters

name	name of the cell being added.
position	position in the parse of the cell definition.
initializer	expression to be evaluated for the cell's starting value.

add_output()

void add_output	(	name_t	name,
		const line_position_t &	position,
		const array_t &	expression )

Add an output cell to the sheet.

Parameters

name	name of the cell being added.
position	position in the parse of the cell definition.
expression	expression to be evaluated for the cell's output value.

add_constant() [1/2]

void add_constant	(	name_t	name,
		const line_position_t &	position,
		const array_t &	initializer )

Add a constant cell to the sheet.

Parameters

name	name of the cell being added.
position	position in the parse of the cell definition.
initializer	expression to be evaluated for the cell's value.

Note

This interface is deprecrecated and will be removed when the virtual machine is removed from the sheet.

add_constant() [2/2]

void add_constant	(	name_t	name,
		any_regular_t	value )

Add a constant cell to the sheet.

Parameters

name	name of the cell being added.
value	value for the cell.

add_logic()

void add_logic	(	name_t	name,
		const line_position_t &	position,
		const array_t &	expression )

Add a logic cell to the sheet.

Parameters

name	name of the cell being added.
position	position in the parse of the cell definition.
expression	expression to be evaluated for the cell's output value.

add_invariant()

void add_invariant	(	name_t	name,
		const line_position_t &	position,
		const array_t &	expression )

Add an invariant cell to the sheet.

Parameters

name	name of the cell being added.
position	position in the parse of the cell definition.
expression	expression to be evaluated for the cell's output value.

add_interface() [1/2]

void add_interface	(	name_t	name,
		bool	linked,
		const line_position_t &	position1,
		const array_t &	initializer,
		const line_position_t &	position2,
		const array_t &	expression )

Add an interface cell to the sheet. An interface cell combines all aspects of both the input and output cell types.

Parameters

name	name of the cell being added.
linked	specifies whether or not the output value is automatically applied back to the input value of the cell.
position1	position in the parse of the initializer definition.
initializer	expression to be evaluated for the cell's value
position2	position in the parse of the expression definition.
expression	expression to be evaluated for the cell's output value.

add_interface() [2/2]

void add_interface	(	name_t	name,
		any_regular_t	initial )

REVISIT (sparent) : This interface is temporary to support the old basic_sheet_t interface, however, as the dependency on the virtual machine is removed from the sheet, a similar interface is likely to remain.

The cell added has an identity expression, no initializer expression, and is linked.

Parameters

name	name of the cell being added.
initial	initial value of the cell.

add_relation()

void add_relation	(	const line_position_t &	position,
		const array_t &	conditional,
		const relation_t *	first,
		const relation_t *	last )

Add a relation logic cell to the sheet. When the sheet is updated, if the conditional evalutes to true then exactly one of the relations in the relation set will be evaluated. Which relation is executed is determined by evaluating cells based on their priority in the sheet until there is only a single cell remaining which must derived by the relationship.

Todo

(sparent) : A warning should be issued if the system is over constrained and no relations are evaluated but currently isn't.

Parameters

position	position in the parse of the cell definition.
conditional	expression (if present) that must be evaluated to true in order for tese relations to be considered.
first	the first relation in the relation set.
last	one-past-the last relation in the relation set.

monitor_value()

connection_t monitor_value	(	name_t	name,
		const monitor_value_t &	proc )

Establishes a callback for a cell to be called when the value of the cell changes.

Parameters

name	the name of the cell to monitor.
proc	the ConvertibleToFunction to be called with the new cell value.

Returns

A connection_t that maintains the sheet-to-callback link. This link should be broken before the sheet or the client code are destroyed to prevent communication between destructing objects.

monitor_contributing()

connection_t monitor_contributing	(	name_t	cell,
		const dictionary_t &	mark,
		const monitor_contributing_t &	proc )

Establishes a callback for a cell to be called when the contributing cells to the cell changes.

Parameters

cell	the name of the cell to monitor.
mark	a "bookmark" used to indicate the start point from which contribution changes are to be measured. Any changes to the cell's contributing cells after this point are considered contributing and will be notified through the callback. A mark is obtained by calling sheet_t::contributing().
proc	the ConvertibleToFunction to be called with the new contributing cell values.

Returns

A connection_t that maintains the adam-to-callback link. This link should be broken before the Adam sheet or the client code are destroyed to prevent communication between destructing objects.

monitor_enabled()

connection_t monitor_enabled	(	name_t	cell,
		const name_t *	first,
		const name_t *	last,
		const monitor_enabled_t &	proc )

Enabled status is a conservative approximation which is false if a change to the cell cannot affect the output of a correct sheet and true if it may effect the output.

Establishes a callback to be called when an interface cell's enabled status changes. A cell's enablement is calculated from a cell and from an optional collection of cells referred to as a touch-set. The definition of enablement depends on several other definitions

1) an "output" cell is a cell that appears in the output section of a sheet

2) an "interface-output" is the ouput value of an interface cell

3) an interface cell's "priority-accessed" is true if during the last update the cell's priority was accessed

4) an interface cell's "value-contributed" is true if during the last update the cell's value contributed to either: a pure output cell's value, or if there are no pure output cells, to an interface-output cell.

5) an interface cell's "active" == "priority-accessed" || "value_contributed"

6) an interface cell's "value-accessed" is true if during the last update the cell's value was accessed

7) an interface cell's "enabled" is true if during the last update: active(cell) || (value-accessed(cell) && (for some cell x in the touchlist: prirority-accessed(x)))

Parameters

cell	the name of the cell whose enabled status to monitor.
first	Start of range [first, last) of interface cells whose priority_accessed status will be monitored. If range is empty this must be NULL.
last	End of range [first, last) of interface cells whose priority_accessed status will be monitored. If range is empty this must be NULL.
proc	the ConvertibleToFunction to be called with the enabled state changes.

Returns

A connection_t that maintains the sheet-to-callback link. This link should be broken before the sheet or the client code are destroyed to prevent communication between destructing objects.

monitor_invariant_dependent()

connection_t monitor_invariant_dependent	(	name_t	output,
		const monitor_invariant_t &	proc )

Establishes a callback for an output cell to be called when an invariant state changes.

Parameters

output	the name of the output cell to which an invariant is bound.
proc	the ConvertibleToFunction to be called with the invariant state change.

Returns

A connection_t that maintains the adam-to-callback link. This link should be broken before the Adam sheet or the client code are destroyed to prevent communication between destructing objects.

has_input()

bool has_input

(

name_t

name

)

const

Predicate to determine wheter an input (or interface) cell with a given name exists.

Parameters

name	the name of the cell to query

Returns

Whether an input (or interface) cell with the given name exists.

has_output()

bool has_output

(

name_t

name

)

const

Predicate to determine wheter an output (or interface) cell with a given name exists.

Parameters

name	the name of the cell to query

Returns

Whether an output (or interface) cell with the given name exists.

count_interface()

std::size_t count_interface

(

name_t

name

)

const

REVISIT (sparent) This interface is provided for compatibility with the old basic_sheet_t. We should have a general approach to quearing if a cell of a particular type exists.

Parameters

name	the name of the cell to query

Returns

1 if the cell exists, 0 otherwise.

Definition at line 437 of file adam.hpp.

update()

void update

(

)

Updates all the Adam cells in the sheet depending on the values changed by calls to set(). This function will utilize the monitor callbacks to notify the client of any cell value changes that resulted from contributing values being applied to the sheet.

reinitialize()

void reinitialize

(

)

Input cells are re-initialized, in sheet order, and interface cell initializers are re-evaluated. Priorities are updated, but no callbacks are triggered. Calls to reinitialize should be followed by calls to update, just as if the cells were updated by set operations on sorted ranges.

set() [2/2]

void set

(

const dictionary_t &

dictionary

)

Sets various cells in the sheet to various values.

Parameters

dictionary

the dictionary with the values to set in the sheet. The keys in the dictionary will be used to map thier values to cells in the sheet.

contributing() [1/2]

dictionary_t contributing

(

const dictionary_t &

mark

)

const

Parameters

mark	A previous result from sheet_t::contributing().

Returns

A dictionary with the minimal set of values such that if you were to call set(mark), followed by set(result), the output state of the sheet would be restored.

contributing() [2/2]

dictionary_t contributing

(

)

const

Returns

A dictionary of the currently contributing cells and their values. Given an equivalent instance of the sheet, sheet.set(result) will ensure that the output of the sheet is restored.

contributing_to_cell()

dictionary_t contributing_to_cell

(

name_t

)

const

Returns

A dictionary of the currently contributing cells and their values to the named cell.

Member Data Documentation

machine_m

virtual_machine_t machine_m

Definition at line 510 of file adam.hpp.