tree - Create and manage tree data objects.
tree create ?-fixed? ?-dictset?
?-keyhash N? ?treeName?
tree destroy treeName...
tree names ?pattern?
tree op subcmd ?subsubcmd ...?
treeName ?arg arg ...?
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.
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.
- 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.
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.
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.
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 information. 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.
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.
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.
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.
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.
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]
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]
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 $s($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
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.
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.