Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
tree(n)			     BLT Built-In Commands		       tree(n)

______________________________________________________________________________

NAME
       tree -  Create and manage tree data objects.

SYNOPSIS
       tree create  ?-fixed? ?-dictset?	?-keyhash N? ?treeName?

       tree destroy treeName...

       tree names ?pattern?

       tree op subcmd ?subsubcmd ...? treeName ?arg arg	...?
_________________________________________________________________

DESCRIPTION
       The  tree command is used to create, destroy, and provide Tcl access to
       a tree object.  A tree object is	an ordered tree	of  nodes  where  each
       node  can  have data key-values,	tags and a label.  The treeview	widget
       uses a tree object.

INTRODUCTION
       Tree provides Tcl with a	rich API for managing complex data structures.
       Here is a simple	example.

	       set t [tree create]
	       set id [$t insert 0]
	       $t set $id X 2
	       set n [$t get $id X]

	       # Create	a node with label
	       $t insert 0 -label A
	       $t set 0->A    X	1
	       set n [$t get 0->A X]

       Labels provide convenient -> indexing relative a	starting node.

       Nodes may also be created with initial data values.

	       $t insert 0 -label A -data {X 1	 Y "a 1	b 2"}
	       $t incr	0->A X 3
	       $t set	0->A Y(a) 4

       Note  round  braces are used to access sub-values in a dict-array.  See
       the section DICT-ARRAYS below for details.

SYNTAX
       tree create ?-fixed? ?-dictset? ?-keyhash N? ?treeName?
	      Creates a	new tree object.  The name of the new tree is returned
	      and  a  Tcl  command  is	created.   If  no treeName argument is
	      present, then the	name of	the tree is automatically generated in
	      the  form	 "tree0",  "tree1",  etc relative to the current name-
	      space.  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 pre-
			serve 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  con-
			verts to a hash.  This affects the order of key	itera-
			tion (eg. for get/names/values).  A list will  iterate
			in the order in	which keys were	added, whereas the or-
			der 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 in-
	      ternal tree data object isn't destroyed until no one else	is us-
	      ing the tree.

       tree names ?pattern?
	      Returns the names	of all tree objects.  if a pattern argument is
	      given, then the only those trees whose name matches pattern will
	      be listed.

       tree op subcmd ?subsubcmd ...? treeName ?arg arg	...?
	      Provide  direct calls to sub-commands, without going through the
	      object command.  Aside from self documentating, it  allows  wize
	      to provide support checked tree calls.

NODE IDS AND TAGS
       Nodes  in  a  tree object may be	referenced by id or by tag.  Each node
       has a unique serial number or id	that is	assigned to  it	 at  creation.
       The id of an node never changes or is reused unless all nodes in	a tree
       are delete.

       A node may also have any	number of tags associated with it.  A  tag  is
       just a string of	characters, and	it may take any	form but can not start
       with an integer.	 For example, "x123" is	valid, but "123x" is not.  The
       same  tag may be	associated with	one or multiple	nodes (ranges or tagn-
       ode).  Ranges are commonly used to group	nodes in  various  interesting
       ways.

       Commands	 that take a tagnode can operate on ranges and will accept ei-
       ther 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	speci-
			fies the node that is currently	set as the  root  node
			for the	tree.

       When  specifying	 nodes in tree object commands,	if the specifier is an
       integer then it is assumed to refer to the single node  with  that  id.
       If  the specifier is not	an integer, then it is assumed to refer	to all
       of the nodes in the tree	that have a tag	matching the  specifier.   The
       symbol node is used below to indicate that an argument specifies	either
       an id or	a tag that selects a single node.  A tagnode is	either	a  tag
       that  selects  a	group of nodes,	or it's	a list of zero or more integer
       node numbers.  Many tree	commands only operate on a single  node	 at  a
       time;  if node is specified in a	way that names multiple	items, then an
       error "refers to	more than one node" is generated.

NODE MODIFIERS
       You can also specify node in relation to	another	node by	appending  one
       or more modifiers to the	node id	or tag after ->.  A modifier refers to
       a  node	in   relation	to   the   specified   node.	For   example,
       "root->firstchild" selects the first subtree of the root	node.

       The following modifiers are available:

	      firstchild
			Selects	the first child	of the node.

	      lastchild	Selects	the last child of the node.

	      nextnode	Selects	the next node in preorder to the node.

	      nextsibling
			Selects	the next sibling of the	node.

	      parentnode
			Selects	the parent of the node.

	      prevnode	Selects	the previous node in preorder to the node.

	      prevsibling
			Selects	the previous sibling of	the node.

	      maxnode	The maximum node number.

	      "label"

	      'label'

	      label	Selects	 the child node	whose label is label.  Enclos-
			ing 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 ex-
       ception to this is the index operation which returns -1,	 allowing  you
       to test if a modifier is	valid.

