Name

Synopsis

Description

The tree object is designed to be used when the data being represented naturally falls into a tree structure. For example, a file system, a set of news articles (with follups), or a multi-part mime mail message are best represented as a tree rather than a flat data object (like the simple Tcl associative array.)

Tree Command

The newTreeObject command creates a new Tcl command whose name is returned when the node is created. This command may be used to invoke various operations on the widget. It has the following general form:

pathName subcommand ?arg arg ... ?


Subcommand and the arg s determine the exact behavior of the command. The following commands are possible for tree object:

pathName add

Add a new child node to this node. Returns a handle for accessing the new node.

pathName delete ?-r ?

Deletes this node and all data associated with it. If the -r option is set, all child nodes are also deleted. If no option is used, this nodes child nodes are relinked to be children of the node's parent.

pathName destroyTree

Delete this entire tree.

pathName set ?-node -tree ? key value

Attaches the value to this node. The value can be retrieved using the get command, and the key . The -node and -tree options control whether the value is attached to the current node (and can only be retrieved from this node), or attached to the tree (and can be retrieved from any node.)

pathName append ?-node -tree ? key value

Appends the contents of value to previous data attached to this node. The value can be retrieved using the get command, and the key . The -node and -tree options control whether the value is attached to the current node (and can only be retrieved from this node), or attached to the tree (and can be retrieved from any node.)

pathName lappend ?-node -tree ? key value

Appends the contents of value to previous data attached to this node as a list. The value can be retrieved using the get command, and the key . The -node and -tree options control whether the value is attached to the current node (and can only be retrieved from this node), or attached to the tree (and can be retrieved from any node.)

pathName get ?-node -tree -best ? key

Retrieves the value referenced by key from this node. The -node and -tree options control whether the value is retrieved from the current node, or retrieved from the tree. The -best option checks first on the node, and if the key is not set for this node, checks for a key in the tree. The default is -best .

pathName unset ?-node -tree ? key

Deletes the value associated with this key. The -node and -tree options control whether the value is destroyed on the current node, or the tree.

pathName childList

Return the list of child nodes attached to this node.

pathName search glob

Return the list of child nodes attached to this node that match a glob pattern.

pathName siblingList

Return the list of child nodes attached to this node's parent.

pathName parent

Return the parent of this node.

pathName valueList ?-node -tree ?

Return the list of all the keys and data associated with this node or tree. The data is returned as a list of lists, each list consists of key and data.

ie. {{key1 data1} {key2 {multiword data2}} {{multi word key} {multiword data}}}

pathName keyList ?-node -tree ?

Return the list of all the keys associated with this node or tree. The data is returned as a list of lists, each list consists of keys,

ie. {key1 key2 {multi word key}}

pathName base

Returns the ultimate ancestor of this node.

pathName getNodes

Returns a list of all nodes in the tree, regardless of parent or child relationship.

pathName dump

An ascii dump of this tree, all nodes, children and associated keys and data. Primarily used for debugging.

Example

package require tree 2.1
# Test creating trees

set mytree [newTreeObject]]

# Test methods for setting and getting id/value pairs.
set tmp [$mytree set -node id1 value1]
if {![string match $tmp "value1"]} {
error "Failed to get expected return from set \
-node: $tmp != value1"
}
set tmp [$mytree get -node id1]
if {![string match $tmp "value1"]} {
error "Failed to get expected return from get \
-node: $tmp != value1"
}


Keywords