DragonFly On-Line Manual Pages
tree(n) BLT Built-In Commands tree(n)
______________________________________________________________________________
NAME
tree - Create and manage tree data objects.
SYNOPSIS
tree create ?-fixed? ?-dictset? ?-keyhash N? ?treeName?
tree destroy treeName...
tree names ?pattern?
tree op subcmd ?subsubcmd ...? treeName ?arg arg ...?
______________________________________________________________________________
DESCRIPTION
The tree command is used to create, destroy, and provide Tcl access to
a tree object. A tree object is an ordered tree of nodes where each
node can have data key-values, tags and a label. The treeview widget
uses a tree object.
INTRODUCTION
Tree provides Tcl with a rich API for managing complex data structures.
Here is a simple example.
set t [tree create]
set id [$t insert 0]
$t set $id X 2
set n [$t get $id X]
# Create a node with label
$t insert 0 -label A
$t set 0->A X 1
set n [$t get 0->A X]
Labels provide convenient -> indexing relative a starting node.
Nodes may also be created with initial data values.
$t insert 0 -label A -data {X 1 Y "a 1 b 2"}
$t incr 0->A X 3
$t set 0->A Y(a) 4
Note round braces are used to access sub-values in a dict-array. See
the section DICT-ARRAYS below for details.
SYNTAX
tree create ?-fixed? ?-dictset? ?-keyhash N? ?treeName?
Creates a new tree object. The name of the new tree is returned
and a Tcl command is created. If no treeName argument is
present, then the name of the tree is automatically generated in
the form "tree0", "tree1", etc relative to the current
namespace. A tree name (if given) can not start with a dash.
Tree names containing the substring "#auto" will be replaced
with a generated identifier. For example, the name data#auto
will translate to datatree0. Note that when the Tcl command is
deleted the tree object also gets freed.
Newly created trees always contain a single root node with id 0
that can not be deleted.
Switches for create are listed below:
-fixed Make insert automatically set the -fixed flag. This
will disallow later setting of keys not given as -data
to the insert. This includes dict-array keys. See
the fixed sub-command.
-dictset Define that any update of an array field will coerce
the array object to a dict object. a dict will
preserve order of sub-field keys on update. See the
dictset sub-command.
-keyhash size
Define the size beyond which node key storage starts
using a hash (the default is 21 keys). Normally small
numbers of keys are stored as a list. But once more
than size keys are added to a node, key storage
converts to a hash. This affects the order of key
iteration (eg. for get/names/values). A list will
iterate in the order in which keys were added, whereas
the order of a hash is undetermined. For large
numbers of ordered keys, specify a really large size
(eg. 1000000).
tree destroy treeName...
Releases one of more trees. The Tcl command associated with
treeName is also removed. Trees are reference counted. The
internal tree data object isn't destroyed until no one else is
using the tree.
tree names ?pattern?
Returns the names of all tree objects. if a pattern argument is
given, then the only those trees whose name matches pattern will
be listed.
tree op subcmd ?subsubcmd ...? treeName ?arg arg ...?
Provide direct calls to sub-commands, without going through the
object command. Aside from self documentating, it allows wize
to provide support checked tree calls.
NODE IDS AND TAGS
Nodes in a tree object may be referenced by id or by tag. Each node
has a unique serial number or id that is assigned to it at creation.
The id of an node never changes or is reused unless all nodes in a tree
are delete.
A node may also have any number of tags associated with it. A tag is
just a string of characters, and it may take any form but can not start
with an integer. For example, "x123" is valid, but "123x" is not. The
same tag may be associated with one or multiple nodes (ranges or
tagnode). Ranges are commonly used to group nodes in various
interesting ways.
Commands that take a tagnode can operate on ranges and will accept
either a tag or a list of zero or more integer node numbers. A node-
list may contain only integers, and can not have leading spaces. Node-
lists simplify the use of iterating commands because it avoids
excessive use of eval.
There are four built-in or psuedo tags:
all Applies to every node in the tree.
nonroot Applies to every node in the tree except the root
node.
rootchildren
Applies to every node in the tree whose parent is the
root node.
root Managed automatically by the tree object, root
specifies the node that is currently set as the root
node for the tree.
When specifying nodes in tree object commands, if the specifier is an
integer then it is assumed to refer to the single node with that id.
If the specifier is not an integer, then it is assumed to refer to all
of the nodes in the tree that have a tag matching the specifier. The
symbol node is used below to indicate that an argument specifies either
an id or a tag that selects a single node. A tagnode is either a tag
that selects a group of nodes, or it's a list of zero or more integer
node numbers. Many tree commands only operate on a single node at a
time; if node is specified in a way that names multiple items, then an
error "refers to more than one node" is generated.
NODE MODIFIERS
You can also specify node in relation to another node by appending one
or more modifiers to the node id or tag after ->. A modifier refers to
a node in relation to the specified node. For example,
"root->firstchild" selects the first subtree of the root node.
The following modifiers are available:
firstchild
Selects the first child of the node.
lastchild Selects the last child of the node.
nextnode Selects the next node in preorder to the node.
nextsibling
Selects the next sibling of the node.
parentnode
Selects the parent of the node.
prevnode Selects the previous node in preorder to the node.
prevsibling
Selects the previous sibling of the node.
maxnode The maximum node number.
"label"
'label'
label Selects the child node whose label is label.
Enclosing label in quotes (double or single) supports
labels with embedded spaces and prevents matching
reserved words (eg. a node labeled "parentnode"). If
mulitiple child nodes have the same label, the first
matching node is used.
It's an error if the node can't be found. For example, lastchild and
firstchild will generate errors if the node has no children. The
exception to this is the index operation which returns -1, allowing you
to test if a modifier is valid.
TREE OPERATIONS
Once you create a tree object, you can use its Tcl command to query or
modify it. The general form is
treeName operation ?arg?...
Both operation and its arguments determine the exact behavior of the
command. The operations available for trees are listed below.
treeName ancestor node1 node2
Returns the mutual ancestor of the two nodes node1 and node2.
The ancestor can be one of the two nodes. For example, if node1
and node2 are the same nodes, their ancestor is node1.
treeName append node key string ?string ...?
Append one or more strings to node/key value.
treeName appendi tagnode key string ?string ...?
The same as append but accepts a multi-node tag and an undefined
key will be initialized to {}. Returns the number of nodes
updated.
treeName apply node ?switches?
Runs commands for all nodes matching the criteria given by
switches for the subtree designated by node. By default all
nodes match, but you can set switches to narrow the match. This
operation differs from find in two ways: 1) Tcl commands can be
invoked both pre- and post-traversal of a node and 2) the tree
is always traversed in depth first order.
The -exact, -glob, and -regexp switches indicate both what kind
of pattern matching to perform and the pattern. By default each
pattern will be compared with the node label. You can set more
than one of these switches. If any of the patterns match
(logical or), the node matches. If the -key switch is used, it
designates the data field to be matched.
The valid switches are listed below:
-depth number
Descend at most number (a non-negative integer) levels
If number is 1 this means only apply the tests to the
children of node.
-exact string
Matches each node using string. The node must match
string exactly.
-glob string
Test each node to string using global pattern
matching. Matching is done in a fashion similar to
that used by string match.
-invert Invert the results of the pattern matching of -name.
-isleaf Only test nodes with no children.
-istree Only test nodes with children.
-key key
-keyglob key
-keyregexp key
-keyexact key
If pattern matching is selected (using the -exact,
-glob, or -regexp switches), compare the values of the
data field keyed by key instead of the node's label.
If no pattern matching switches are set, then any node
with this data key will match. The field names may
also be patterns using -keyglob, etc.
-nocase Ignore case when matching patterns.
-precommand command
Invoke command for each matching node. Before command
is invoked, the id of the node is appended. You can
control processing by the return value of command. If
command generates an error, processing stops and the
find operation returns an error. But if command
returns break, then processing stops, no error is
generated. If command returns continue, then
processing stops on that subtree and continues on the
next.
-postcommand command
Invoke command for each matching node. Before command
is invoked, the id of the node is appended. You can
control processing by the return value of command. If
command generates an error, processing stops and the
find operation returns an error. But if command
returns break, then processing stops, no error is
generated. If command returns continue, then
processing stops on that subtree and continues on the
next.
-regexp string
Test each node using string as a regular expression
pattern.
-tag string
Only test nodes that have the tag string.
-usepath Use the node's full path when comparing nodes. The
node's full path is a list of labels, starting from
the root of each ancestor and the node label. The
default is to compare only the node label.
treeName attach ?-notags? ?treeObject?
Queries or attaches to an existing tree object treeObject. This
is primarly used where the tree object was previously created
via the C API (eg. via TreeView). The current tree associated
with treeName is discarded. In addition, the current set of
tags, notifier events, and traces are removed. If -notags is
given, tags will not be shared.
treeName children ?-labels? node ?first? ?last?
Returns a list of children for node. If node is a leaf, then an
empty string is returned. If first and/or last are given they
are the integer index of the children to display. If the
-labels option is used, labels are returned instead of the
nodes.
treeName copy srcNode ?destTree? parentNode ?switches?
Copies srcNode into parentNode. Both nodes srcNode and
parentNode must already exist. The id of the new node is
returned. You can copy from one tree to another. If a destTree
argument is present, it indicates the name of the destination
tree. By default both the source and destination trees are the
same. The valid switches are listed below:
-label string
Label destNode as string. By default, destNode has the
same label as srcNode.
-overwrite
Overwrite nodes that already exist. Normally nodes are
always created, even if there already exists a node by
the same name. This switch indicates to add or overwrite
the node's data fields.
-recurse
Recursively copy all the subtrees of srcNode as well. In
this case, srcNode can't be an ancestor of destNode as it
would result in a cyclic copy.
-reverse
Reverse the direction of the copy.
-tags Copy tag inforation. Normally the following node is
copied: its label and data fields. This indicates to
copy tags as well.
treeName create ?switches?
Cause the creation of zero or more nodes. Exactly one of -num,
-nodes or -path is required. This can create all nodes in a
given -path or efficiently populate a tree with large numbers of
nodes. The return values is the id of the last created node (or
-path element). The valid flags for switches are described
below.
-fixed Set the fixed flag.
-data list
Data to set in each node.
-labelstart number
The label generated nodes is to use a sequence number
starting from number. The default is to just use the
node id.
-nodes list
List of nodes ids to create. The -offset option can
specify a constant to add.
-num number
The number of nodes to create.
-offset number
Number to add to each element in -nodes. For example,
if loading sqlite rowids you should use 1. The
default is 0.
-parent node
The node to insert children into. The default is the
root node.
-path pathList
Verify that a path exists and create any missing
nodes. Uses labels in pathList to lookup nodes,
creating them if not found. The id for the last node
in the path is returned (created or not).
-pos number
The position where to insert child nodes. The default
is -1, meaning append.
-prefix str
String prefix to add to each nodes label.
-start number
Node nuber to start from when using -num. The default
is 1.
-tags tagList
List of tags to add to each newly created node.
treeName degree node
Returns the number of children of node.
treeName delete node...
Recursively deletes one or more nodes from the tree. The node
and all its descendants are removed. The one exception is the
root node. In this case, only its descendants are removed. The
root node will remain. Any tags or traces on the nodes are
released.
treeName depth node
Returns the depth of the node. The depth is the number of steps
from the node to the root of the tree. The depth of the root
node is 0.
treeName dictset ?bool?
Get or set the dictset flag for the tree which causes any set of
an array sub-fields to force the value to type dict. Unlike
array types, dicts preserve the order of elements. Setting this
to one has the same effect as using the -dictset flag at tree
creation time.
treeName dump node ?switches?
Save tree data for node and its descendants. With the -file
option, output goes to the file fileName (this is unsupported in
a safe interp). With the -channel option, data is output to
channel chan. If neither option is given, the dump is returned
as data.
The subtree designated by node is traversed to obtain the
following information for each node: 1) the node's path relative
to node, 2) a sublist key value pairs representing the node's
data fields, and 3) a sublist of tags. and 4) the label This
list returned can be used later to copy or restore the tree with
the restore operation.
The valid switches are listed below.
-channel chan
Obtain data from from the given channel chan. The
channel is not closed afterwards.
-file fileName
Obtain data from from the file. fileName. This options
is unsupported in a safe interp.
-keys list
A list of patterns of matching keys to be dumped.
-skipkeys list
A list of patterns of matching keys not to be dumped.
-tag pattern
A pattern match for tags to include in a node dump.
-skiptag pattern
A pattern match for tags to not include in a node dump.
-notags
Do not restore any tags
-nopath
To save space, do not dump the full path for each node.
Instead output periods for all but the last path element.
Full paths are used only for partial restores.
treeName exists node ?key?
Indicates if node exists in the tree. If a key argument is
present then the command also indicates if the named data field
exists.
treeName find ?switches?
Finds for all nodes matching the criteria given by switches for
the subtree designated by node. A list of the selected nodes is
returned. By default all nodes match, but you can set switches
to narrow the match.
The -exact, -glob, and -regexp switches indicate what kind of
pattern matching to perform for -name. By default the pattern
will be compared with the node label. If the -key switch is
used, it designates the data field to be matched.
The order in which the nodes are traversed is controlled by the
-order switch. The possible orderings are preorder, postorder,
inorder, and breadthfirst. The default is preorder.
The valid switches are listed below:
-addtag string
Add the tag string to each selected node. The tag
will be created even if no nodes are tagged.
-column key
Use value with field given by key. Like the treeview
find -column option, this key may contain an array
referrence.
-cmdargs columns
Specify columns whose values are to be appended to
-command.
-command command
Invoke command for each matching node. Before command
is invoked, the id of the node is appended. You can
control processing by the return value of command. If
command generates an error, processing stops and the
find operation returns an error. But if command
returns break, then processing stops, no error is
generated. If command returns continue, then
processing stops on that subtree and continues on the
next. If command returns return, then the returned
integer is used to indicate 1 for match or 0 for
mismatch.
-count Just return the number of matches.
-depth number
Include only nodes with level equal to number.
-exact Matches each node exactly.
-exec script
Specifies a Tcl script to be evaluated for each
matching node. If -var was also specified, that
variable is set with the value of the node id before
each evaluation. Otherwise, percent sustitutions are
performed: note this is much less efficient than using
either -var or -command
The result of each eval gets appended to the return
list, unless the script issues a CONTINUE, in which
case that node is skipped.
The available percent substitutions on string are:
%# The id of the node.
%W The pathname of the tree.
%p The label of the node.
%P The full pathname of the node.
%R The -> delimited path from root, eg.
"root->able->baker->charlie"
%r The -> delimited path from 0, eg.
"0->able->baker->charlie"
%T The dot delimited tag path eg.
".able.baker.charlie"
%V The value if using -key or the label otherwise.
%D The data for the node, ie. like that returned
from get.
%% Translates to a single percent.
-glob Test each node using global pattern matching.
Matching is done in a fashion similar to that used by
the string match.
-invert Invert the pattern matching of -name.
-isarray Only test nodes where the specified -key value is an
array. Can not be used with -name. The -invert flag
will invert the meaning of the check. Note that this
will attempt to convert the key value in each
traversed node into an array type.
-isempty Only match nodes where the specified -column key value
was unset.
-isfixed Only test nodes that have used fixed 1.
-isleaf Only test nodes with no children.
-isnotfixed
Only test nodes that have not used fixed 1.
-istree Only test nodes with children.
-keycount num
Only test if number of keys is equal to num.
-key key
-keyglob key
-keyregexp key
-keyexact key
Compare the values of the data field keyed by key
instead of the node's label. If no -name pattern is
used then any node with this data key will match. The
key names may also be patterns using -keyglob, etc.
-limit number
Stop processing after number (a positive integer)
matches.
-maxdepth number
Include only nodes at level number or less.
-mindepth number
Include only nodes at level number or greater.
-name string
The name to use for pattern matching.
-nocase Ignore case when matching patterns.
-nodes tagnode
Search only in tagnode, which is either a tag or a
list of nodes ids. This makes possible nested
searches. Note this option is incompatible with -top
and -notop.
-notop Exclude the -top or starting node.
-order string
Traverse the tree and process nodes according to
string. String can be one of the following:
breadthfirst
Process the node and the subtrees at each
sucessive level. Each node on a level is
processed before going to the next level.
inorder Recursively process the nodes of the first
subtree, the node itself, and any the
remaining subtrees.
postorder Recursively process all subtrees before the
node.
preorder Recursively process the node first, then any
subtrees (default).
-usepath Use the node's full path when doing the comparison.
The default is to compare only the node label.
-regexp Test each node using regular expression pattern
matching.
-reldepth Change the meaning of -depth, -mindepth and -maxdepth
to be relative to the -top node.
-return key
Return the value of the given key, or the empty string
if none. If the given key is the empty string, the
node label will be returned. If no value was found
and the given key starts with a percent returns the
sustitution as per -exec. Note that a percent
substitution longer than 2 chars will append values as
list elements.
-strict Generate an error if a given key value is unset when
using -return.
-top node Search is only at node and it's descendants. The
default is the root node.
-var variable
A variable to set with the node id before each
iteration of the -exec script.
-withouttag string
Only test nodes that don't have the tag string.
-withtag string
Only test nodes that have the tag string.
treeName findchild node label
Searches for a child node label in node. The id of the child
node is returned if found. Otherwise -1 is returned. This is
the same as using index node->label.
treeName firstchild node
Returns the id of the first child in the node's list of
subtrees. If node is a leaf (has no children), then -1 is
returned.
treeName fixed node ?isfixed?
Get or set the fixed key-fields flag for a node. New key-fields
can be added to a node only if fixed is 0 (the default) If node
is given as an empty string, operates on the tree flag. Note
that copied and restored nodes do not preserve the fixed state.
treeName foreach var tagnode script
Provides a foreach loop for tree. For each node in tagnode the
node-id is assigned to var and then script is evaluated. The
tagnode is either a tag or a list of nodes as described in the
section NODE IDS AND TAGS above.
treeName get node ?key? ?defaultValue?
Returns a list of key-value pairs of data for node. If key is
present, then only the value for that particular data field is
returned. It's normally an error if node does not contain the
data field key. But if you provide a defaultValue argument,
this value is returned instead (node will still not contain
key). This feature can be used to access a data field of node
without first testing if it exists. This operation may trigger
read data traces.
treeName incr node key ?amount?
Increment value by 1 or given amount and return the value. The
incr operation normally tries to use integers, but uses doubles
when one of value or amount is a double.
treeName incri tagnode key ?amount?
The same as incr but accepts a multi-node tag and an undefined
key will be initialized to 0. Returns the number of nodes
updated.
treeName index node
Returns the id of node. In addition to standard node id form,
node can also be a path (a list of labels from the root) as
returned by the path command. If node is invalid, then -1 is
returned.
treeName insert parent ?switches?
Inserts a new node into parent node parent. The id of the new
node is returned. The following switches are available:
-after child
Position node after child. The node child must be a
child of parent.
-before child
Position node before child. The node child must be a
child of parent.
-data dataList
Sets the value for each data field in dataList for the
new node. DataList is a list of key-value pairs. May
not be used in conjuction with -names or -values.
-fixed bool
If bool is 1, set fixed field mode after initializing
the key/value pairs from -data. This disallows
creation of new key fields after the node is created.
If not given, the tree default for fixed is used.
-label string
Designates the labels of the node as string. By
default, nodes are labeled as 0, 1, etc.
-names nameList
The names for the data fields. This must have the
same length as -values, and may not be used in
conjuction with -data.
-node id Designates the id for the node. Normally new ids are
automatically generated. This allows you to create a
node with a specific id. It is an error if the id is
already used by another node in the tree.
-pos number
Inserts the node into parent's list of children at
position number. The default is to append.
-pretags tagList
Adds each tag in tagList to the new node, before data
is added. Unlike -tags, traces on these tags will
fire on key data during the insert.
-tags tagList
Adds each tag in tagList to the new node. TagList is a
list of tags, so be careful if a tag has embedded
space.
-values valueList
The values for the data fields. This must have the
same length as -names, and may not be used in
conjuction with -data.
treeName is property args
Indicates the property of a node. Both property and args
determine the property being tested. Returns 1 if true and 0
otherwise. The following property and args are valid:
ancestor node1 node2
Indicates if node1 is an ancestor of node2.
before node1 node2
Indicates if node1 is before node2 in depth first
traversal.
leaf node Indicates if node is a leaf (it has no subtrees).
root node Indicates if node is the designated root. This can be
changed by the root operation.
treeName ismodified ?nodeOrTag? ?isflag?
Get or set modified state for the tree or nodes. With no args
returns modified state for tree. With one args returns modified
state for a node. With two args set modified state for one or
more nodes. In the last case, where ?nodeOrTag? is the tag all,
the state for the tree is also set.
Newly created nodes are always considered to be modified until
explicitly cleared. After clearing, subsequent updates to keys
or tags will toggle the node (and tree) modified again.
treeName isset node key
Return 1 if key is set in node.
treeName keys node ?tagnode ...?
Return list of unique keys for all of the given nodes in
tagnode. Keys are in no particular order. Accepts nodes and
tags or all. See also names.
treeName label node ?newLabel?
Returns the label of the node designated by node. If newLabel
is present, the node is relabeled using it as the new label.
treeName lappend node key value ?value ...?
Append one or more list values to node/key value.
treeName lappendi tagnode key value ?value ...?
The same as lappend but accepts a multi-node tag and an
undefined key will be initialized to {}. Returns the number of
nodes updated.
treeName lastchild node
Returns the id of the last child in the node's list of subtrees.
If node is a leaf (has no children), then -1 is returned.
treeName modify tagnode key value ?key value...?
Update one or more fields in one or more nodes in tagnode. As
with set, node can be a tag referring to multiple nodes. This
is identical to set, except an error is thrown if any of the key
fields do not exist. Despite the error, all nodes that do have
said fields get updated. For modifying a single node, see
update.
treeName move node newParent ?switches?
Moves node into newParent. Node is appended to the list children
of newParent. Node can not be an ancestor of newParent. The
valid flags for switches are described below.
-after child
Position node after child. The node child must be a
child of newParent.
-before child
Position node before child. The node child must be a
child of newParent.
-pos number
Inserts node into parent's list of children at
position number. The default is -1 to append the node.
treeName names node ?key? ?pattern?
Return key names for node, in the order defined (if possible).
If a key is given, attempts to return ARRAY fields (see DICT-
ARRAYS). If a pattern is given, the array keys are limited to
those matching the glob pattern. An error is thrown if the
convert to array fails (ie. list-length is odd). The type
command can be used to query the type. See also values.
treeName next node
Returns the next node from node in a preorder traversal. If
node is the last node in the tree, then -1 is returned.
treeName nextsibling node
Returns the node representing the next subtree from node in its
parent's list of children. If node is the last child, then -1
is returned.
treeName nodeseq ?start?
Get or set the start sequence number for subsequent node
insertions not using -node. The default is 0.
treeName notify args
Manages notification events that indicate that the tree
structure has been changed. See the NOTIFY OPERATIONS section
below.
treeName oldvalue ?newvalue?
Return the value from before the last (untraced) change
operation. This is used primarly by write traces wishing to
restore a key to it's pre-write value (eg. read-only variables).
The oldvalue is saved internally everytime a change operation
occurs to a key value by deferring its deallocation. Changes
made during node traces do not affect oldvalue.
If newvalue is provided, the current value of oldvalue is
discarded and replaced. This is useful really only for releasing
large objects.
treeName parent node
Returns the parent node of node. If node is the root of the
tree, then -1 is returned.
treeName path node ?delim? ?prefix?
Returns the full path (from root) of node using the node labels.
If delim is not specified, the result is a list. Otherwise, the
result is a string starting with prefix and each element of the
path separated by delim. This latter form is useful for
building tags like: .able.baker
treeName position ?-sort? ?-format ftype? node ?node ...?
Returns the position of the node(s) in its parent's list of
children. Positions are numbered from 0. The position of the
root node is always 0. The value of ftype is one of: position
parent-at-position id+position id+parent-at-position.
treeName previous node
Returns the previous node from node in a preorder traversal. If
node is the root of the tree, then -1 is returned.
treeName prevsibling node
Returns the node representing the previous subtree from node in
its parent's list of children. If node is the first child, then
-1 is returned.
treeName restore node switches
Performs the inverse function of the dump operation, restoring
nodes to the tree. The format of the input data is exactly what
is returned by the dump operation. It's a list containing
information for each node to be restored. The information
consists of 1) the relative path of the node, 2) a sublist of
key value pairs representing the node's data, 3) a list of tags
for the node, and 4) the label. Nodes are created starting from
node. Nodes can be listed in any order. If a node's path
describes ancestor nodes that do not already exist, they are
automatically created.
The valid switches are listed below. Exactly one of -channel,
-file or -data must be specified.
-addtags
List of tags to add to each node restored node. Each tag
will be created only if a node loaded.
-channel chan
Obtain data from from the given channel chan. The
channel is not closed afterwards.
-data string
Data input is from the given string.
-file fileName
Obtain data from from the file. fileName. This options
is unsupported in a safe interp.
-keys list
A list of patterns of matching keys to be restored.
-skipkeys list
A list of patterns of matching keys not to be restored.
-tag pattern
A pattern match for tags to include in a node restore.
-skiptag pattern
A pattern match for tags to not include in a node
restore.
-notags
Do not restore any tags
-overwrite
Overwrite nodes that already exist. Normally nodes are
always created, even if there already exists a node by
the same name. This switch indicates to overwrite
existing node's data fields.
treeName root ?node?
Returns the id of the root node. Normally this is node 0. If a
node argument is provided, it will become the new root of the
tree. This lets you temporarily work within a subset of the
tree. Changing root affects operations such as next, path,
previous, etc.
treeName set tagnode key value ?key value...?
Sets one or more data fields in node. tagode may be a tag that
represents several nodes and a count of the number of nodes
updated is returned. Key is the name of the data field to be
set, or an array-like reference such as field(subkey). See the
DICT-ARRAYS section below. Value is the respective keys value.
The Key will be created if it does not exists (see modify).
The set operation triggers write and create data traces.
treeName size node
Returns the number of nodes in the subtree. This includes the
node and all its descendants. The size of a leaf node is 1.
treeName sort node ?switches?
Return nodes in sorted order.
-ascii Compare strings using the ASCII collation order.
-command string
Use command string as a comparison command. To
compare two elements, evaluate a Tcl script consisting
of command with the five elements appended as
additional arguments: the tree, node1, node1, label1,
label2. The script should return an integer less
than, equal to, or greater than zero if the first
element is to be considered less than, equal to, or
greater than the second, respectively.
-decreasing
Sort in decreasing order (largest items come first).
-dictionary
Compare strings using a dictionary-style comparison.
This is the same as -ascii except (a) case is ignored
except as a tie-breaker and (b) if two strings contain
embedded numbers, the numbers compare as integers, not
characters. For example, in -dictionary mode, bigBoy
sorts between bigbang and bigboy, and x10y sorts
between x9y and x11y.
-integer Compare the nodes as integers.
-key string
Sort based upon the node's data field keyed by string.
Normally nodes are sorted according to their label.
label.
-real Compare the nodes as real numbers.
-recurse Recursively sort the entire subtree rooted at node.
-reorder Recursively sort subtrees for each node. Warning.
Unlike the normal flat sort, where a list of nodes is
returned, this will reorder the tree.
-usepath Compare the full path of each node. The default is to
compare only the node label.
treeName sqlload ?switches? dbhfile sqlstmt
Load tree with the results of evaling the SQL in sqlstmt using
dbhfile. The evaluated SQL creates one tree-node per row
result. The returned value is the number of rows loaded.
Dbhfile is either an sqlite3 database handle, or an sqlite3
file.
The sqlload command can populate a tree with 10k nodes about 7
times faster than sqlite3 eval. It also preserves NULL values
and object types (eg. int or double) used internally by sqlite.
This eliminates later reconversion within tree. See the SQLLOAD
EXAMPLE below.
The following switches are available:
-addtags taglist
The tags in taglist to add to each inserted node.
Each tag will be created only if a node loaded.
-fixed Set the fixed flag to disallow new keys after
creation.
-key name Store the entire result in the key name instead of
creating one key per column. Array notation can be
used to then access column results. This is more
efficent as it initially stores just one object per
row. Conversion to an array is at the first array
access (if that occurs).
-labelcol column
The value of column is used as the label. By default
the label is the node id.
-maprowid num
This option maps the node id to the rowid plus the
constant num. The key for rowid will also not be
created. This is applicable only if rowid is returned
in the result-set of sqlstmt. If rowid is not in the
result set, this option is ignored. If mapping fails
(because the tree already contains a requested node)
the load will abort at that point with an error. Note
that num must be >= 1 since sqlite rowids start from
0, but the root node of the tree uses the node-id 0.
-max num The maximum number of rows to return. The default is
100,000. Note that SQL queries on large tables should
probably always use LIMIT.
-nullvalue string
Define value to use for null values. The default is
no value, meaning do not set key if value is null.
Note this is different from the sqlite Tcl extension
which uses an empty string for NULL.
-parent string
The node where results are inserted as child nodes.
The default is the tree root.
-pathcol column
Name of column containing the full path where node is
to be created. This works like -treecols, but uses a
singl columns.
-skipcols columns
The given columns are not to be added as keys. This
is useful mostly in conjuction with -tagcol,
-labelcol, -pathcol.
-pos num Where to insert into parents list of children.
Default is -1, meaning to append.
-tagcol column
The value of column is added as a tag.
-treecols columns
Columns whose values concatenated give the path of
where node is to be created. This works like
-pathcol, but uses multiple columns.
treeName sum ?switches? tagnode key ?key ...?
Add values in key fields for all tagnode and return the sum.
Values that are not doubles (or integer) are ignored.
-diff value
Double value difference to ignore and not do update
for -runtotal. This is unused when using -int.
-force Force update -runtotal even if value was unchanged.
Normally, a check is made to avoid updating unchanged
values.
-int Use and accept only integer values.
-runtotal key
Place running total in the given key field (if
changed).
-start num
The start value for the sum: default is 0.
treeName supdate node key value ?key value...?
Like update, but uses a string comparison to avoid writes if the
value will not be changed. This is useful primarily for
avoiding unnecessary write traces.
treeName tag args
Manages tags for the tree object. See the TAG OPERATIONS
section below.
treeName trace args
Manages traces for data fields in the tree object. Traces cause
Tcl commands to be executed whenever a data field of a node is
created, read, written, or unset. Traces can be set for a
specific node or a tag, representing possibly many nodes. See
the TRACE OPERATIONS section below.
treeName type node key
Return type of value. This is the introspected type from the
Tcl_Obj value passed to set.
treeName update node key value ?key value...?
Like modify, except an error is generated if a tag is used that
applies to more than one node.
treeName unset node key...
Removes one or more data fields from node. Node may be a tag
that represents several nodes. Key is the name of the data
field to be removed. It's not an error is node does not contain
key. A count of the number of nodes unset is returned. This
operation may trigger unset data traces.
treeName values node ?key? ?withnames?
Return values for node. The values are returned in the same
order as the keys returned from names.
If a key is given, array values get returned for the key value.
If withname is True, then key names are also returned with the
values. This differs from get in that the result is a true Tcl
list object, not an array object. If subsequently using an
array value in a list context, this can be more efficient by
avoiding a split on string representations.
treeName vecdump vector key ?tagnode?
Dump key field to a vector. With no tagnode, dumps every node
to the 1-1 corresponding vector index. With tag dumps nodes to
consequetive vector elements.
treeName vecload vector key ?tagnode?
Loads key field from a vector. With no tagnode, loads every
node from the 1-1 corresponding vector index. With tag loads
nodes from consequetive vector elements.
treeName with variable ?switch? tagnode script
For each node in tagnode, evaluate the script after assigning
key values to elements of the array variable. The -keys limits
which keys may be assigned. If script completes normally, and
any of the key values change in the variable, then the updates
are reflected back into the key values (unless -noupdate is
used). Unsetting a variable key will cause that change to be
ignored. New elements added to the array variable are ignored.
Doing a return, break, or continue inside script will still
cause updates to copy back, but processing will stop and (unless
-break is used) the return code will become the return code to
the caller. This means that a break, continue, and return will
propagate up through multiple nested with statements to the to
an enclosing foreach, while, etc. But -break can be used to
change this, making with behave more like a foreach loop.
If -keys is not used, the list of key names will be stored in
variable(*) and the node id stored in variable(#) (which could
then be overwritten by a key of that name). By default, the
array is not cleaned up before or after each execution.
However, if -unset is used, the array is unset at the start of
each iteration, and -init can be used to specify a default
value. Also, long running queries can speed up by initializing
variables prior to the call to with.
If the variable name string is zero length, an simple variables
are used instead of an array, and * and # do not get set. Note,
when not using -keys, arbitrary local variables can get
overwritten.
If -array is used, with operates on the keys of an tree
array/dict instead of the keys of the node.
Upon normal completion, the number of times script was evaluated
is returned.
The valid switches are listed below:
-array key
Specifies a single key that is to be treated as an
array-dict. The fields of the array for that one key
are then used (instead of keys from the whole node).
This changes the meaning of -keys and -glob to be the
keys of the array rather than the keys of the node.
Nodes missing the given array key will be skipped. If
a key value can not be converted to an array, an error
will occur.
-break Treat break and continue like foreach does rather than
just passing them up to the enclosing script body.
-init value
Variables specified by -keys are to be initialized to
value for each node where key is missing.
-keys keylist
Copy only the named keys and does not set (*).
-glob pattern
Pattern to limit matching keys. Can not be used with
-keys.
-noupdate Ignore changes to array variables. This do not copy
changed variables back into tree nodes.
-unset Unset the array variable at the begin of each
evaluation.
DICT-ARRAYS
Round braces can be used to access sub-values of a key value. In
effect, this means each key value can be an array (or dict), eg.
set t [tree create]
set n [$t insert 0 -data {a 1 b 2 c "x 9 y 8 z 7"}]
$t get $n; # a 1 b 2 c {x 9 y 8 z 7}
$t get $n c; # x 9 y 8 z 7
$t get $n c(y); # 8
$t update $n c(y) 8.6
$t get $n c; # x 9 y 8.6 z 7
$t unset $n c(y)
$t get $n c; # x 9 z 7
$t set $n d 10
$t incr $n d
If a key value is a dict object tree will make use of it. If not, on
access it converts the value to a pure array hash object. The
following example shows the type in a comment after each operation.
set t [tree create]
$t insert 0 -label A;
$t set 0->A X [dict create a 1 b 2 c 3]; # dict
array set q { x 1 y 2 };
$t set 0->A Y [array get q]; # dict
$t set 0->A Z {m 0 n 1}; # string
$t incr 0->A Z(m); # array
dict size [$t get 0->A Z]; # dict
One advantage of using a dict is that it preserves order. See dictset.
TAG OPERATIONS
Tags are a general means of selecting and marking nodes in the tree. A
tag is just a string of characters, and it may take any form except
that of an integer. The same tag may be associated with many different
nodes.
Most tree operations use tags. And several operations let you operate
on multiple nodes at once. For example, you can use the set operation
with the tag all to set a data field in for all nodes in the tree.
Tags are invoked by the tag operation. The general form is
treeName tag operation ?arg?...
Both operation and its arguments determine the exact behavior of the
command. The operations available for tags are listed below.
treeName tag add string ?node?...
Adds the tag string to zero or more nodes. If no nodes are
given, just creates the tag. A count of the number of nodes
tagged is returned.
treeName tag delete string node...
Remove the tag string from one or more nodes. A count of the
number of nodes visited is returned. Calling tag delete with a
builtin tag is ignore.
treeName tag dump tagnode ?switches?
Dump the nodes specified by the tag tagnode.
The valid switches are listed below.
-keys list
A list of patterns of matching keys to be dumped.
-skipkeys list
A list of patterns of matching keys not to be dumped.
-tag pattern
A pattern match for tags to include in a node dump.
-skiptag pattern
A pattern match for tags to not include in a node dump.
-notags
Do not dump the tags.
-nopath
To save space, do not dump the full path for each node.
Instead output periods for all but the last path element.
Full paths are used only for partial restores.
treeName tag exists string ?id?
If an id is given, return 1 (or 0) if node has (or hasn't) the
tag. Otherwise, returns 1 if at least one nodes has tag string.
treeName tag forget string ?string ...?
Removes the tag definition for one or more of string. It's not
an error if the tag string does not exist.
treeName tag lookups ?pattern?
Dump a lookup table (dictionary) of nodes-to-tags, or tags-to-
nodes if pattern is given. With no arguments, returns a pair
list of nodes/tags, for nodes that have tags. With an argument,
returns a pair list of tags/nodes. lookups provides efficient
bulk processing when dealing with large numbers of nodes and/or
tags.
treeName tag names ?-glob? ?-regexp? ?-nocase? ?node? ?node ...?
Returns a list of tags used by the tree. If no node argument is
given, returns a list of all known tags. Otherwise, returns the
union of the tags used by all given node numbers. Patterns can
be used via -glob or -regexp. If -nocase is used, the pattern
is expected to be all lower case.
treeName tag nodes string ?string ...?
Returns a list of any nodes that have any of given string tag.
If no node is tagged with any of the string, then an empty
string is returned.
TRACE OPERATIONS
Data fields can be traced much like tracing Tcl variables. Data traces
cause a Tcl command to be executed whenever data fields are created,
read, written, or unset. A trace can apply to one or more nodes. You
can trace a specific node by using its id, or a group of nodes by a
their tag. Note: operations on arrays trigger on the whole key value,
not the individual array element.
The tree's get, set, and unset operations can trigger various traces.
The get operation can cause a read trace to fire. The set operation
causes a write trace to fire. And if the data field is written for the
first time, you will also get a create trace. The unset operation
triggers unset traces.
Data traces are invoked by the trace operation. The general form is
treeName trace operation ?arg?...
Both operation and its arguments determine the exact behavior of the
command. The operations available for traces are listed below.
treeName trace create node key ops command ?-bgerror?
Create a trace on data fields (or tags for tag traces) given by
the pattern in key. The node argument can be a nodeid, or a tag
to refer to multiple nodes eg. all. The return value is an
identifier that can be used with "trace info" or "trace delete".
Traces are temporarily disabled while executing command within
the trace.
Command is a command prefix, to which four arguments are
appended before invocation: treeName, nodeid, key and, ops. If
an error occurs in command (and -bgerror was not used) the
invoking operation will also abort.
Ops indicates which operations are of interest. It consists of
one or more of the following letters:
r Invoke command whenever key is read.
w Invoke command whenever key is written.
c Invoke command whenever key is created.
u Invoke command whenever key is unset, typically with the
unset command. to that.
e Invoke command whenever exists is used on an non-existant
key. This can be used to populate node key data on
demand.
t Invoke command whenever tag key is added to a node.
m Invoke command when tag key gets added to more than one
node. This trace can be used to enforce tags that should
be on at most one node. It can avoid later errors with
tags used in get or other commands not accepting non-
unique tags.
d Invoke command whenever tag key is deleted from a node
using either tag delete or tag forget. Node deletion
will not trigger this trace.
treeName trace delete traceId...
Deletes one of more traces. TraceId is the trace identifier
returned by the trace create operation.
treeName trace info traceId
Returns information about the trace traceId. TraceId is a trace
identifier previously returned by the trace create operation.
It's the same information specified for the trace create
operation. It consists of the node id or tag, data field key, a
string of letters indicating the operations that are traced
(it's in the same form as ops) and, the command prefix.
treeName trace names
Returns a list of identifers for all the current traces.
NOTIFY OPERATIONS
The purpose of notify is to get control when structural operations
occur on a tree. This is used internally by treeview or example when a
tree object is shared. A client may create nodes, sort a tree, move a
node, etc. Notifier can cause such operations to generate events,
resulting in Tcl commands being executed.
The general form of notify is:
treeName notify operation ?arg?...
The available operation are as follows:
treeName notify create ?switches? command ?args?...
Creates a notifier for the tree. A notify identifier in the
form "notify0", "notify1", etc. is returned.
Command and args are saved and invoked whenever the tree
structure is changed (controlled by switches). Two arguments are
appended to command and args before it's invoked: the id of the
node and a string representing the type of event that occured.
If an error is returned by command the invoking operation
returns an error (when not using -whenidle). One or more of the
following switches are used to indicate the events that are of
interest:
-bgerror Generate a background error if an error occurs.
-create Invoke command whenever a new node is added. This is
called after the creation. Returning an error will
delete the node.
-delete Invoke command whenever a node has been deleted. This
is called before the delete starts to allow aborting
it with an error. Deletes resulting from failed
inserts are ignored.
-disabletrace
Disable traces from firing during a notify event.
-get Invoke command whenever a node with no keys is
accessed (via get or with). If a node has at least
one key, this will not trigger. The invocation occurs
before the read, meaning it can be used to implement
demand loading of data keys into empty nodes (eg.
loading database row data on read).
-insert Invoke command when an insert completes. This differs
from -create in that the call occurs after the label,
tags and data are added (but before -fixed gets set).
This trace applies to the subcommands create, copy,
restore, sqlload, and insert (both tree and treeview).
It is useful for verifying key-data, tags and labels.
Returning an error will delete the node and cause the
originating command to generate an error.
-move Invoke command at the start of a node move.
-movepost Invoke command after a node has been moved.
-sort Invoke command whenever the tree has been sorted and
reordered.
-relabel Invoke command at the start of a node relabel.
-relabelpost
Invoke command after a node has been relabeled.
-allevents
Invoke command whenever any of the above events occur.
-whenidle When an event occurs don't invoke command immediately,
but queue it to be run the next time the event loop is
entered and there are no events to process. If
subsequent events occur before the event loop is
entered, command will still be invoked only once.
treeName notify delete notifyId
Deletes one or more notifiers from the tree. NotifyId is the
notifier identifier returned by the notify create operation.
treeName notify info notifyId
Returns information about the notify event notifyId. NotifyId
is a notify identifier previously returned by the notify create
operation. It's the same information specified for the notify
create operation. It consists of the notify id, a sublist of
event flags (it's in the same form as flags) and, the command
prefix.
treeName notify names
Returns a list of identifers for all the current notifiers.
TABLE EXAMPLE
The following is a simple example.
variable Users {
tom { Name "Tom Brown" Sex M Age 19 Class {4 5} Rate {A 1 B 2}}
mary { Name "Mary Brown" Sex F Age 16 Class {5} Rate {A 2}}
sam { Name "Sam Spade" Sex M Age 19 Class {3 4} Rate {B 3}}
}
set t [tree create]
foreach {i d} $Users {
# Use name in -tags so we don't have to do "0->mary" etc.
$t insert 0 -tags $i -data $d -label $i
}
$t update tom Sex F Name "Tomi Brown"
$t append sam Name " Jr"
$t lappend sam Class 5
$t incr mary Age
$t update tom Rate(A) 2
$t incr 0->mary Age
# Set a trace.
proc ::Aupd {t id key op} { tclLog "AA: $t $id $key $op" }
$t trace create all Age w ::Aupd
$t incr mary Age
# Display it.
pack [treeview .t -tree $t] -fill both -expand y
eval .t column insert end [$t keys all]
TREE EXAMPLE
The following is a nested tree example with updates.
variable Info {
system {
sol { OS Linux Version 3.4 }
bing { OS Win Version 7 }
gui { OS Mac Version 8 }
}
network {
intra { Address 192.168.1 Netmask 255.255.255.0 }
dmz { Address 192.168.10 Netmask 255.255.255.0 }
wan { Address 0.0.0.0 Netmask 0.0.0.0 Class {A 1 B 4}}
}
admins {
sully { Name "Sully Van Damme" Level 3 }
maverick { Name "Maverick Gump" Level 1 }
}
}
set s [tree create]
foreach {n vals} $Info {
set ind [$s insert 0 -label $n]
foreach {i d} $vals {
$s insert $ind -label $i -data $d
}
}
set old [$s get 0->system->bing]
$s update 0->system->bing OS Linux Version 3.4
$s update 0->network->dmz Address 192.168.11
$s update 0->network->wan Class(A) 2
eval $s set 0->system->bing $old
$s insert 0->admins -label linus -data { Name "Linus Torvalds" Level 9 }
pack [treeview .s -tree $s -width 600] -fill both -expand y
eval .s column insert end [$s keys all]
SQLLOAD EXAMPLE
Here is an example using sqlload on table cust from a database file,
and displaying it in a treeview:
set t [tree create]
$t sqlload mydb.dat "select rowid,* from cust"
pack [treeview .t -tree $t -width 500] -fill both -expand y
eval .t column insert end [lsort [$t keys all]]
Although there is no corresponding sqldump command, scripting it is
easy. Following is one approach.
proc sqldump {t db table {ids {}}} {
# Dump nodes from tree t into table in open sqlite database db.
if {$ids == {}} { set ids [$t children root] }
set keys [$t keys $ids]
catch { $db eval "CREATE TABLE $table ( [join $keys ,] )" }
$t with s $ids {
set nams {}
set vals {}
foreach nam $s(*) {
lappend vals ($nam)
lappend nams $nam
}
set vals [join $vals ,]
set nams [join $nams ,]
set q [format {INSERT INTO %s (%s) VALUES (%s)} $table $nams $vals]
$db eval $q
}
}
sqlite3 [set db dbhandle] mydb.dat
sqldump $t $db cust2
TREE KEY STRING STORAGE
Key name strings are stored by default in a global hash table.
However, sometimes this can be undesirable (eg. with threading), and so
the behavior may be changed (at tree create time only). To enable per-
interp storage of keys, set blt::treeKeysLocal to 1 before tree
creation. To enable per-tree storage of keys, set blt::treeKeysLocal
to 2 before tree creation. The above is unavailable in safe interps.
C LANGUAGE API
Blt_TreeApply, Blt_TreeApplyBFS, Blt_TreeApplyDFS, Blt_TreeChangeRoot,
Blt_TreeCreate, Blt_TreeCreateEventHandler, Blt_TreeCreateNode,
Blt_TreeCreateTrace, Blt_TreeDeleteEventHandler, Blt_TreeDeleteNode,
Blt_TreeDeleteTrace, Blt_TreeExists, Blt_TreeFindChild,
Blt_TreeFirstChild, Blt_TreeFirstKey, Blt_TreeGetNode,
Blt_TreeGetToken, Blt_TreeGetValue, Blt_TreeIsAncestor,
Blt_TreeIsBefore, Blt_TreeIsLeaf, Blt_TreeLastChild, Blt_TreeMoveNode,
Blt_TreeName, Blt_TreeNextKey, Blt_TreeNextNode, Blt_TreeNextSibling,
Blt_TreeNodeDegree, Blt_TreeNodeDepth, Blt_TreeNodeId,
Blt_TreeNodeLabel, Blt_TreeNodeParent, Blt_TreePrevNode,
Blt_TreePrevSibling, Blt_TreeRelabelNode, Blt_TreeReleaseToken,
Blt_TreeRootNode, Blt_TreeSetValue, Blt_TreeSize, Blt_TreeSortNode, and
Blt_TreeUnsetValue.
KEYWORDS
tree, treeview, widget
BLT 2.5 tree(n)