Class Composite

Object
   |
   +--Composite

class Composite

Defined in composite.js

Constructor Detail

Composite

function Composite(<string> name, <Object> value)

Creates a composite.

Parameters:
name - the name of this node
value - (Optional) - the value of this node. Defaults to the empty string.

addChild

void addChild(<Composite> child)

Adds the given Composite node to this node's list of children.

Parameters:
child - the node to add

addChildren

void addChildren(<AbstractList> list)

Iteratively adds the contents of list to this node's child list.

Parameters:
list - a list of Composites to add as children of this node

apply

void apply(<Function> preFunc, <Function> postFunc)

Visits each node in the composite tree and calls preFunc and/or postFunc at each node. preFunc is called before visiting the current node's children and postFunc is called after visiting the children. If either preFunc or postFunc is undefined (or null) then apply behaves as though the undefined function were a function that does nothing but return false.

preFunc has the following signature:

• node - the Composite currently being visited by apply
• depth - the depth of node (where the Composite on which apply was originally called is at depth 0)

postFunc has the following signature:

• node - the Composite currently being visited by apply
• depth - the depth of node. depth is defined the same as for preFunc.
• preAbort - a boolean indicating whether or not preFunc's return value caused apply to skip node's children
• childAbort - a boolean indicating whether or not any of node's children caused postFunc to abort.

If preFunc is defined and returns true then the current node's children will be skipped. If postFunc is defined and returns true then the current node's remaining siblings will be skipped. In either case, postFunc is called whenever it is defined.

It is more efficient (but functionally equivalent) to pass null or undefined for either preFunc or postFunc than it is to pass a function that does nothing.

Parameters:
preFunc - (Optional) - a function accepting a Composite and an int as defined above. Defaults to a function that does nothing.
postFunc - (Optional) - a function accepting a Composite, an int, and two booleans as defined above. Defaults to a function that does nothing.

clear

void clear()

Empties this node's child list.

clone

Composite clone(<int> depth, <string> newName)

Clones this node, optionally cloning its children. If depth is 0 then a new Composite is returned with the same name and value as this node. If depth is positive then this node is cloned and all of its children are cloned with depth = depth - 1 and added to the clone of this node (ie. depth is an indicator of how deep to do the clone.) If depth is less than zero then the clone is made as deep as it will go.

Parameters:
depth - the depth to which the clone should be made. Pass a negative number to do a complete deep copy.
newName - (Optional) - the name of the returned Composite. Defaults to this.getName().

Returns:
a clone of this node

contains

boolean contains(<string> path)

Returns true if this node or one of its descendants can be found using the given path and false otherwise.

Parameters:
path - the path to search for

Returns:
true if the match succeeds and false otherwise

containsNodeWithValue

boolean containsNodeWithValue(<string> path, <string> value)

Returns true if this node or one of its descendants has a path matching path and a value matching value.

Parameters:
path - the path to search for
value - the value to query for

Returns:
true if the match succeeds and false otherwise

createPath

Composite createPath(<string> path)

Creates and inserts enough Composites to make sure that this.findFirst(path) will return a non-null value. Returns the Composite at the tail of the path. createPath always chooses the first element in a vector if it has to make a decision about where to create a new node.

Parameters:
path - a path to a possibly non-existent node beneath this one

Returns:
the Composite that path points to, which may have been created in order to satisfy this request

diff

Object diff(<Composite> other)

First stab at a tree-based diff function. Vectors are handled, but in a somewhat unsatisfactory way.

Parameters:
other - the node to diff against this one

Returns:
a structure describing the differences between this node and the given one

find

AbstractList find(<string> path, <Function> hash)

Finds and returns all nodes beneath this one that have a path equal to path, relative to this node. The return value is a list of all matching nodes, and may be empty.

Parameters:
path - the path of the nodes to return
hash - (Optional) - a hash function as used by HashList. If hash is supplied, the list that is returned will be a HashList that uses hash as its hash function. If hash is not supplied, the list that is returned will be a plain LinkedList.

Returns:
a list of matching nodes

findByIndex

Composite findByIndex(<string> path, <int> index)

Finds and returns the indexth node beneath this one that has a path equal to path. Nodes are indexed starting from zero, so findFirst(path) is equivalent to findByIndex(path, 0). Like findFirst, this method returns null if there is no matching node.

Parameters:
path - the path to search for, relative to this node
index - an index into the list of possible return values

Returns:
the matching node or null if none matches

findFirst

Composite findFirst(<string> path)

Finds and returns the first node beneath this one that has a path equal to path. Returns null if there is no such node.

Parameters:
path - the path to search for, relative to this node

Returns:
the matching Composite node, or null if none matches

findFirstNodeWithValue

Composite findFirstNodeWithValue(path, value)

findFirstValue

string findFirstValue(<string> path)

Finds and returns the value of the first node beneath this one that has a path equal to path. Returns the empty string if there is no such node. findFirstValue(path) returns the same value as findFirst(path).getValue() except it won't cause an error if there are no nodes matching the given path.

Parameters:
path - the path to search for, relative to this node

Returns:
the value of the matching Composite node, or the empty string if there is no such node

See:
- findFirst()

findLast

Composite findLast(path)

findLastNodeWithValue

Composite findLastNodeWithValue(path, value)

findLastValue

Object findLastValue(path)

findNodesWithValue

AbstractList findNodesWithValue(<string> path, <string> value, <Function> hash)

Returns a list of all nodes with the given path that have the given value.

