stlab.adobe.com Adobe Systems Incorporated

The fundamental data structure for the Property Model engine.

#include <adam.hpp>

List of all members.

Classes

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

Public Types

typedef boost::signals::connection connection_t
typedef boost::function< void(const
dictionary_t &)> 
monitor_contributing_t
typedef boost::function< void(bool)> monitor_enabled_t
typedef boost::function< void(bool)> monitor_invariant_t
typedef boost::function< void(const
any_regular_t &)> 
monitor_value_t

Public Member Functions

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_input (name_t name, const line_position_t &position, const array_t &initializer)
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_invariant (name_t name, const line_position_t &position, const array_t &expression)
void add_logic (name_t name, const line_position_t &position, const array_t &expression)
void add_output (name_t name, const line_position_t &position, const array_t &expression)
void add_relation (const line_position_t &position, const array_t &conditional, const relation_t *first, const relation_t *last)
dictionary_t contributing (const dictionary_t &mark) const
dictionary_t contributing () const
dictionary_t contributing_to_cell (name_t) const
std::size_t count_interface (name_t name) const
any_regular_t get (name_t cell)
bool has_input (name_t name) const
bool has_output (name_t name) const
any_regular_t inspect (const array_t &expression)
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)
connection_t monitor_value (name_t name, const monitor_value_t &proc)
void reinitialize ()
void set (const dictionary_t &dictionary)
void set (name_t cell, const any_regular_t &value)
void touch (const name_t *first, const name_t *last)
void update ()

Public Attributes

virtual_machine_t machine_m

Detailed Description

Definition at line 73 of file adam.hpp.


Member Typedef Documentation

typedef boost::signals::connection connection_t

An object that maintains the function callback validity between the Adam engine and the client code. These are simply boost::signals::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 96 of file adam.hpp.

typedef boost::function<void (const dictionary_t&)> monitor_contributing_t

Definition at line 80 of file adam.hpp.

typedef boost::function<void (bool)> monitor_enabled_t

Definition at line 81 of file adam.hpp.

typedef boost::function<void (bool)> monitor_invariant_t

Definition at line 76 of file adam.hpp.

typedef boost::function<void (const any_regular_t&)> monitor_value_t

Definition at line 79 of file adam.hpp.


Member Function Documentation

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

Add a constant cell to the sheet.

Parameters:
namename of the cell being added.
positionposition in the parse of the cell definition.
initializerexpression 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.
void add_constant ( name_t  name,
any_regular_t  value 
)

Add a constant cell to the sheet.

Parameters:
namename of the cell being added.
valuevalue for the cell.
initializerexpression to be evaluated for the cell's value.
void add_input ( name_t  name,
const line_position_t position,
const array_t initializer 
)

Add an input cell to the sheet.

Parameters:
namename of the cell being added.
positionposition in the parse of the cell definition.
initializerexpression to be evaluated for the cell's starting value.
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:
namename of the cell being added.
linkedspecifies whether or not the output value is automatically applied back to the input value of the cell.
positionposition in the parse of the initializer definition.
initializerexpression to be evaluated for the cell's value
position2position in the parse of the expression definition.
expressionexpression to be evaluated for the cell's output value.
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:
namename of the cell being added.
initalinitial value of the cell.
void add_invariant ( name_t  name,
const line_position_t position,
const array_t expression 
)

Add an invariant cell to the sheet.

Parameters:
namename of the cell being added.
positionposition in the parse of the cell definition.
expressionexpression to be evaluated for the cell's output value.
void add_logic ( name_t  name,
const line_position_t position,
const array_t expression 
)

Add a logic cell to the sheet.

Parameters:
namename of the cell being added.
positionposition in the parse of the cell definition.
expressionexpression to be evaluated for the cell's output value.
void add_output ( name_t  name,
const line_position_t position,
const array_t expression 
)

Add an output cell to the sheet.

Parameters:
namename of the cell being added.
positionposition in the parse of the cell definition.
expressionexpression to be evaluated for the cell's output value.
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:
positionposition in the parse of the cell definition.
conditionalexpression (if present) that must be evaluated to true in order for tese relations to be considered.
firstthe first relation in the relation set.
lastone-past-the last relation in the relation set.
dictionary_t contributing ( const dictionary_t mark ) const
Parameters:
markA 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.
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.
dictionary_t contributing_to_cell ( name_t   ) const
Returns:
A dictionary of the currently contributing cells and their values to the named cell.
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:
namethe name of the cell to query
Returns:
1 if the cell exists, 0 otherwise.

Definition at line 449 of file adam.hpp.

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. Outside of these calls the get() function may be called to get the most recent ouput value of the cell cashed from the last call to update().

Parameters:
nameof cell to calculate/get the value.
bool has_input ( name_t  name ) const

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

Parameters:
namethe name of the cell to query
Returns:
Whether an input (or interface) cell with the given name exists.
bool has_output ( name_t  name ) const

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

Parameters:
namethe name of the cell to query
Returns:
Whether an output (or interface) cell with the given name exists.
any_regular_t inspect ( const array_t expression )
Parameters:
expressiontoken stack describing a virtual machine expression.
Returns:
The value evaluated out of the expression.
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:
cellthe name of the cell to monitor.
marka "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().
procthe 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.
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:
cellthe name of the cell whose enabled status to monitor.
firstStart of range [first, last) of interface cells whose priority_accessed status will be monitored. If range is empty this must be NULL.
lastEnd of range [first, last) of interface cells whose priority_accessed status will be monitored. If range is empty this must be NULL.
procthe 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.
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:
outputthe name of the output cell to which an invariant is bound.
procthe 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.
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:
cellthe name of the cell to monitor.
procthe 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.
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.

void set ( const dictionary_t dictionary )

Sets various cells in the sheet to various values.

Parameters:
dictionarythe 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.
void set ( name_t  cell,
const any_regular_t value 
)
Parameters:
cellthe input cell to which the value is to be set.
valuethe value to set the input cell to.
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:
firstStart of range [first, last) of input cells to touch.
lastEnd of range [first, last) of input cells to touch.
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.


Member Data Documentation

Definition at line 523 of file adam.hpp.

Copyright © 2006-2007 Adobe Systems Incorporated.

Use of this website signifies your agreement to the Terms of Use and Online Privacy Policy.

Search powered by Google