TREE OPERATIONS
       Once  you create	a tree object, you can use its Tcl command to query or
       modify it.  The general form is treeName	operation ?arg?...  Both oper-
       ation  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 up-
	      dated.

       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	(logi-
	      cal  or),	the node matches.  If the -key switch is used, it des-
	      ignates 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	match-
			ing.  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  re-
			turns break, then processing stops, no error is	gener-
			ated.  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 re-
			turns break, then processing stops, no error is	gener-
			ated.	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 de-
			fault 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 -la-
	      bels option is used, labels are returned instead of the nodes.

       treeName	copy srcNode ?destTree?	parentNode ?switches?
	      Copies srcNode into parentNode. Both nodes srcNode and  parentN-
	      ode  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 de-
	      fault both the source and	destination trees are  the  same.  The
	      valid switches are listed	below:

	      -label string
		     Label  destNode  as string.  By default, destNode has the
		     same label	as srcNode.

	      -overwrite
		     Overwrite nodes that already exist.  Normally  nodes  are
		     always  created,  even  if	there already exists a node by
		     the same name.  This switch indicates to add or overwrite
		     the node's	data fields.

	      -recurse
		     Recursively copy all the subtrees of srcNode as well.  In
		     this case,	srcNode	can't be an ancestor of	destNode as it
		     would result in a cyclic copy.

	      -reverse
		     Reverse the direction of the copy.

	      -tags  Copy  tag	inforation.   Normally	the  following node is
		     copied: its label and data	 fields.   This	 indicates  to
		     copy tags as well.

       treeName	create ?switches?
	      Cause  the creation of zero or more nodes.  Exactly one of -num,
	      -nodes or	-path is required.  This can create  all  nodes	 in  a
	      given -path or efficiently populate a tree with large numbers of
	      nodes.  The return values	is the id of the last created node (or
	      -path  element).	The valid flags	for switches are described be-
	      low.

	      -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  de-
			fault 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, cre-
			ating 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  re-
	      leased.

       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 ar-
	      ray  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 op-
	      tion, output goes	to the file fileName (this is unsupported in a
	      safe interp).  With the -channel option, data is output to chan-
	      nel chan.	 If neither option is given, the dump is  returned  as
	      data.

	      The  subtree  designated by node is traversed to obtain the fol-
	      lowing 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	 chan-
		     nel 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 re-
			ferrence.

	      -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  re-
			turns break, then processing stops, no error is	gener-
			ated.  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	match-
			ing node.  If -var was also specified,	that  variable
			is set with the	value of the node id before each eval-
			uation.	  Otherwise,  percent  sustitutions  are  per-
			formed:	 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.char-
			     lie"

			%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.	Match-
			ing  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 tra-
			versed 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 in-
			stead 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  re-
				  maining 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	match-
			ing.

	      -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 substi-
			tution	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 de-
			fault is the root node.

	      -var variable
			A variable to set with the node	id before each	itera-
			tion 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 sub-
	      trees.  If node is a leaf	(has no	 children),  then  -1  is  re-
	      turned.

       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 up-
	      dated.

       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 re-
	      turned by	the path command.  If node is invalid, then -1 is  re-
	      turned.

       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 cre-
			ation 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 de-
			fault, 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 conjuc-
			tion 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 po-
			sition 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 conjuc-
			tion with -data.

       treeName	is property args
	      Indicates	the property of	a node.	Both property and args	deter-
	      mine  the	property being tested.	Returns	1 if true and 0	other-
	      wise.  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 tra-
			versal.

	      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	 tagn-
	      ode.   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 unde-
	      fined 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  up-
	      date.

       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 posi-
			tion 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-AR-
	      RAYS).  If a pattern is given, the array	keys  are  limited  to
	      those matching the glob pattern.	An error is thrown if the con-
	      vert 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	inser-
	      tions not	using -node.  The default is 0.

       treeName	notify args
	      Manages  notification  events that indicate that the tree	struc-
	      ture has been changed.  See the NOTIFY OPERATIONS	section	below.

       treeName	oldvalue ?newvalue?
	      Return the value from before the last (untraced)	change	opera-
	      tion.   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 dur-
	      ing node traces do not affect oldvalue.

	      If  newvalue  is provided, the current value of oldvalue is dis-
	      carded 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	build-
	      ing 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  in-
	      formation	 for  each  node to be restored.  The information con-
	      sists 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 de-
	      scribes ancestor nodes that do not already exist,	they are auto-
	      matically	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 chan-
		     nel 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 re-
		     store.

	      -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	exist-
		     ing 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, pre-
	      vious, 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  up-
	      dated 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 com-
			pare 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 be-
			tween 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  re-
	      sult.  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 cre-
			ation.

	      -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 eff-
			icent  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 cre-
			ated.  This is applicable only if rowid	is returned in
			the result-set of sqlstmt.  If rowid is	not in the re-
			sult 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, -label-
			col, -pathcol.

	      -pos num	Where to insert	into parents list  of  children.   De-
			fault 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	-path-
			col, 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	avoid-
	      ing unnecessary write traces.

       treeName	tag args
	      Manages tags for the tree	object.	 See the TAG  OPERATIONS  sec-
	      tion 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 spe-
	      cific 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 or-
	      der 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 ar-
	      ray 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 ar-
	      ray is not cleaned up before or after each execution.   However,
	      if -unset	is used, the array is unset at the start of each iter-
	      ation, 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	 over-
	      written.

	      If  -array  is  used,  with  operates on the keys	of an tree ar-
	      ray/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 ar-
			ray-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  evalua-
			tion.