Parameters:
path - the path to search for, relative to this node
value - the value matching nodes must have
hash - (Optional) - a hash function as used by HashList. If hash is supplied, the list that is returned will be a HashList that uses hash as its hash function. If hash is not supplied, the list that is returned will be a plain LinkedList.

Returns:
a list of matching Composites, which may be empty

findValueByIndex

string findValueByIndex(<string> path, <int> index)

Finds and returns the value of the indexth node beneath this one that has a path equal to path. Returns the empty string if there is no such node. findValueByIndex(path, index) returns the same value as findByIndex(path, index).getValue() except it won't cause an error if there are no matching nodes.

Parameters:
path - the path to search for, relative to this node
index - an index into the list of possible return values

Returns:
the value of the matching Composite node, or the empty string if there is no such node

See:
- findByIndex()

findValues

AbstractList findValues(<string> path, <bool> makeHash)

Finds and returns the values of all the nodes beneath this one that have a path equal to path. The return value is a list of the values of all matching nodes, and may be empty.

Parameters:
path - the path to search for, relative to this node
makeHash - (Optional) - If true it will place the values in a hash list, using Hash.IDENTITY(). The behaviour is undefined if values are not unique and makeHash is true.

Returns:
a list of the values of matching nodes

getChild

Composite getChild(index)

getChildCount

int getChildCount()

getChildIterator

Iterator getChildIterator()

Returns an iterator over this node's child list.

Returns:
an iterator, as defined by AbstractList.iterator()

See:
- AbstractList.iterator()

getChildren

Array getChildren()

getName

string getName()

getParent

Composite getParent()

getPath

string getPath()

getValue

Object getValue()

hasChildren

boolean hasChildren()

merge

Object merge(<Composite> comp, <boolean> returnOldCopy, <boolean> writableInput)

Updates the model to match what is specified by comp. If a node exists in both the model and comp then comp is taken to be correct. If a node exists in the model but not in comp then the model is left alone, except in the case of vectors where comp's version of the vector is used. Only the children of comp are merged into the model. This way a group of siblings can be merged with one call by grouping them under a nameless node.

Parameters:
comp - the Composite to merge into this model
returnOldCopy - (Optional) - a boolean indicating whether or not to return a Composite that is a copy of this before the merge was performed. Defaults to false.
writableInput - (Optional) - a flag indicating whether or not comp is writable. If false, comp will be cloned as necessary to update this. If true, the Composite descendants of comp will be moved, rather than copied, into this. Passing true can be significantly faster than false, but it invalidates comp. Defaults to false.

Returns:
undefined if returnOldCopy is false, a pre-merge, deep clone of the merge root otherwise

removeChild

void removeChild(<Composite> child)

Removes the given Composite from this one.

Parameters:
child - the Composite to remove

removeChildren

void removeChildren(<AbstractList> childList)

Removes a list of Composites from this one.

Parameters:
childList - a list of Composites to remove

setValue

void setValue(newValue)

toString

string toString()

fromLoL

<static> Composite fromLoL(<string> name, <string> value, <Array> children)

Creates and returns a Composite from a list of lists. The returned Composite will have name and value equal to name and value, respectively, and its children will be determined by the remaining arguments to fromLoL. Each argument to fromLoL after value should be an array of length at least one. Each such array recursively describes a Composite. The zeroth element is taken to be the name, the first element is the value, and each successive element is an array describing a child using the same format as was used to describe the parent. For example, the following code

var root = Composite.fromLoL('Parent', '',
                             ['Child', '',
                                 ['GrandChild', 'foo'],
                                 ['GrandChild', 'bar']],
                             ['Child', '',
                                 ['GrandChild', 'baz']]);

is equivalent to the following

var root = new Composite('Parent');

var firstChild = new Composite('Child');
firstChild.addChild(new Composite('GrandChild', 'foo'));
firstChild.addChild(new Composite('GrandChild', 'bar'));

root.addChild(firstChild);

var secondChild = new Composite('Child');
secondChild.addChild(new Composite('GrandChild', 'baz'));

root.addChild(secondChild);

Parameters:
name - the name of the returned Composite
value - (Optional) - the value of the returned Composite. Defaults to ''.
children - (Optional) - the argument list is of variable length, but each argument should be an array as described above. Calling Composite.fromLoL(name, value) (with no children at all) is an inefficient way to call the Composite constructor.

Returns:
the Composite described by the arguments

fromXML

<static> Composite fromXML(<DOMNode> xml)

Creates a Composite tree based on the XML provided.

Parameters:
xml - the root of an XML tree to be converted to a Composite tree

Returns:
the root of a Composite tree

getPathSegments

<static> Array getPathSegments(<string> path)

Returns an array of path segments given a path.

Parameters:
path - a path into a Composite tree

Returns:
an array wherein the i^th element of the array is the i^th sequence of characters in path not containing the '/' character

toXML

<static> string toXML(<Composite> node, <Array> roots, <boolean> include)

Serializes the Composite tree rooted at node to an XML string. The contents of the resulting string can be controlled by the roots and include parameters. If both of these optional parameters are set to their default values then all the Composites descending from node will be serialized to XML. If a non-empty list is supplied for roots then node plus all of node's children either in or not in roots (depending on the value of include) will be serialized and the other children of node will be ignored.

Parameters:
node - the root of the Composite tree to be XML-ified
roots - (Optional) - a array of node names to either include or exclude from the serialization process, depending on the value of include. Defaults to the zero-length array.
include - (Optional) - a flag indicating whether roots is a list of nodes to include or exclude. If include is true the node names in roots are included, and if it's false they're excluded. Defaults to false.

Returns:
the XML representation of node and all its descendants in a string