Class ::tycho::Graph


Inherits: ::tycho::Object - Source File - Contents: public methods - protected method - protected variables
A graph is a collection of nodes that may have other nodes as parents or children. This class provides methods to build, browse, and edit such a data structure. The contents of each node can be arbitrary Tcl string. Graphical editors and viewers for this class, however, expect the contents to be a Tcl list with an even number of elements. The even elements (0, 2, 4, ...) are arbitrary keywords, and the odd elements are arbitrary strings or lists. Although certain keywords are understood by certain graphical display widgets, any keywords can be used. A method is provided to describe the data structure as a list, which can, for example, be written to a file. A method is also provided to convert this list back into a graph.

Here is an example of how to use the Graph:

   catch {delete object foo}
   ::tycho::Graph foo
   foo add a {}
   foo add c {} a
   foo add d {} a
   foo add e {} a
   foo add f {} e
   foo addArc d e
   ::tycho::post [foo describe]
The description that is posted in the last line will be: "{d {} a} {e {} {a d}} {a {} {}} {f {} e} {c {} a}", or some permutation of these list items. This is a list of nodes in the graph. Each node is a list of three items, the name, contents, and list of parents. In the above example, the contents of each node is an empty list. The verifyAll method can be used to check the graph to make sure that all parents and children that are mentioned are present.

Public constructs

Public Methods

add nodename contents {parents {}}
Add a node to the graph with the specified name and contents. If parents are specified (using the optional third argument), then this node is added to the list of children of the parents. Otherwise, it is identified as a root node. It is not verified whether the parents exist (indeed, they frequently will not exist) so when the complete graph has been constructed, verifyAll should be invoked. It is an error if the specified node name already exists in the graph.
addArc parent child
Add an arc between existing nodes, if it doesn't already exist. If it does exist, ignore. It is an error if either node does not exist.
attribute attrname node
Return the value of the specified attribute for the specified node. It is an error if the attribute has not been set for this node. The method attributeInit or attributeSet should be used to set the value of the attribute. Attributes are used by various algorithms that traverse the graph. For example, to keep track of which nodes have beed visited already in some graph traversal algorithm, you could use an attribute with "visited" that takes value 0 or 1.
attributeInit attrname {initvalue 0}
Set the specified attribute for all nodes to the specified value. The attribute name is an arbitrary identifying string, and the value is an arbitrary string. If the value is not given, it defaults to "0".
attributeSet attrname node {value 1}
Set the specified attribute for the specified node to the specified value. The attribute name and value can be any arbitrary Tcl strings.
children nodename
Return the list of children of a node.
clear
Remove all nodes from the graph.
contents nodename
Return the contents of a cell of the forest. The contents can be any arbitrary Tcl string or list.
delete nodename
Delete a node from the graph. If the node has children, then the parents of the node are appended as parents of the children.
deleteArc parent child
Delete an existing arc between existing nodes. If it does not exist, ignore. It is an error if either node does not exist.
describe
Return a list that describes the graph. The returned list contains one element for each node in the graph, in arbitrary order. Each node is described as a list with three elements: the node name, the contents, and the list of parents.
exists nodename
Return 1 if the specified node exists, otherwise, return 0.
init description
Initialize the graph from a description. The format of the description should be compatible with that produced by the describe method. The graph should be verified after this using verifyAll.
parents nodename
Return the list of parents of a node. If the node is a root, return an empty string.
rename nodename newname
Give a node a new name. It is an error if the new name is already the name of another node. It is assumed that the parents and children of the node exist (that the graph has been verified using verifyAll).
roots
Return a list the names of the root nodes (those with no parents).
setContents nodename contents
Set the contents of a node.
verify nodename
Verify that a node exists in the graph with the name given by the argument. Trigger an error if not. In other words, if this method returns, the nodename is valid. Note that this method does not check the validity of the parents and children of a node. That is done by verifyAll.
verifyAll {repair {}}
Verify that all parents and children of all nodes exist as nodes in the graph. If no argument is given, or if the argument is an empty string, then trigger an error on the first invalid one encountered. Otherwise, repair the graph by removing the offending reference to a parent or child.

Protected constructs

Protected Method

listreplace listname olditem newitem
For the list listname, remove the olditem and append the newitem. The items are strings, and olditem must match exactly a string in the list. Issue a warning olditem is not present in the list.

Protected Variables

rootnames
List of the names of the roots of the trees in the forest.
contentslist
Array storing the contents of each node of the tree.
parentnames
Array storing the parent name for each node of the tree.
childrennames
Array storing the list of children for each node.

Index of classes



Author: Edward A. Lee
Version: @(#)Graph.itcl 1.8 12/16/96
Copyright: (c) 1995-1996 The Regents of the University of California.