--- /dev/null
+'\"
+'\" Copyright 1991-1997 by Lucent Technologies, Inc.
+'\"
+'\" Permission to use, copy, modify, and distribute this software and its
+'\" documentation for any purpose and without fee is hereby granted, provided
+'\" that the above copyright notice appear in all copies and that both that the
+'\" copyright notice and warranty disclaimer appear in supporting documentation,
+'\" and that the names of Lucent Technologies any of their entities not be used
+'\" in advertising or publicity pertaining to distribution of the software
+'\" without specific, written prior permission.
+'\"
+'\" Lucent Technologies disclaims all warranties with regard to this software,
+'\" including all implied warranties of merchantability and fitness. In no event
+'\" shall Lucent Technologies be liable for any special, indirect or
+'\" consequential damages or any damages whatsoever resulting from loss of use,
+'\" data or profits, whether in an action of contract, negligence or other
+'\" tortuous action, arising out of or in connection with the use or performance
+'\" of this software.
+'\"
+'\" Tree command created by George Howlett.
+'\" Extensive cleanups and enhancements by Peter MacDonald.
+'\"
+.so man.macros
+.TH tree n BLT_VERSION BLT "BLT Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+tree \- Create and manage tree data objects.
+.SH SYNOPSIS
+\fBtree create\fR ?\fB-fixed\fR? ?\fB-dictset\fR? ?\fB-keyhash\fR \fIN\fR? ?\fItreeName\fR?
+.sp
+\fBtree destroy\fR \fItreeName\fR...
+.sp
+\fBtree names\fR ?\fIpattern\fR?
+.sp
+\fBtree op\fR \fIsubcmd\fR ?\fIsubsubcmd ...\fR? \fItreeName\fR ?\fIarg arg ...\fR?
+.BE
+.SH DESCRIPTION
+The \fBtree command\fR is used to create, destroy, and
+provide Tcl access to a \fBtree object\fR.
+A \fBtree object\fR
+is an ordered tree of nodes where each node can have
+data key-values, tags and a label.
+The \fBtreeview\fR widget uses a \fBtree object\fR.
+
+.SH INTRODUCTION
+
+Tree provides Tcl with a rich API for managing complex data structures.
+Here is a simple example.
+.PP
+.CS
+ 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]
+.CE
+.PP
+Labels provide convenient \fB->\fR indexing relative a starting node.
+.PP
+Nodes may also be created with initial data values.
+.PP
+.CS
+ $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
+.CE
+.PP
+Note round braces are used to access sub-values in a \fBdict-array\fR.
+See the section
+.SB "DICT-ARRAYS"
+below for details.
+.CE
+.SH SYNTAX
+.TP
+\fBtree create\fR ?\fB-fixed\fR? ?\fB-dictset\fR? ?\fB-keyhash\fR \fIN\fR? ?\fItreeName\fR?
+Creates a new tree object. The name of the new tree is returned
+and a Tcl command is created.
+If no \fItreeName\fR argument is present, then the name of the tree is
+automatically generated in the form "\fBtree0\fR", "\fBtree1\fR",
+etc relative to the current namespace.
+A tree name (if given) can not start with a dash.
+Tree names containing the substring "\fB#auto\fR" will
+be replaced with a generated identifier. For example, the
+name \fBdata#auto\fR will translate to \fBdatatree0\fR.
+Note that when
+the Tcl command is deleted the \fBtree object\fR also gets freed.
+.sp
+Newly created trees always contain a single root node with id \fB0\fR
+that can not be deleted.
+.sp
+Switches for \fBcreate\fR are listed below:
+.RS
+.TP 1i
+\fB\-fixed\fR
+Make \fBinsert\fR automatically set the \fB\-fixed\fR flag.
+This will disallow later setting of keys not given
+as \fI\-data\fR to the insert. This includes dict-array keys.
+See the \fBfixed\fR sub-command.
+.TP 1i
+\fB\-dictset\fR
+Define that any update of an \fBarray\fR field will coerce the
+array object to a dict object.
+a dict will preserve order of sub-field keys on update.
+See the \fBdictset\fR sub-command.
+.TP 1i
+\fB\-keyhash\fR \fIsize\fR
+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
+\fIsize\fR keys are added to a node, key storage converts to a hash.
+This affects the order of key iteration (eg. for \fBget\fR/\fBnames\fR/\fBvalues\fR).
+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 \fIsize\fR (eg. 1000000).
+.RE
+
+.TP
+\fBtree destroy\fR \fItreeName\fR...
+Releases one of more trees. The Tcl command associated with
+\fItreeName\fR is also removed. Trees are reference counted. The
+internal tree data object isn't destroyed until no one else is using
+the tree.
+.TP
+\fBtree names\fR ?\fIpattern\fR?
+Returns the names of all tree objects. if a \fIpattern\fR argument
+is given, then the only those trees whose name matches pattern will
+be listed.
+.TP
+\fBtree op\fR \fIsubcmd\fR ?\fIsubsubcmd ...\fR? \fItreeName\fR ?\fIarg arg ...\fR?
+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.
+.SH 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.
+.PP
+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, "\fBx123\fR" is valid, but "\fB123x\fR"
+is not. The same tag may be associated with one
+or multiple nodes (ranges or \fItagnode\fR).
+Ranges are commonly used to group nodes in various interesting ways.
+.PP
+Commands that take a \fItagnode\fR 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 \fBeval\fR.
+.PP
+There are four built-in or psuedo tags:
+.RS
+.TP 1i
+\fBall\fR
+Applies to every node in the tree.
+.TP 1i
+\fBnonroot\fR
+Applies to every node in the tree except the root node.
+.TP 1i
+\fBrootchildren\fR
+Applies to every node in the tree whose parent is the root node.
+.TP 1i
+\fBroot\fR
+Managed automatically by the tree object, \fBroot\fR specifies the node
+that is currently set as the root node for the tree.
+.RE
+.PP
+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 \fInode\fR is used below to indicate that an argument specifies
+either an id or a tag that selects a single node.
+A \fItagnode\fR 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 \fInode\fR is specified in a way that names multiple items, then
+an error "refers to more than one node" is generated.
+.SH 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 \fB->\fR.
+A modifier refers to a node
+in relation to the specified node. For example,
+"\fBroot->firstchild\fR"
+selects the first subtree of the root node.
+.PP
+The following modifiers are available:
+.RS
+.TP 1i
+\fBfirstchild\fR
+Selects the first child of the node.
+.TP 1i
+\fBlastchild\fR
+Selects the last child of the node.
+.TP 1i
+\fBnextnode\fR
+Selects the next node in preorder to the node.
+.TP 1i
+\fBnextsibling\fR
+Selects the next sibling of the node.
+.TP 1i
+\fBparentnode\fR
+Selects the parent of the node.
+.TP 1i
+\fBprevnode\fR
+Selects the previous node in preorder to the node.
+.TP 1i
+\fBprevsibling\fR
+Selects the previous sibling of the node.
+.TP 1i
+\fBmaxnode\fR
+The maximum node number.
+.TP 1i
+"\fIlabel\fR"
+.TP 1i
+\'\fIlabel\fR'
+.TP 1i
+\fIlabel\fR
+Selects the child node whose label is \fIlabel\fR. Enclosing \fIlabel\fR 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.
+.RE
+.PP
+It's an error if the node can't be found. For example,
+\fBlastchild\fR and \fBfirstchild\fR will generate errors if the node
+has no children. The exception to this is the \fBindex\fR operation which
+returns -1, allowing you to test if a modifier is valid.
+.SH TREE OPERATIONS
+Once you create a tree object, you can use its Tcl command
+to query or modify it. The
+general form is
+.DS
+\fItreeName\fR \fIoperation\fR ?\fIarg\fR?...
+.DE
+Both \fIoperation\fR and its arguments determine the exact behavior of
+the command. The operations available for trees are listed below.
+.TP
+\fItreeName\fR \fBancestor\fR \fInode1\fR \fInode2\fR
+Returns the mutual ancestor of the two nodes \fInode1\fR and
+\fInode2\fR. The ancestor can be one of the two nodes. For example,
+if \fInode1\fR and \fInode2\fR are the same nodes, their ancestor is
+\fInode1\fR.
+.TP
+\fItreeName\fR \fBappend\fR \fInode key\fR \fIstring\fR ?\fIstring ...\fR?
+Append one or more strings to node/key value.
+.TP
+\fItreeName\fR \fBappendi\fR \fItagnode key\fR \fIstring\fR ?\fIstring ...\fR?
+The same as \fBappend\fR but accepts a multi-node tag and an
+undefined key will be initialized to {}. Returns the number of nodes
+updated.
+.TP
+\fItreeName\fR \fBapply\fR \fInode\fR ?\fIswitches\fR?
+Runs commands for all nodes matching the criteria given by
+\fIswitches\fR for the subtree designated by \fInode\fR. By default
+all nodes match, but you can set switches to narrow the match. This
+operation differs from \fBfind\fR 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.
+.sp
+The \fB\-exact\fR, \fB\-glob\fR,
+and \fB\-regexp\fR 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 \fB\-key\fR switch is
+used, it designates the data field to be matched.
+.sp
+The valid switches are listed
+below:
+.RS
+.TP 1i
+\fB\-depth\fR \fInumber\fR
+Descend at most \fInumber\fR (a non-negative integer) levels
+If \fInumber\fR is \fB1\fR this means only apply the tests
+to the children of \fInode\fR.
+.TP 1i
+\fB\-exact\fR \fIstring\fR
+Matches each node using \fIstring\fR. The node must match \fIstring\fR
+exactly.
+.TP 1i
+\fB\-glob\fR \fIstring\fR
+Test each node to \fIstring\fR using global pattern
+matching. Matching is done in a fashion similar to that used by
+\fBstring match\fR.
+.TP 1i
+\fB\-invert\fR
+Invert the results of the pattern matching of \fB-name\fR.
+.TP 1i
+\fB\-isleaf\fR
+Only test nodes with no children.
+.TP 1i
+\fB\-istree\fR
+Only test nodes with children.
+.TP 1i
+\fB\-key\fR \fIkey\fR
+.TP 1i
+\fB\-keyglob\fR \fIkey\fR
+.TP 1i
+\fB\-keyregexp\fR \fIkey\fR
+.TP 1i
+\fB\-keyexact\fR \fIkey\fR
+If pattern matching is selected (using the \fB\-exact\fR,
+\fB\-glob\fR, or \fB\-regexp\fR switches), compare the values of the
+data field keyed by \fIkey\fR 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 \fB-keyglob\fR, etc.
+.TP 1i
+\fB\-nocase\fR
+Ignore case when matching patterns.
+.TP 1i
+\fB\-precommand\fR \fIcommand\fR
+Invoke \fIcommand\fR for each matching node. Before \fIcommand\fR is
+invoked, the id of the node is appended. You can control
+processing by the return value of \fIcommand\fR. If \fIcommand\fR
+generates an error, processing stops and the \fBfind\fR operation
+returns an error. But if \fIcommand\fR returns \fBbreak\fR, then
+processing stops, no error is generated. If \fIcommand\fR returns
+\fBcontinue\fR, then processing
+stops on that subtree and continues on the next.
+.TP 1i
+\fB\-postcommand\fR \fIcommand\fR
+Invoke \fIcommand\fR for each matching node. Before \fIcommand\fR is
+invoked, the id of the node is appended. You can control
+processing by the return value of \fIcommand\fR. If \fIcommand\fR
+generates an error, processing stops and the \fBfind\fR operation
+returns an error. But if \fIcommand\fR returns \fBbreak\fR, then
+processing stops, no error is generated. If \fIcommand\fR returns
+\fBcontinue\fR, then processing
+stops on that subtree and continues on the next.
+.TP 1i
+\fB\-regexp\fR \fIstring\fR
+Test each node using \fIstring\fR as a regular expression pattern.
+.TP 1i
+\fB\-tag\fR \fIstring\fR
+Only test nodes that have the tag \fIstring\fR.
+.TP 1i
+\fB\-usepath\fR
+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.
+.RE
+.TP
+\fItreeName\fR \fBattach\fR ?\fB-notags\fR? ?\fItreeObject\fR?
+Queries or
+attaches to an existing tree object \fItreeObject\fR. This is primarly
+used where the tree object was previously created via the C API (eg.
+via TreeView). The current
+tree associated with \fItreeName\fR is discarded. In addition, the
+current set of tags, notifier events, and traces are removed.
+If \fB-notags\fR is given, tags will not be shared.
+.TP
+\fItreeName\fR \fBchildren\fR ?\fB-labels\fR? \fInode\fR ?\fIfirst\fR? ?\fIlast\fR?
+Returns a list of children for \fInode\fR. If \fInode\fR is a leaf,
+then an empty string is returned. If \fIfirst\fR and/or \fIlast\fR
+are given they are the integer index of the children to display.
+If the \fB-labels\fR option is used,
+labels are returned instead of the nodes.
+.TP
+\fItreeName\fR \fBcopy\fR \fIsrcNode\fR ?\fIdestTree\fR? \fIparentNode\fR ?\fIswitches\fR?
+Copies \fIsrcNode\fR into \fIparentNode\fR. Both nodes \fIsrcNode\fR and
+\fIparentNode\fR must already exist. The id of the new node is
+returned. You can copy from one tree to another. If a \fIdestTree\fR
+argument is present, it indicates the name of the destination tree.
+By default both the source and destination trees are the same. The valid
+\fIswitches\fR are listed below:
+.RS
+.TP
+\fB\-label\fR \fIstring\fR
+Label \fIdestNode\fR as \fIstring\fR. By default, \fIdestNode\fR has
+the same label as \fIsrcNode\fR.
+.TP
+\fB\-overwrite\fR
+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.
+.TP
+\fB\-recurse\fR
+Recursively copy all the subtrees of \fIsrcNode\fR as well. In this case,
+\fIsrcNode\fR can't be an ancestor of \fIdestNode\fR as it would result
+in a cyclic copy.
+.TP
+\fB\-reverse\fR
+Reverse the direction of the copy.
+.TP
+\fB\-tags\fR
+Copy tag inforation. Normally the following node is copied: its
+label and data fields. This indicates to copy tags as well.
+.RE
+.TP
+\fItreeName\fR \fBcreate\fR ?\fIswitches\fR?
+Cause the creation of zero or more nodes.
+Exactly one of \fB-num\fR, \fB-nodes\fR or \fB-path\fR is required.
+This can create all nodes in a given \fB-path\fR
+or efficiently populate a tree with large numbers
+of nodes.
+The return values is the id of the last created node (or \fB-path\fR element).
+The valid flags for \fIswitches\fR are described below.
+.RS
+.TP 1i
+\fB\-fixed\fR
+Set the fixed flag.
+.TP 1i
+\fB\-data\fR \fIlist\fR
+Data to set in each node.
+.TP 1i
+\fB\-labelstart\fR \fInumber\fR
+The label generated nodes is to use
+a sequence number starting from \fInumber\fR.
+The default is to just use the node id.
+.TP 1i
+\fB\-nodes\fR \fIlist\fR
+List of nodes ids to create.
+The \fB\-offset\fR option can specify
+a constant to add.
+.TP 1i
+\fB\-num\fR \fInumber\fR
+The number of nodes to create.
+.TP 1i
+\fB\-offset\fR \fInumber\fR
+Number to add to each element in \fB-nodes\fR.
+For example, if loading sqlite rowids you should use 1.
+The default is 0.
+.TP 1i
+\fB\-parent\fR \fInode\fR
+The \fInode\fR to insert children into.
+The default is the root node.
+.TP 1i
+\fB\-path\fR \fIpathList\fR
+Verify that a path exists and create any missing nodes.
+Uses labels in \fIpathList\fR to lookup nodes, creating
+them if not found. The id for the last
+node in the path is returned (created or not).
+.TP 1i
+\fB\-pos\fR \fInumber\fR
+The position where to insert child nodes.
+The default is -1, meaning append.
+.TP 1i
+\fB\-prefix\fR \fIstr\fR
+String prefix to add to each nodes label.
+.TP 1i
+\fB\-start\fR \fInumber\fR
+Node nuber to start from when using \fB-num\fR. The default is 1.
+.TP 1i
+\fB\-tags\fR \fItagList\fR
+List of tags to add to each newly created node.
+.RE
+.TP
+\fItreeName\fR \fBdegree\fR \fInode\fR
+Returns the number of children of \fInode\fR.
+.TP
+\fItreeName\fR \fBdelete\fR \fInode\fR...
+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.
+.TP
+\fItreeName\fR \fBdepth\fR \fInode\fR
+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 \fB0\fR.
+.TP
+\fItreeName\fR \fBdictset\fR ?\fIbool\fR?
+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 \fB-dictset\fR
+flag at tree creation time.
+.TP
+\fItreeName\fR \fBdump\fR \fInode\fR ?\fIswitches\fR?
+Save tree data for \fInode\fR and its descendants.
+With the \fB-file\fR option, output goes to the file
+\fIfileName\fR (this is unsupported in a safe interp).
+With the \fB-channel\fR option, data is output to channel \fIchan\fR.
+If neither option is given, the dump is returned as data.
+.sp
+The subtree designated by \fInode\fR is
+traversed to obtain the following information for each node: 1) the node's
+path relative to \fInode\fR, 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 \fBrestore\fR operation.
+.sp
+The valid \fIswitches\fR are listed below.
+.RS
+.TP
+\fB\-channel \fIchan\fR
+Obtain data from from the given channel \fIchan\fR.
+The channel is not closed afterwards.
+.TP
+\fB\-file \fIfileName\fR
+Obtain data from from the file.
+\fIfileName\fR. This options is unsupported in a safe interp.
+.TP
+\fB\-keys \fIlist\fR
+A list of patterns of matching keys to be dumped.
+.TP
+\fB\-skipkeys \fIlist\fR
+A list of patterns of matching keys not to be dumped.
+.TP
+\fB\-tag \fIpattern\fR
+A pattern match for tags to include in a node dump.
+.TP
+\fB\-skiptag \fIpattern\fR
+A pattern match for tags to not include in a node dump.
+.TP
+\fB\-notags\fR
+Do not restore any tags
+.TP
+\fB\-nopath\fR
+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.
+.RE
+.TP
+\fItreeName\fR \fBexists\fR \fInode\fR ?\fIkey\fR?
+Indicates if \fInode\fR exists in the tree. If a \fIkey\fR argument
+is present then the command also indicates if the named data field
+exists.
+.TP
+\fItreeName\fR \fBfind\fR ?\fIswitches\fR?
+Finds for all nodes matching the criteria given by \fIswitches\fR
+for the subtree designated by \fInode\fR. A list of the selected
+nodes is returned. By default all nodes match, but you can set
+switches to narrow the match.
+.sp
+The \fB\-exact\fR, \fB\-glob\fR,
+and \fB\-regexp\fR switches indicate what kind of pattern matching
+to perform for \fB-name\fR. By default the pattern will be compared
+with the node label. If the \fB\-key\fR switch is
+used, it designates the data field to be matched.
+.sp
+The order in
+which the nodes are traversed is controlled by the \fB\-order\fR switch.
+The possible orderings are \fBpreorder\fR, \fBpostorder\fR, \fBinorder\fR,
+and \fBbreadthfirst\fR. The default is \fBpreorder\fR.
+.sp
+The valid switches are listed
+below:
+.RS
+.TP 1i
+\fB\-addtag\fR \fIstring\fR
+Add the tag \fIstring\fR to each selected node.
+The tag will be created even if no nodes are tagged.
+.TP 1i
+\fB\-column\fR \fIkey\fR
+Use value with field given by \fIkey\fR.
+Like the \fBtreeview find -column\fR option,
+this key may contain an array referrence.
+.TP 1i
+\fB\-cmdargs\fR \fIcolumns\fR
+Specify columns whose values are to be appended to \fB\-command\fR.
+.TP 1i
+\fB\-command\fR \fIcommand\fR
+Invoke \fIcommand\fR for each matching node. Before \fIcommand\fR is
+invoked, the id of the node is appended. You can control
+processing by the return value of \fIcommand\fR. If \fIcommand\fR
+generates an error, processing stops and the \fBfind\fR operation
+returns an error. But if \fIcommand\fR returns \fBbreak\fR, then
+processing stops, no error is generated. If \fIcommand\fR returns
+\fBcontinue\fR, then processing
+stops on that subtree and continues on the next.
+If \fIcommand\fR returns \fBreturn\fR, then the returned integer
+is used to indicate 1 for match or 0 for mismatch.
+.TP 1i
+\fB\-count\fR
+Just return the number of matches.
+.TP 1i
+\fB\-depth\fR \fInumber\fR
+Include only nodes with level equal to \fInumber\fR.
+.TP 1i
+\fB\-exact\fR
+Matches each node exactly.
+.TP 1i
+\fB\-exec\fR \fIscript\fR
+Specifies a Tcl script to be evaluated for each matching node.
+If \fB-var\fR 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 \fB-var\fR or \fB-command\fR
+.sp
+The result of each eval gets appended to the return list, unless
+the script issues a CONTINUE, in which case that node is skipped.
+.sp
+The available percent substitutions on \fIstring\fR are:
+.RS
+.TP 5
+\fB%#\fR
+The id of the node.
+.TP 5
+\fB%W\fR
+The pathname of the tree.
+.TP 5
+\fB%p\fR
+The label of the node.
+.TP 5
+\fB%P\fR
+The full pathname of the node.
+.TP 5
+\fB%R\fR
+The -> delimited path from root, eg. "root->able->baker->charlie"
+.TP 5
+\fB%r\fR
+The -> delimited path from 0, eg. "0->able->baker->charlie"
+.TP 5
+\fB%T\fR
+The dot delimited tag path eg. ".able.baker.charlie"
+.TP 5
+\fB%V\fR
+The value if using \fB-key\fR or the label otherwise.
+.TP 5
+\fB%D\fR
+The data for the node, ie. like that returned from \fBget\fR.
+.TP 5
+\fB%%\fR
+Translates to a single percent.
+.RE
+.TP 1i
+\fB\-glob\fR
+Test each node using global pattern
+matching. Matching is done in a fashion similar to that used by the
+\fBstring match\fR.
+.TP 1i
+\fB\-invert\fR
+Invert the pattern matching of \fB-name\fR.
+.TP 1i
+\fB\-isarray\fR
+Only test nodes where the specified \fB-key\fR value
+is an array. Can not be used with \fB-name\fR.
+The \fB-invert\fR 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.
+.TP 1i
+\fB\-isempty\fR
+Only match nodes where the specified \fB-column\fR key value
+was unset.
+.TP 1i
+\fB\-isfixed\fR
+Only test nodes that have used \fBfixed 1\fR.
+.TP 1i
+\fB\-isleaf\fR
+Only test nodes with no children.
+.TP 1i
+\fB\-isnotfixed\fR
+Only test nodes that have not used \fBfixed 1\fR.
+.TP 1i
+\fB\-istree\fR
+Only test nodes with children.
+.TP 1i
+\fB\-keycount\fR \fInum\fR
+Only test if number of keys is equal to \fInum\fR.
+.TP 1i
+\fB\-key\fR \fIkey\fR
+.TP 1i
+\fB\-keyglob\fR \fIkey\fR
+.TP 1i
+\fB\-keyregexp\fR \fIkey\fR
+.TP 1i
+\fB\-keyexact\fR \fIkey\fR
+Compare the values of the data field keyed by \fIkey\fR instead of
+the node's label. If no \fB\-name\fR pattern is used
+then any node with this data key will match.
+The key names may also be patterns using \fB-keyglob\fR, etc.
+.TP 1i
+\fB\-limit\fR \fInumber\fR
+Stop processing after \fInumber\fR (a positive integer) matches.
+.TP 1i
+\fB\-maxdepth\fR \fInumber\fR
+Include only nodes at level \fInumber\fR or less.
+.TP 1i
+\fB\-mindepth\fR \fInumber\fR
+Include only nodes at level \fInumber\fR or greater.
+.TP 1i
+\fB\-name\fR \fIstring\fR
+The name to use for pattern matching.
+.TP 1i
+\fB\-nocase\fR
+Ignore case when matching patterns.
+.TP 1i
+\fB\-nodes \fItagnode\fR
+Search only in \fItagnode\fR, which is either a tag
+or a list of nodes ids. This makes possible nested searches.
+Note this option is incompatible with
+\fB-top\fR and \fB-notop\fR.
+.TP 1i
+\fB\-notop\fR
+Exclude the \fB-top\fR or starting node.
+.TP 1i
+\fB\-order\fR \fIstring\fR
+Traverse the tree and process nodes according to \fIstring\fR. \fIString\fR
+can be one of the following:
+.RS
+.TP 1i
+\fBbreadthfirst\fR
+Process the node and the subtrees at each sucessive level. Each node
+on a level is processed before going to the next level.
+.TP 1i
+\fBinorder\fR
+Recursively process the nodes of the first subtree, the node itself,
+and any the remaining subtrees.
+.TP 1i
+\fBpostorder\fR
+Recursively process all subtrees before the node.
+.TP 1i
+\fBpreorder\fR
+Recursively process the node first, then any subtrees (default).
+.RE
+.TP 1i
+\fB\-usepath\fR
+Use the node's full path when doing the comparison.
+The default is to compare only the node label.
+.TP 1i
+\fB\-regexp\fR
+Test each node using regular expression pattern matching.
+.TP 1i
+\fB\-reldepth\fR
+Change the meaning of \fB\-depth\fR, \fB\-mindepth\fR and \fB\-maxdepth\fR
+to be relative to the \fB\-top\fR node.
+.TP 1i
+\fB\-return \fIkey\fR
+Return the value of the given \fIkey\fR, or the empty string if none.
+If the given \fIkey\fR is the empty string, the node label will be returned.
+If no value was found and the given \fIkey\fR starts with a percent
+returns the sustitution as per \fB-exec\fR. Note that a percent
+substitution longer than 2 chars will append values as list elements.
+.TP 1i
+\fB\-strict\fR
+Generate an error if a given key value is unset when using \fB-return\fR.
+.TP 1i
+\fB\-top \fInode\fR
+Search is only at \fInode\fR and it's descendants.
+The default is the root node.
+.TP 1i
+\fB\-var \fIvariable\fR
+A variable to set with the node id before each iteration of the \fB-exec\fR
+script.
+.TP 1i
+\fB\-withouttag\fR \fIstring\fR
+Only test nodes that don't have the tag \fIstring\fR.
+.TP 1i
+\fB\-withtag\fR \fIstring\fR
+Only test nodes that have the tag \fIstring\fR.
+.RE
+.TP
+\fItreeName\fR \fBfindchild\fR \fInode\fR \fIlabel\fR
+Searches for a child node \fIlabel\fR in \fInode\fR. The id of the
+child node is returned if found. Otherwise \fB-1\fR is returned.
+This is the same as using \fBindex \fInode->label\fR.
+.TP
+\fItreeName\fR \fBfirstchild\fR \fInode\fR
+Returns the id of the first child in the \fInode\fR's list
+of subtrees. If \fInode\fR is a leaf (has no children),
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBfixed\fR \fInode\fR ?\fIisfixed\fR?
+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 \fInode\fR is given as an empty string, operates on the tree flag.
+Note that copied and restored nodes do not preserve the fixed state.
+.TP
+\fItreeName\fR \fBforeach\fR \fIvar tagnode script\fR
+Provides a \fBforeach\fR loop for tree. For
+each node in \fItagnode\fR the node-id is assigned to \fIvar\fR and then
+\fIscript\fR is evaluated. The \fItagnode\fR is either a tag or a list of
+nodes as described in the section
+.SB NODE IDS AND TAGS
+above.
+.TP
+\fItreeName\fR \fBget\fR \fInode\fR ?\fIkey\fR? ?\fIdefaultValue\fR?
+Returns a list of key-value pairs of data for \fInode\fR. If \fIkey\fR
+is present, then only the value for that particular data field is
+returned. It's normally an error if \fInode\fR does not contain the
+data field \fIkey\fR. But if you provide a \fIdefaultValue\fR
+argument, this value is returned instead (\fInode\fR will still not
+contain \fIkey\fR). This feature can be used to access a data field of
+\fInode\fR without first testing if it exists. This operation may
+trigger \fBread\fR data traces.
+.TP
+\fItreeName\fR \fBincr\fR \fInode key\fR ?\fIamount\fR?
+Increment value by 1 or given \fIamount\fR and return the value.
+The incr operation normally tries to use integers,
+but uses doubles when one of
+value or \fIamount\fR is a double.
+.TP
+\fItreeName\fR \fBincri\fR \fItagnode key\fR ?\fIamount\fR?
+The same as \fBincr\fR but accepts a multi-node tag and an
+undefined key will be initialized to 0. Returns the number of nodes
+updated.
+.TP
+\fItreeName\fR \fBindex\fR \fInode\fR
+Returns the id of \fInode\fR. In addition
+to standard node id form,
+\fInode\fR can also be a path (a list of labels from the root) as returned
+by the \fBpath\fR command.
+If \fInode\fR is invalid, then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBinsert\fR \fIparent\fR ?\fIswitches\fR?
+Inserts a new node into parent node \fIparent\fR.
+The id of the new node is returned.
+The following switches
+are available:
+.RS
+.TP 1i
+\fB\-after\fR \fIchild\fR
+Position \fInode\fR after \fIchild\fR. The node \fIchild\fR must be a
+child of \fIparent\fR.
+.TP 1i
+\fB\-before\fR \fIchild\fR
+Position \fInode\fR before \fIchild\fR. The node \fIchild\fR must be a
+child of \fIparent\fR.
+.TP 1i
+\fB\-data\fR \fIdataList\fR
+Sets the value for each data field in \fIdataList\fR for the
+new node. \fIDataList\fR is a list of key-value pairs.
+May not be used in conjuction with \fB-names\fR or \fB-values\fR.
+.TP 1i
+\fB\-fixed\fR \fIbool\fR
+If \fIbool\fR is 1, set \fBfixed\fR field mode after initializing
+the key/value pairs from \fB-data\fR.
+This disallows creation of new key fields
+after the node is created.
+If not given, the tree default for fixed is used.
+.TP 1i
+\fB\-label\fR \fIstring\fR
+Designates the labels of the node as \fIstring\fR. By default, nodes
+are labeled as \fB0\fR, \fB1\fR, etc.
+.TP 1i
+\fB\-names\fR \fInameList\fR
+The names for the data fields. This must have the same length as
+\fB-values\fR, and may not be used in conjuction with \fB-data\fR.
+.TP 1i
+\fB\-node\fR \fIid\fR
+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.
+.TP 1i
+\fB\-pos\fR \fInumber\fR
+Inserts the node into \fIparent\fR's list of children at
+position \fInumber\fR. The default is to append.
+.TP 1i
+\fB\-pretags\fR \fItagList\fR
+Adds each tag in \fItagList\fR to the new node, before
+data is added. Unlike \fB-tags\fR, traces on these tags
+will fire on key data during the insert.
+.TP 1i
+\fB\-tags\fR \fItagList\fR
+Adds each tag in \fItagList\fR to the new node. \fITagList\fR is a list
+of tags, so be careful if a tag has embedded space.
+.TP 1i
+\fB\-values\fR \fIvalueList\fR
+The values for the data fields. This must have the same length as
+\fB-names\fR, and may not be used in conjuction with \fB-data\fR.
+.RE
+.TP
+\fItreeName\fR \fBis\fR \fIproperty\fR \fIargs\fR
+Indicates the property of a node. Both \fIproperty\fR and \fIargs\fR
+determine the property being tested. Returns \fB1\fR if true and
+\fB0\fR otherwise. The following \fIproperty\fR and \fIargs\fR
+are valid:
+.RS
+.TP 1i
+\fBancestor\fR \fInode1\fR \fInode2\fR
+Indicates if \fInode1\fR is an ancestor of \fInode2\fR.
+.TP 1i
+\fBbefore\fR \fInode1\fR \fInode2\fR
+Indicates if \fInode1\fR is before \fInode2\fR in depth first traversal.
+.TP 1i
+\fBleaf\fR \fInode\fR
+Indicates if \fInode\fR is a leaf (it has no subtrees).
+.TP 1i
+\fBroot\fR \fInode\fR
+Indicates if \fInode\fR is the designated root. This can be changed
+by the \fBroot\fR operation.
+.RE
+.TP
+\fItreeName\fR \fBismodified\fR ?\fInodeOrTag\fR? ?\fIisflag\fR?
+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 ?\fInodeOrTag\fR? is the tag \fBall\fR,
+the state for the tree is also set.
+.sp
+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.
+.TP
+\fItreeName\fR \fBisset\fR \fInode\fR \fIkey\fR
+Return 1 if key is set in node.
+.TP
+\fItreeName\fR \fBkeys\fR \fInode\fR ?\fItagnode ...\fR?
+Return list of unique keys for all of the given nodes in \fItagnode\fR.
+Keys are in no particular order.
+Accepts nodes and tags or all. See also \fBnames\fR.
+.TP
+\fItreeName\fR \fBlabel\fR \fInode\fR ?\fInewLabel\fR?
+Returns the label of the node designated by \fInode\fR. If \fInewLabel\fR
+is present, the node is relabeled using it as the new label.
+.TP
+\fItreeName\fR \fBlappend\fR \fInode key\fR \fIvalue\fR ?\fIvalue ...\fR?
+Append one or more list values to node/key value.
+.TP
+\fItreeName\fR \fBlappendi\fR \fItagnode key\fR \fIvalue\fR ?\fIvalue ...\fR?
+The same as \fBlappend\fR but accepts a multi-node tag and an
+undefined key will be initialized to {}. Returns the number of nodes
+updated.
+.TP
+\fItreeName\fR \fBlastchild\fR \fInode\fR
+Returns the id of the last child in the \fInode\fR's list
+of subtrees. If \fInode\fR is a leaf (has no children),
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBmodify\fR \fItagnode\fR \fIkey value\fR ?\fIkey value\fR...?
+Update one or more fields in one or more nodes in \fItagnode\fR.
+As with \fBset\fR, \fInode\fR
+can be a tag referring to multiple nodes.
+This is identical to \fBset\fR, 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 \fBupdate\fR.
+.TP
+\fItreeName\fR \fBmove\fR \fInode\fR \fInewParent\fR ?\fIswitches\fR?
+Moves \fInode\fR into \fInewParent\fR. \fINode\fR is appended to the
+list children of \fInewParent\fR. \fINode\fR can not be an ancestor
+of \fInewParent\fR. The valid flags for \fIswitches\fR are described below.
+.RS
+.TP 1i
+\fB\-after\fR \fIchild\fR
+Position \fInode\fR after \fIchild\fR. The node \fIchild\fR must be a
+child of \fInewParent\fR.
+.TP 1i
+\fB\-before\fR \fIchild\fR
+Position \fInode\fR before \fIchild\fR. The node \fIchild\fR must be a
+child of \fInewParent\fR.
+.TP 1i
+\fB\-pos\fR \fInumber\fR
+Inserts \fInode\fR into \fIparent\fR's list of children at
+position \fInumber\fR. The default is -1 to append the node.
+.RE
+.TP
+\fItreeName\fR \fBnames\fR \fInode\fR ?\fIkey\fR? ?\fIpattern\fR?
+Return key names for \fInode\fR, 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 \fBtype\fR command can be used to query the type.
+See also \fBvalues\fR.
+.TP
+\fItreeName\fR \fBnext\fR \fInode\fR
+Returns the next node from \fInode\fR in a preorder traversal.
+If \fInode\fR is the last node in the tree,
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBnextsibling\fR \fInode\fR
+Returns the node representing the next subtree from \fInode\fR
+in its parent's list of children. If \fInode\fR is the last child,
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBnodeseq\fR ?\fIstart\fR?
+Get or set the \fIstart\fR sequence number for subsequent
+node insertions not using \fB-node\fR. The default is 0.
+.TP
+\fItreeName\fR \fBnotify\fR \fIargs\fR
+Manages notification events that indicate that the tree structure has
+been changed.
+See the
+.SB "NOTIFY OPERATIONS"
+section below.
+.TP
+\fItreeName\fR \fBoldvalue\fR ?\fInewvalue\fR?
+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.
+.sp
+If \fInewvalue\fR is provided, the current value of oldvalue is
+discarded and replaced. This is useful really only for releasing large objects.
+.TP
+\fItreeName\fR \fBparent\fR \fInode\fR
+Returns the parent node of \fInode\fR. If \fInode\fR is the root
+of the tree,
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBpath\fR \fInode\fR ?\fIdelim\fR? ?\fIprefix\fR?
+Returns the full path (from root) of \fInode\fR using the node labels.
+If \fIdelim\fR is not specified, the result is a list.
+Otherwise, the result is a string starting with \fIprefix\fR and
+each element of the path separated by \fIdelim\fR.
+This latter form is useful for building tags like: \fB.able.baker\fR
+.TP
+\fItreeName\fR \fBposition\fR ?\fB-sort\fR? ?\fB-format\fR \fIftype\fR? \fInode\fR ?\fInode\fR ...?
+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 \fIftype\fR is one of:
+\fBposition parent-at-position id+position id+parent-at-position\fR.
+.TP
+\fItreeName\fR \fBprevious\fR \fInode\fR
+Returns the previous node from \fInode\fR in a preorder traversal.
+If \fInode\fR is the root of the tree,
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBprevsibling\fR \fInode\fR
+Returns the node representing the previous subtree from \fInode\fR
+in its parent's list of children. If \fInode\fR is the first child,
+then \fB-1\fR is returned.
+.TP
+\fItreeName\fR \fBrestore\fR \fInode\fR \fIswitches\fR
+Performs the inverse function of the \fBdump\fR operation, restoring
+nodes to the tree. The format of the input data is exactly what is
+returned by the \fBdump\fR 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 \fInode\fR. Nodes can be listed in any order. If a node's
+path describes ancestor nodes that do not already exist, they are
+automatically created.
+.sp
+The valid \fIswitches\fR are listed below. Exactly one
+of \fB-channel\fR, \fB-file\fR or \fB-data\fR must be specified.
+.RS
+.TP
+\fB\-addtags\fR
+List of tags to add to each node restored node.
+Each tag will be created only if a node loaded.
+.TP
+\fB\-channel \fIchan\fR
+Obtain data from from the given channel \fIchan\fR.
+The channel is not closed afterwards.
+.TP
+\fB\-data \fIstring\fR
+Data input is from the given \fIstring\fR.
+.TP
+\fB\-file \fIfileName\fR
+Obtain data from from the file.
+\fIfileName\fR. This options is unsupported in a safe interp.
+.TP
+\fB\-keys \fIlist\fR
+A list of patterns of matching keys to be restored.
+.TP
+\fB\-skipkeys \fIlist\fR
+A list of patterns of matching keys not to be restored.
+.TP
+\fB\-tag \fIpattern\fR
+A pattern match for tags to include in a node restore.
+.TP
+\fB\-skiptag \fIpattern\fR
+A pattern match for tags to not include in a node restore.
+.TP
+\fB\-notags\fR
+Do not restore any tags
+.TP
+\fB\-overwrite\fR
+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.
+.RE
+.TP
+\fItreeName\fR \fBroot\fR ?\fInode\fR?
+Returns the id of the root node. Normally this is node \fB0\fR. If
+a \fInode\fR 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 \fBnext\fR, \fBpath\fR,
+\fBprevious\fR, etc.
+.TP
+\fItreeName\fR \fBset\fR \fItagnode\fR \fIkey value\fR ?\fIkey value\fR...?
+Sets one or more data fields in \fInode\fR. \fItagode\fR may
+be a tag that represents several nodes and a count of the number
+of nodes updated is returned.
+\fIKey\fR is the
+name of the data field to be set, or an array-like reference such as \fBfield(subkey)\fR.
+See the
+.SB "DICT-ARRAYS"
+section below. \fIValue\fR is the respective keys value.
+The \fIKey\fR will be created if it does not exists (see \fBmodify\fR).
+.sp
+The set operation triggers \fBwrite\fR and \fBcreate\fR data traces.
+.TP
+\fItreeName\fR \fBsize\fR \fInode\fR
+Returns the number of nodes in the subtree. This includes the node
+and all its descendants. The size of a leaf node is 1.
+.TP
+\fItreeName\fR \fBsort\fR \fInode\fR ?\fIswitches\fR?
+Return nodes in sorted order.
+.RS
+.TP 1i
+\fB\-ascii\fR
+Compare strings using the ASCII collation order.
+.TP 1i
+\fB\-command\fR \fIstring\fR
+Use command \fIstring\fR as a comparison command. To compare two
+elements, evaluate a Tcl script consisting of command with the five
+elements appended as additional arguments:
+\fIthe tree, node1, node1, label1, label2\fR.
+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.
+.TP 1i
+\fB\-decreasing\fR
+Sort in decreasing order (largest items come first).
+.TP 1i
+\fB\-dictionary\fR
+Compare strings using a dictionary-style comparison. This is the same
+as \fB\-ascii\fR 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 \fB\-dictionary\fR mode, bigBoy sorts between
+bigbang and bigboy, and x10y sorts between x9y and x11y.
+.TP 1i
+\fB\-integer\fR
+Compare the nodes as integers.
+.TP 1i
+\fB\-key\fR \fIstring\fR
+Sort based upon the node's data field keyed by \fIstring\fR. Normally
+nodes are sorted according to their label.
+label.
+.TP 1i
+\fB\-real\fR
+Compare the nodes as real numbers.
+.TP 1i
+\fB\-recurse\fR
+Recursively sort the entire subtree rooted at \fInode\fR.
+.TP 1i
+\fB\-reorder\fR
+Recursively sort subtrees for each node. \fBWarning\fR. Unlike
+the normal flat sort, where a list of nodes is returned, this will
+reorder the tree.
+.TP 1i
+\fB\-usepath\fR
+Compare the full path of each node. The default is to compare only the node
+label.
+.RE
+.TP
+\fItreeName\fR \fBsqlload\fR ?\fIswitches\fR? \fIdbhfile\fR \fIsqlstmt\fR
+Load tree with the results of evaling the SQL in \fIsqlstmt\fR using
+\fIdbhfile\fR.
+The evaluated SQL creates one tree-node per row result.
+The returned value is the number of rows loaded.
+\fIDbhfile\fR is either an \fBsqlite3\fR database handle,
+or an \fBsqlite3\fR file.
+.sp
+The \fBsqlload\fR command can populate a tree with 10k nodes
+about 7 times faster than \fBsqlite3 eval\fR.
+It also preserves NULL values
+and object types (eg. int or double) used internally
+by sqlite. This eliminates later reconversion within tree.
+See the
+.SB "SQLLOAD EXAMPLE"
+below.
+.sp
+The following switches are available:
+.RS
+.TP 1i
+\fB\-addtags \fItaglist\fR
+The tags in \fItaglist\fR to add to each inserted node.
+Each tag will be created only if a node loaded.
+.TP 1i
+\fB\-fixed\fR
+Set the \fBfixed\fR flag to disallow new keys after creation.
+.TP 1i
+\fB\-key \fIname\fR
+Store the entire result in the key \fIname\fR 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).
+.TP 1i
+\fB\-labelcol \fIcolumn\fR
+The value of \fIcolumn\fR is used as the label.
+By default the label is the node id.
+.TP 1i
+\fB\-maprowid \fInum\fR
+This option maps the node id to the rowid plus the constant \fInum\fR.
+The key for \fBrowid\fR will also not be created.
+This is applicable only if \fBrowid\fR is returned in the result-set
+of \fIsqlstmt\fR.
+If \fBrowid\fR 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 \fInum\fR must be >= 1 since sqlite
+rowids start from 0, but the root node of the tree uses the node-id 0.
+.TP 1i
+\fB\-max \fInum\fR
+The maximum number of rows to return. The default is 100,000.
+Note that SQL queries on large tables should probably always use LIMIT.
+.TP 1i
+\fB\-nullvalue \fIstring\fR
+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.
+.TP 1i
+\fB\-parent \fIstring\fR
+The node where results are
+inserted as child nodes. The default is the tree root.
+.TP 1i
+\fB\-pathcol \fIcolumn\fR
+Name of column containing the full path where node is to be created.
+This works like \fB\-treecols\fR, but uses a singl columns.
+.TP 1i
+\fB\-skipcols \fIcolumns\fR
+The given \fIcolumns\fR are not to be added as keys. This is useful mostly
+in conjuction with \fB-tagcol\fR, \fB-labelcol\fR, \fB-pathcol\fR.
+.TP 1i
+\fB\-pos \fInum\fR
+Where to insert into parents list of children.
+Default is -1, meaning to append.
+.TP 1i
+\fB\-tagcol \fIcolumn\fR
+The value of \fIcolumn\fR is added as a tag.
+.TP 1i
+\fB\-treecols \fIcolumns\fR
+Columns whose values concatenated
+give the path of where node is to be created.
+This works like \fB\-pathcol\fR, but uses multiple columns.
+.RE
+.TP
+\fItreeName\fR \fBsum\fR ?\fIswitches\fR? \fItagnode key\fR ?\fIkey ...\fR?
+Add values in key fields for all \fItagnode\fR and return the sum.
+Values that are not doubles (or integer) are ignored.
+.RS
+.TP 1i
+\fB\-diff\fI value\fR
+Double value difference to ignore and not do update for \fB-runtotal\fR.
+This is unused when using \fB\-int\fR.
+.TP 1i
+\fB\-force\fR
+Force update \fB-runtotal\fR even if value was unchanged.
+Normally, a check is made to avoid updating unchanged values.
+.TP 1i
+\fB\-int\fR
+Use and accept only integer values.
+.TP 1i
+\fB\-runtotal \fIkey\fR
+Place running total in the given key field (if changed).
+.TP 1i
+\fB\-start \fInum\fR
+The start value for the sum: default is 0.
+.RE
+.TP
+\fItreeName\fR \fBsupdate\fR \fInode\fR \fIkey value\fR ?\fIkey value\fR...?
+Like \fBupdate\fR, but uses a string comparison
+to avoid writes if the value will not be changed. This is useful primarily
+for avoiding unnecessary write traces.
+.TP
+\fItreeName\fR \fBtag\fR \fIargs\fR
+Manages tags for the tree object.
+See the
+.SB "TAG OPERATIONS"
+section below.
+.TP
+\fItreeName\fR \fBtrace\fR \fIargs\fR
+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
+.SB "TRACE OPERATIONS"
+section below.
+.TP
+\fItreeName\fR \fBtype\fR \fInode\fR \fIkey\fR
+Return type of value. This is the introspected type from the Tcl_Obj
+value passed to set.
+.TP
+\fItreeName\fR \fBupdate\fR \fInode\fR \fIkey value\fR ?\fIkey value\fR...?
+Like \fBmodify\fR, except an error is generated if a tag
+is used that applies to more than one node.
+.TP
+\fItreeName\fR \fBunset\fR \fInode\fR \fIkey\fR...
+Removes one or more data fields from \fInode\fR. \fINode\fR may
+be a tag that represents several nodes. \fIKey\fR is the
+name of the data field to be removed. It's not an error is
+\fInode\fR does not contain \fIkey\fR.
+A count of the number of nodes unset is returned.
+This operation may trigger \fBunset\fR data traces.
+.TP
+\fItreeName\fR \fBvalues\fR \fInode\fR ?\fIkey\fR? ?\fIwithnames\fR?
+Return values for \fInode\fR.
+The values are returned in the same order as the keys
+returned from \fBnames\fR.
+.sp
+If a \fIkey\fR is given,
+array values get returned for the \fIkey\fR value.
+If \fIwithname\fR is \fBTrue\fR, then key
+names are also returned with the values. This differs from \fBget\fR
+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.
+.TP
+\fItreeName\fR \fBvecdump\fR \fIvector\fR \fIkey\fR ?\fItagnode\fR?
+Dump key field to a vector. With no \fItagnode\fR, dumps every node
+to the 1-1 corresponding vector index. With \fItag\fR dumps
+nodes to consequetive vector elements.
+.TP
+\fItreeName\fR \fBvecload\fR \fIvector\fR \fIkey\fR ?\fItagnode\fR?
+Loads key field from a vector. With no \fItagnode\fR, loads every node
+from the 1-1 corresponding vector index. With \fItag\fR loads
+nodes from consequetive vector elements.
+.TP
+\fItreeName\fR \fBwith\fR \fIvariable\fR ?\fIswitch\fR? \fItagnode script\fR
+For each node in \fItagnode\fR,
+evaluate the \fIscript\fR after assigning key values to
+elements of the array \fIvariable\fR.
+The \fB-keys\fR limits which keys may be assigned.
+If \fIscript\fR completes normally,
+and any of the key values change in the \fIvariable\fR, then the
+updates are reflected back into the key values
+(unless \fB-noupdate\fR is used).
+Unsetting a variable key
+will cause that change to be ignored. New elements added to the
+array variable are ignored.
+.sp
+Doing a \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR inside
+\fIscript\fR will still cause updates to copy back, but
+processing will stop and (unless \fB-break\fR is used)
+the return code will become the return code to the caller.
+This means that a \fBbreak\fR, \fBcontinue\fR, and
+\fBreturn\fR will propagate up through
+multiple nested \fBwith\fR statements to the
+to an enclosing \fBforeach\fR, \fBwhile\fR, etc.
+But \fB-break\fR can be used to change this, making \fBwith\fR behave more
+like a \fBforeach\fR loop.
+.sp
+If \fB-keys\fR is not used, the list of key names will be
+stored in \fIvariable(*)\fR and the node id
+stored in \fIvariable(#)\fR (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 \fB-unset\fR is used, the array is unset at the start of each
+iteration, and \fB-init\fR can be used to specify a default value.
+Also, long running queries can speed up by initializing variables
+prior to the call to \fBwith\fR.
+.sp
+If the \fIvariable\fR 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.
+.sp
+If \fB-array\fR is used, \fBwith\fR operates on the keys of an tree array/dict
+instead of the keys of the node.
+.sp
+Upon normal completion, the number of times \fIscript\fR
+was evaluated is returned.
+.sp
+The valid switches are listed below:
+.RS
+.TP 1i
+\fB-array\fR \fIkey\fR
+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 \fB-keys\fR and \fB-glob\fR 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.
+.TP 1i
+\fB-break\fR
+Treat \fBbreak\fR and \fBcontinue\fR like \fBforeach\fR does
+rather than just passing them up to the enclosing script body.
+.TP 1i
+\fB-init\fI value\fR
+Variables specified by \fB-keys\fR are to be initialized to \fIvalue\fR
+for each node where key is missing.
+.TP 1i
+\fB-keys\fR \fIkeylist\fR
+Copy only the named keys and does not set (*).
+.TP 1i
+\fB-glob\fR \fIpattern\fR
+Pattern to limit matching keys. Can not be used with \fB-keys\fR.
+.TP 1i
+\fB-noupdate\fR
+Ignore changes to array variables. This
+do not copy changed variables back into tree nodes.
+.TP 1i
+\fB-unset\fR
+Unset the array variable at the begin of each evaluation.
+.RE
+.RE
+.SH 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.
+.PP
+.CS
+ 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
+.CE
+.PP
+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 \fBarray\fR hash object.
+The following example shows the type in a comment after each operation.
+.PP
+.CS
+ 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
+.CE
+.PP
+One advantage of using a dict is that it preserves order.
+See \fBdictset\fR.
+.SH 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.
+.PP
+Most tree operations use tags. And several operations let you
+operate on multiple nodes at once. For example, you can use the
+\fBset\fR operation with the tag \fBall\fR to set a data field in
+for all nodes in the tree.
+.PP
+Tags are invoked by the \fBtag\fR operation. The
+general form is
+.DS
+\fItreeName\fR \fBtag\fR \fIoperation\fR ?\fIarg\fR?...
+.DE
+Both \fIoperation\fR and its arguments determine the exact behavior of
+the command. The operations available for tags are listed below.
+.TP
+\fItreeName\fR \fBtag add\fR \fIstring\fR ?\fInode\fR?...
+Adds the tag \fIstring\fR to zero or more nodes.
+If no nodes are given, just creates the tag.
+A count of the number of nodes tagged is returned.
+.TP
+\fItreeName\fR \fBtag delete\fR \fIstring\fR \fInode\fR...
+Remove the tag \fIstring\fR from one or more nodes.
+A count of the number of nodes visited is returned.
+Calling \fBtag delete\fR with a builtin tag is ignore.
+.TP
+\fItreeName\fR \fBtag dump\fR \fItagnode\fR ?\fIswitches\fR?
+Dump the nodes specified by the tag \fItagnode\fR.
+.sp
+The valid \fIswitches\fR are listed below.
+.RS
+.TP
+\fB\-keys \fIlist\fR
+A list of patterns of matching keys to be dumped.
+.TP
+\fB\-skipkeys \fIlist\fR
+A list of patterns of matching keys not to be dumped.
+.TP
+\fB\-tag \fIpattern\fR
+A pattern match for tags to include in a node dump.
+.TP
+\fB\-skiptag \fIpattern\fR
+A pattern match for tags to not include in a node dump.
+.TP
+\fB\-notags\fR
+Do not dump the tags.
+.TP
+\fB\-nopath\fR
+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.
+.RE
+.TP
+\fItreeName\fR \fBtag exists\fR \fIstring\fR ?\fIid\fR?
+If an \fIid\fR is given, return 1 (or 0) if node has (or hasn't) the tag.
+Otherwise, returns 1 if at least one nodes has tag \fIstring\fR.
+.TP
+\fItreeName\fR \fBtag forget\fR \fIstring\fR ?\fIstring\fR ...?
+Removes the tag definition for one or more of \fIstring\fR.
+It's not an error if the tag \fIstring\fR does not exist.
+.TP
+\fItreeName\fR \fBtag lookups\fR ?\fIpattern\fR?
+Dump a lookup table (dictionary)
+of nodes-to-tags, or tags-to-nodes if \fIpattern\fR
+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.
+\fBlookups\fR provides efficient bulk processing when dealing with
+large numbers of nodes and/or tags.
+.TP
+\fItreeName\fR \fBtag names\fR ?\fB-glob\fR? ?\fB-regexp\fR? ?\fB-nocase\fR? ?\fInode\fR? ?\fInode ...\fR?
+Returns a list of tags used by the tree. If no \fInode\fR argument
+is given, returns a list of all known tags. Otherwise, returns
+the union of the tags used by all given \fInode\fR numbers.
+Patterns can be used via \fB-glob\fR or \fB-regexp\fR.
+If \fB-nocase\fR is used, the pattern is expected to be all lower case.
+.TP
+\fItreeName\fR \fBtag nodes\fR \fIstring\fR ?\fIstring ...\fR?
+Returns a list of any nodes that have any of given \fIstring\fR tag. If no node
+is tagged with any of the \fIstring\fR, then an empty string is returned.
+.SH 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.
+.PP
+The tree's \fBget\fR, \fBset\fR, and \fBunset\fR operations can
+trigger various traces. The \fBget\fR operation can cause
+a \fIread\fR trace to fire. The \fBset\fR operation causes a \fIwrite\fR
+trace to fire. And if the data field is written for the first time, you
+will also get a \fIcreate\fR trace.
+The \fBunset\fR operation triggers \fIunset\fR traces.
+.PP
+Data traces are invoked by the \fBtrace\fR
+operation. The general form is
+.DS
+\fItreeName\fR \fBtrace\fR \fIoperation\fR ?\fIarg\fR?...
+.DE
+Both \fIoperation\fR and its arguments determine the exact behavior of
+the command. The operations available for traces are listed below.
+.TP
+\fItreeName\fR \fBtrace create\fR \fInode\fR \fIkey\fR \fIops\fR \fIcommand\fR ?-bgerror?
+Create a trace on data fields (or tags for tag traces)
+given by the pattern in \fIkey\fR. The \fInode\fR argument
+can be a nodeid, or a tag to refer to multiple nodes eg. \fIall\fR.
+The return value is an identifier that can
+be used with "\fBtrace info\fR" or "\fBtrace delete\fR".
+Traces are temporarily disabled while executing \fIcommand\fR within the trace.
+.sp
+\fICommand\fR is a command prefix, to which
+four arguments are appended before invocation:
+\fItreeName\fR, \fInodeid\fR, \fIkey\fR and, \fIops\fR.
+If an error occurs in \fIcommand\fR (and \fI-bgerror\fR was not used)
+the invoking operation will also abort.
+.sp
+\fIOps\fR indicates which operations are of
+interest. It consists of one or more of the following letters:
+.RS
+.TP
+\fBr\fR
+Invoke \fIcommand\fR whenever \fIkey\fR is read.
+.TP
+\fBw\fR
+Invoke \fIcommand\fR whenever \fIkey\fR is written.
+.TP
+\fBc\fR
+Invoke \fIcommand\fR whenever \fIkey\fR is created.
+.TP
+\fBu\fR
+Invoke \fIcommand\fR whenever \fIkey\fR is unset,
+typically with the \fBunset\fR command.
+to that.
+.TP
+\fBe\fR
+Invoke \fIcommand\fR whenever \fBexists\fR is used on an non-existant
+key. This can be used to populate node key data on demand.
+.TP
+\fBt\fR
+Invoke \fIcommand\fR whenever tag \fIkey\fR is added to a node.
+.TP
+\fBm\fR
+Invoke \fIcommand\fR when tag \fIkey\fR 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
+\fBget\fR or other commands not accepting non-unique tags.
+.TP
+\fBd\fR
+Invoke \fIcommand\fR whenever tag \fIkey\fR is \fIdeleted\fR from a node
+using either \fBtag delete\fR or \fBtag forget\fR.
+Node deletion will not trigger this trace.
+.sp
+.RE
+.TP
+\fItreeName\fR \fBtrace delete\fR \fItraceId\fR...
+Deletes one of more traces. \fITraceId\fR is
+the trace identifier returned by the \fBtrace create\fR operation.
+.TP
+\fItreeName\fR \fBtrace info\fR \fItraceId\fR
+Returns information about the trace \fItraceId\fR. \fITraceId\fR
+is a trace identifier previously returned by the \fBtrace create\fR operation.
+It's the same information specified for the \fBtrace create\fR 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 \fIops\fR) and, the command prefix.
+.TP
+\fItreeName\fR \fBtrace names\fR
+Returns a list of identifers for all the current traces.
+.SH NOTIFY OPERATIONS
+The purpose of \fBnotify\fR is to get control when structural operations
+occur on a tree. This is used internally by \fBtreeview\fR 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.
+.PP
+The general form of \fBnotify\fR is:
+.PP
+.RS
+\fItreeName\fR \fBnotify\fR \fIoperation\fR ?\fIarg\fR?...
+.RE
+.PP
+The available \fIoperation\fR are as follows:
+.TP
+\fItreeName\fR \fBnotify create\fR ?\fIswitches\fR? \fIcommand\fR ?\fIargs\fR?...
+Creates a notifier for the tree. A notify identifier in the form
+"\fBnotify0\fR", "\fBnotify1\fR", etc. is returned.
+.sp
+\fICommand\fR and \fIargs\fR are saved and invoked whenever the tree
+structure is changed (controlled by \fIswitches\fR). Two arguments are
+appended to \fIcommand\fR and \fIargs\fR 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 \fIcommand\fR
+the invoking operation returns an error (when not using \fI-whenidle\fR).
+One or more of the following switches are used to indicate the events
+that are of interest:
+.RS
+.TP 1i
+\fB\-bgerror\fR
+Generate a background error if an error occurs.
+.TP 1i
+\fB\-create\fR
+Invoke \fIcommand\fR whenever a new node is added.
+This is called after the creation. Returning an error will
+delete the node.
+.TP 1i
+\fB\-delete\fR
+Invoke \fIcommand\fR 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.
+.TP 1i
+\fB\-disabletrace\fR
+Disable traces from firing during a notify event.
+.TP 1i
+\fB\-get\fR
+Invoke \fIcommand\fR whenever a node with no keys is accessed (via \fBget\fR
+or \fBwith\fR).
+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).
+.TP 1i
+\fB\-insert\fR
+Invoke \fIcommand\fR when an \fBinsert\fR completes.
+This differs from \fB-create\fR in that the call occurs
+after the label, tags and data are added (but before
+\fB-fixed\fR gets set).
+This trace applies to the subcommands \fBcreate\fR, \fBcopy\fR,
+\fBrestore\fR, \fBsqlload\fR, and
+\fBinsert\fR (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.
+.TP 1i
+\fB\-move\fR
+Invoke \fIcommand\fR at the start of a node move.
+.TP 1i
+\fB\-movepost\fR
+Invoke \fIcommand\fR after a node has been moved.
+.TP 1i
+\fB\-sort\fR
+Invoke \fIcommand\fR whenever the tree has been sorted and reordered.
+.TP 1i
+\fB\-relabel\fR
+Invoke \fIcommand\fR at the start of a node relabel.
+.TP 1i
+\fB\-relabelpost\fR
+Invoke \fIcommand\fR after a node has been relabeled.
+.TP 1i
+\fB\-allevents\fR
+Invoke \fIcommand\fR whenever any of the above events occur.
+.TP 1i
+\fB\-whenidle\fR
+When an event occurs don't invoke \fIcommand\fR 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, \fIcommand\fR will still be
+invoked only once.
+.RE
+.TP
+\fItreeName\fR \fBnotify delete\fR \fInotifyId\fR
+Deletes one or more notifiers from the tree. \fINotifyId\fR is the
+notifier identifier returned by the \fBnotify create\fR operation.
+.TP
+\fItreeName\fR \fBnotify info\fR \fInotifyId\fR
+Returns information about the notify event \fInotifyId\fR. \fINotifyId\fR
+is a notify identifier previously returned by the \fBnotify create\fR operation.
+It's the same information specified for the \fBnotify create\fR operation.
+It consists of the notify id, a sublist of event flags (it's in the same
+form as \fIflags\fR) and, the command prefix.
+.TP
+\fItreeName\fR \fBnotify names\fR
+Returns a list of identifers for all the current notifiers.
+
+.SH TABLE EXAMPLE
+The following is a simple example.
+.sp
+.CS
+ 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]
+.CE
+.SH TREE EXAMPLE
+The following is a nested tree example with updates.
+.sp
+.CS
+ 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]
+.CE
+.SH SQLLOAD EXAMPLE
+Here is an example using \fBsqlload\fR on table \fIcust\fR from a
+database file, and displaying it in a treeview:
+.CS
+ 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]]
+.CE
+Although there is no corresponding \fBsqldump\fR command,
+scripting it is easy. Following
+is one approach.
+.CS
+ 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
+.CE
+.SH 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
+\fBblt::treeKeysLocal\fR to 1 before tree creation.
+To enable per-tree storage of keys, set
+\fBblt::treeKeysLocal\fR to 2 before tree creation.
+The above is unavailable in safe interps.
+.SH 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.
+.SH KEYWORDS
+tree, treeview, widget
OSDN Git Service