DICT-ARRAYS
       Round  braces  can be used to access sub-values of a key	value.	In ef-
       fect, 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 follow-
       ing example shows the type in a comment after each operation.

	       set t [tree create]
	       $t insert 0 -label A;
	       $t set	0->A  X	[dict create a 1 b 2 c 3];   # dict
	       array set q { x 1 y 2 };
	       $t set	0->A  Y	[array get q];		     # dict
	       $t set	0->A  Z	{m 0 n 1};		     # string
	       $t incr	0->A  Z(m);			     # array
	       dict size [$t get 0->A Z];		     # dict

       One advantage of	using a	dict is	that it	preserves order.  See dictset.

TAG OPERATIONS
       Tags are	a general means	of selecting and marking nodes in the tree.  A
       tag  is	just  a	 string	of characters, and it may take any form	except
       that of an integer.  The	same tag may be	associated with	many different
       nodes.

       Most  tree operations use tags.	And several operations let you operate
       on multiple nodes at once.  For example,	you can	use the	set  operation
       with the	tag all	to set a data field in for all nodes in	the tree.

       Tags  are  invoked  by the tag operation.  The general form is treeName
       tag operation ?arg?...  Both operation and its arguments	determine  the
       exact  behavior	of the command.	 The operations	available for tags are
       listed below.

       treeName	tag add	string ?node?...
	      Adds the tag string to zero or more  nodes.   If	no  nodes  are
	      given,  just  creates  the  tag.	A count	of the number of nodes
	      tagged is	returned.

       treeName	tag delete string node...
	      Remove the tag string from one or	more nodes.  A	count  of  the
	      number  of nodes visited is returned.  Calling tag delete	with a
	      builtin tag is ignore.

       treeName	tag dump tagnode ?switches?
	      Dump the nodes specified by the tag tagnode.

	      The valid	switches are listed below.

	      -keys list
		     A list of patterns	of matching keys to be dumped.

	      -skipkeys	list
		     A list of patterns	of matching keys not to	be dumped.

	      -tag pattern
		     A pattern match for tags to include in a node dump.

	      -skiptag pattern
		     A pattern match for tags to not include in	a node dump.

	      -notags
		     Do	not dump the tags.

	      -nopath
		     To	save space, do not dump	the full path for  each	 node.
		     Instead output periods for	all but	the last path element.
		     Full paths	are used only for partial restores.

       treeName	tag exists string ?id?
	      If an id is given, return	1 (or 0)  if node has (or hasn't)  the
	      tag.  Otherwise, returns 1 if at least one nodes has tag string.

       treeName	tag forget string ?string ...?
	      Removes  the tag definition for one or more of string.  It's not
	      an error if the tag string does not exist.

       treeName	tag lookups ?pattern?
	      Dump a lookup table (dictionary) of nodes-to-tags,  or  tags-to-
	      nodes  if	 pattern  is given.  With no arguments,	returns	a pair
	      list of nodes/tags, for nodes that have tags.  With an argument,
	      returns  a  pair list of tags/nodes.  lookups provides efficient
	      bulk processing when dealing with	large numbers of nodes	and/or
	      tags.

       treeName	tag names ?-glob? ?-regexp? ?-nocase?  ?node? ?node ...?
	      Returns a	list of	tags used by the tree.	If no node argument is
	      given, returns a list of all known tags.	Otherwise, returns the
	      union  of	the tags used by all given node	numbers.  Patterns can
	      be used via -glob	or -regexp.  If	-nocase	is used,  the  pattern
	      is expected to be	all lower case.

       treeName	tag nodes string ?string ...?
	      Returns  a  list of any nodes that have any of given string tag.
	      If no node is tagged with	any  of	 the  string,  then  an	 empty
	      string is	returned.

TRACE OPERATIONS
       Data fields can be traced much like tracing Tcl variables.  Data	traces
       cause a Tcl command to be executed whenever data	 fields	 are  created,
       read,  written, or unset.  A trace can apply to one or more nodes.  You
       can trace a specific node by using its id, or a group  of  nodes	 by  a
       their  tag.  Note: operations on	arrays trigger on the whole key	value,
       not the individual array	element.

       The tree's get, set, and	unset operations can trigger  various  traces.
       The  get	 operation can cause a read  trace to fire.  The set operation
       causes a	write trace to fire.  And if the data field is written for the
       first  time,  you  will	also  get a create trace.  The unset operation
       triggers	unset traces.

       Data traces are invoked by the trace operation.	The  general  form  is
       treeName	trace operation	?arg?...  Both operation and its arguments de-
       termine 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  ap-
	      pended 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  de-
		     mand.

	      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 re-
	      turned 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	opera-
	      tion.   It  consists  of	the  node id or	tag, data field	key, a
	      string of	letters	indicating  the	 operations  that  are	traced
	      (it's in the same	form as	ops) and, the command prefix.

       treeName	trace names
	      Returns a	list of	identifers for all the current traces.

NOTIFY OPERATIONS
       The  purpose of notify is to get	control	when structural	operations oc-
       cur 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,  re-
       sulting 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	struc-
	      ture  is changed (controlled by switches). Two arguments are ap-
	      pended 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  re-
	      turns  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 in-
			serts are ignored.

	      -disabletrace
			Disable	traces from firing during a notify event.

	      -get	Invoke command whenever	a node with  no	 keys  is  ac-
			cessed	(via get or with).  If a node has at least one
			key, this will not trigger.  The invocation occurs be-
			fore the read, meaning it can be used to implement de-
			mand loading of	data keys into empty nodes (eg.	 load-
			ing 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	subse-
			quent events occur before the event loop  is  entered,
			command	will still be invoked only once.

       treeName	notify delete notifyId
	      Deletes  one  or	more notifiers from the	tree.  NotifyId	is the
	      notifier identifier returned by the notify create	operation.

       treeName	notify info notifyId
	      Returns information about	the notify event  notifyId.   NotifyId
	      is  a notify identifier previously returned by the notify	create
	      operation.  It's the same	information specified for  the	notify
	      create  operation.   It  consists	of the notify id, a sublist of
	      event flags (it's	in the same form as flags)  and,  the  command
	      prefix.

       treeName	notify names
	      Returns a	list of	identifers for all the current notifiers.

TABLE EXAMPLE
       The following is	a simple example.

	       variable	Users {
		   tom	{ Name "Tom Brown"  Sex	M Age 19  Class	{4 5} Rate {A 1	B 2}}
		   mary	{ Name "Mary Brown" Sex	F Age 16  Class	{5}   Rate {A 2}}
		   sam	{ Name "Sam Spade"  Sex	M Age 19  Class	{3 4} Rate {B 3}}
	       }
	       set t [tree create]
	       foreach {i d} $Users {
		  # Use	name in	-tags so we don't have to do "0->mary" etc.
		  $t insert 0 -tags $i -data $d	-label $i
	       }

	       $t update   tom	     Sex F   Name "Tomi	Brown"
	       $t append   sam	     Name " Jr"
	       $t lappend  sam	     Class 5
	       $t incr	   mary	     Age
	       $t update   tom	     Rate(A) 2
	       $t incr	   0->mary   Age

	       # Set a trace.
	       proc ::Aupd {t id key op} { tclLog "AA: $t $id $key $op"	}
	       $t trace	create all Age w ::Aupd
	       $t incr	   mary	Age

	       # Display it.
	       pack [treeview .t -tree $t] -fill both -expand y
	       eval .t column insert end [$t keys all]

TREE EXAMPLE
       The following is	a nested tree example with updates.

	       variable	Info {
		 system	{
		    sol	 { OS Linux Version 3.4	}
		    bing { OS Win Version 7 }
		    gui	 { OS Mac Version 8 }
		 }
		 network {
		    intra { Address 192.168.1  Netmask 255.255.255.0 }
		    dmz	  { Address 192.168.10 Netmask 255.255.255.0 }
		    wan	  { Address 0.0.0.0 Netmask 0.0.0.0 Class {A 1 B 4}}
		 }
		 admins	{
		    sully { Name "Sully	Van Damme" Level 3 }
		    maverick { Name "Maverick Gump" Level 1 }
		 }
	       }

	       set s [tree create]
	       foreach {n vals}	$Info {
		 set ind [$s insert 0 -label $n]
		 foreach {i d} $vals {
		    $s insert $ind -label $i -data $d
		 }
	       }

	       set old [$s get	0->system->bing]
	       $s update   0->system->bing   OS	Linux Version 3.4
	       $s update   0->network->dmz   Address 192.168.11
	       $s update   0->network->wan   Class(A) 2
	       eval $s set 0->system->bing   $old
	       $s insert   0->admins -label linus -data	{ Name "Linus Torvalds"	Level 9	}

	       pack [treeview .s -tree $s -width 600] -fill both -expand y
	       eval .s column insert end [$s keys all]

SQLLOAD	EXAMPLE
       Here  is	 an  example using sqlload on table cust from a	database file,
       and displaying it in a treeview:

		set t [tree create]
		$t sqlload mydb.dat "select rowid,* from cust"
		pack [treeview .t -tree	$t -width 500] -fill both -expand y
		eval .t	column insert end [lsort [$t keys all]]

       Although	there is no corresponding sqldump  command,  scripting	it  is
       easy.  Following	is one approach.

		proc sqldump {t	db table {ids {}}} {
		    # Dump nodes from tree t into table	in open	sqlite database	db.
		    if {$ids ==	{}} { set ids [$t children root] }
		    set	keys [$t keys $ids]
		    catch { $db	eval "CREATE TABLE $table ( [join $keys	,] )" }
		    $t with s $ids {
			set nams {}
			set vals {}
			foreach	nam $s(*) {
			    lappend vals ($nam)
			    lappend nams $nam
			}
			set vals [join $vals ,]
			set nams [join $nams ,]
			set q [format {INSERT INTO %s (%s) VALUES (%s)}	$table $nams $vals]
			$db eval $q
		    }
		}
		sqlite3	[set db	dbhandle] mydb.dat
		sqldump	$t $db cust2

TREE KEY STRING	STORAGE
       Key  name  strings  are stored by default in a global hash table.  How-
       ever, 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  cre-
       ation.  To enable per-tree storage of keys, set blt::treeKeysLocal to 2
       before tree creation.  The above	is unavailable in safe interps.

C LANGUAGE API
       Blt_TreeApply, Blt_TreeApplyBFS,	Blt_TreeApplyDFS,  Blt_TreeChangeRoot,
       Blt_TreeCreate,	   Blt_TreeCreateEventHandler,	   Blt_TreeCreateNode,
       Blt_TreeCreateTrace,  Blt_TreeDeleteEventHandler,   Blt_TreeDeleteNode,
       Blt_TreeDeleteTrace,	    Blt_TreeExists,	    Blt_TreeFindChild,
       Blt_TreeFirstChild, Blt_TreeFirstKey,  Blt_TreeGetNode,	Blt_TreeGetTo-
       ken,	Blt_TreeGetValue,     Blt_TreeIsAncestor,    Blt_TreeIsBefore,
       Blt_TreeIsLeaf,	Blt_TreeLastChild,   Blt_TreeMoveNode,	 Blt_TreeName,
       Blt_TreeNextKey,	Blt_TreeNextNode, Blt_TreeNextSibling, Blt_TreeNodeDe-
       gree, Blt_TreeNodeDepth,	Blt_TreeNodeId,	Blt_TreeNodeLabel,  Blt_TreeN-
       odeParent,  Blt_TreePrevNode, Blt_TreePrevSibling, Blt_TreeRelabelNode,
       Blt_TreeReleaseToken, Blt_TreeRootNode, Blt_TreeSetValue, Blt_TreeSize,
       Blt_TreeSortNode, and Blt_TreeUnsetValue.

KEYWORDS
       tree, treeview, widget

BLT				      2.5			       tree(n)

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION | SYNTAX | NODE IDS AND TAGS | NODE MODIFIERS | TREE OPERATIONS | DICT-ARRAYS | TAG OPERATIONS | TRACE OPERATIONS | NOTIFY OPERATIONS | TABLE EXAMPLE | TREE EXAMPLE | SQLLOAD EXAMPLE | TREE KEY STRING STORAGE | C LANGUAGE API | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tree&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help