Ubuntu Manpage: tcldot - graph manipulation in tcl

NAME

       tcldot - graph manipulation in tcl

SYNOPSIS

       #!/usr/local/bin/tclsh
       package require Tcldot

USAGE

       Requires the dynamic loading facilities of tcl7.6 or later.

INTRODUCTION

       tcldot  is  a  tcl  dynamically  loaded  extension  that  incorporates  the directed graph
       facilities of dot(1), and the undirected  graph  facilities  of  neato(1),  into  tcl  and
       provides  a  set  of  commands to control those facilities.  tcldot converts dot and neato
       from batch processing tools to an interpreted and, if needed,  interactive  set  of  graph
       manipulation facilities.

COMMANDS

tcldot initially adds only three commands to tcl, namely dotnew, dotread, and dotstring.
These commands return a handle for the graph that has just been created and that handle
can then be used as a command for further actions on the graph.

All other "commands" are of the form:

handle <method> parameters

Many of the methods return further handles of graphs, nodes of edges, which are themselves
registered as commands.

The methods are described in detail below, but in summary:

Graph methods are:

addedge, addnode, addsubgraph, countedges, countnodes, layout, listattributes,
listedgeattributes, listnodeattributes, listedges, listnodes, listnodesrev,
listsubgraphs, render, rendergd, queryattributes, queryedgeattributes,
querynodeattributes, queryattributevalues, queryedgeattributevalues,
querynodeattributevalues, setattributes, setedgeattributes, setnodeattributes,
showname, write.

Node methods are:

addedge, listattributes, listedges, listinedges, listoutedges, queryattributes,
queryattributevalues, setattributes, showname.

Edge methods are:

delete, listattributes, listnodes, queryattributes, queryattributevalues,
setattributes, showname.

dotnew graphType ?attributeName attributeValue? ?...?

creates a new empty graph and returns its graphHandle.

graphType can be any supported by dot(1) namely: "graph," "digraph," "graphstrict,"
or "digraphstrict." (In digraphs edges have a direction from tail to head.
"Strict" graphs or digraphs collapse multiple edges between the same pair of nodes
into a single edge.)

Following the mandatory graphType parameter the dotnew command will accept an
arbitrary number of attribute name/value pairs for the graph. Certain special
graph attributes and permitted values are described in dot(1), but the programmer
can arbitrarily invent and assign values to additional attributes beyond these. In
dot the attribute name is separated from the value by an "=" character. In tcldot
the "=" has been replaced by a " " (space) to be more consistent with tcl syntax.
e.g.

set g [dotnew digraph rankdir LR]

dotread fileHandle

reads in a dot-language description of a graph from a previously opened file
identified by the fileHandle. The command returns the graphHandle of the newly
read graph. e.g.

set f [open test.dot r]
set g [dotread $f]

dotstring string

reads in a dot-language description of a graph from a Tcl string; The command
returns the graphHandle of the newly read graph. e.g.

set g [dotstring $dotsyntaxstring]

graphHandle addnode ?nodeName? ?attributeName attributeValue? ?...?

creates a new node in the graph whose handle is graphHandle and returns its
nodeHandle. The handle of a node is a string like: "node0" where the integer value
is different for each node. There can be an arbitrary number of attribute
name/value pairs for the node. Certain special node attributes and permitted
values are described in dot(1), but the programmer can arbitrarily invent and
assign values to additional attributes beyond these. e.g.

set n [$g addnode "N" label "Top\nNode" shape triangle eggs easyover]

A possible cause of confusion in tcldot is the distinction between handles, names,
labels, and variables. The distinction is primarily in who owns them. Handles are
owned by tcldot and are guaranteed to be unique within one interpreter session.
Typically handles are assigned to variables, like "n" above, for manipulation
within a tcl script. Variables are owned by the programmer. Names are owned by
the application that is using the graph, typically names are important when reading
in a graph from an external program or file. Labels are the text that is displayed
with the node (or edge) when the graph is displayed, labels are meaningful to the
reader of the graph. Only the handles and variables are essential to tcldot's
ability to manipulate abstract graphs. If a name is not specified then it defaults
to the string representation of the handle, if a label is not specified then it
defaults to the name.

graphHandle addedge tailNode headNode ?attributeName attributeValue? ?...?

creates a new edge in the graph whose handle is graphHandle and returns its
edgeHandle. tailNode and headNode can be specified either by their nodeHandle or
by their nodeName. e.g.

set n [$g addnode]
set m [$g addnode]
$g addedge $n $m label "NM"

$g addnode N
$g addnode M
$g addedge N M label "NM"

The argument is recognized as a handle if possible and so it is best to avoid names
like "node6" for nodes. If there is potential for conflict then use findnode to
translate explicitly from names to handles. e.g.

$g addnode "node6"
$g addnode "node99"
$g addedge [$g findnode "node6"] [$g findnode "node99"]

There can be an arbitrary number of attribute name/value pairs for the edge.
Certain special edge attributes and permitted values are described in dot(1), but
the programmer can arbitrarily invent and assign values to additional attributes
beyond these.

graphHandle addsubgraph ?graphName? ?attributeName attributeValue? ?...?

creates a new subgraph in the graph and returns its graphHandle. If the graphName
is omitted then the name of the subgraph defaults to it's graphHandle. There can
be an arbitrary number of attribute name/value pairs for the subgraph. Certain
special graph attributes and permitted values are described in dot(1), but the
programmer can arbitrarily invent and assign values to additional attributes beyond
these. e.g.

set sg [$g addsubgraph dinglefactor 6]

Clusters, as described in dot(1), are created by giving the subgraph a name that
begins with the string: "cluster". Cluster can be labelled by using the label
attibute. e.g.

set cg [$g addsubgraph cluster_A label dongle dinglefactor 6]

nodeHandle addedge headNode ?attributeName attributeValue? ?...?

creates a new edge from the tail node identified by tha nodeHandle to the headNode
which can be specified either by nodeHandle or by nodeName (with preference to
recognizing the argument as a handle). The graph in which this is drawn is the
graph in which both nodes are members. There can be an arbitrary number of
attribute name/value pairs for the edge. These edge attributes and permitted
values are described in dot(1). e.g.

[$g addnode] addedge [$g addnode] label "NM"

graphHandle delete

nodeHandle delete

edgeHandle delete

Delete all data structures associated with the graph, node or edge from the
internal storage of the interpreter. Deletion of a node also results in the the
deletion of all subtending edges on that node. Deletion of a graph also results in
the deletion of all nodes and subgraphs within that graph (and hence all edges
too). The return from these delete commands is a null string.

graphHandle countnodes

graphHandle countedges

Returns the number of nodes, or edges, in the graph.

graphHandle listedges

graphHandle listnodes

graphHandle listnodesrev

graphHandle listsubgraphs

nodeHandle listedges

nodeHandle listinedges

nodeHandle listoutedges

edgeHandle listnodes

Each return a list of handles of graphs, nodes or edges, as appropriate.

graphHandle findnode nodeName

graphHandle findedge tailnodeName headNodeName

nodeHandle findedge nodeName

Each return the handle of the item if found, or an error if none are found. For
non-strict graphs when there are multiple edges between two nodes findedge will
return an arbitrary edge from the set.

graphHandle showname

nodeHandle showname

edgeHandle showname

Each return the name of the item. Edge names are of the form: "a->b" where "a" and
"b" are the names of the nodes and the connector "->" indicates the tail-to-head
direction of the edge. In undirected graphs the connector "--" is used.

graphHandle setnodeattributes attributeName attributeValue ?...?

graphHandle setedgeattributes attributeName attributeValue ?...?

Set one or more default attribute name/values that are to apply to all nodes
(edges) unless overridden by subgraphs or per-node (per-edge) attributes.

graphHandle listnodeattributes

graphHandle listedgeattributes

Return a list of attribute names.

graphHandle querynodeattributes attributeName ?...?

graphHandle queryedgeattributes attributeName ?...?

Return a list of default attribute value, one value for each of the attribute names
provided with the command.

graphHandle querynodeattributes attributeName ?...?

graphHandle queryedgeattributes attributeName ?...?

Return a list of pairs of attrinute name and default attribute value, one pair for
each of the attribute names provided with the command.

graphHandle setattributes attributeName attributeValue ?...?

nodeHandle setattributes attributeName attributeValue ?...?

edgeHandle setattributes attributeName attributeValue ?...?

Set one or more attribute name/value pairs for a specific graph, node, or edge
instance.

graphHandle listattributes

nodeHandle listattributes

edgeHandle listattributes

Return a list of attribute names (attribute values are provided by queryattribute

graphHandle queryattributes attributeName ?...?

nodeHandle queryattributes attributeName ?...?

edgeHandle queryattributes attributeName ?...?

Return a list of attribute value, one value for each of the attribute names
provided with the command.

graphHandle queryattributevalues attributeName ?...?

nodeHandle queryattributevalues attributeName ?...?

edgeHandle queryattributevalues attributeName ?...?

Return a list of pairs or attribute name and attribute value, one value for each of
the attribute names provided with the command.

Annotate the graph with layout information. This commands takes an abstract graph
add shape and position information to it according to the layout engine's rules of
eye-pleasing graph layout. If the layout engine is unspecified then it defaults to
dot for directed graphs, and neato otherwise. If the nop engine is specified then
layout infomation from the input graph is used. The result of the layout is stored
as additional attributes name/value pairs in the graph, node and edges. These
attributes are intended to be interpreted by subsequent write or render commands.

Write a graph to the open file represented by fileHandle in a specific format.
Possible formats are: "ps" "mif" "hpgl" "plain" "dot" "gif" "ismap" If the layout
hasn't been already done, then it will be done as part of this operation using the
same rules for selecting the layout engine as for the layout command.

graphHandle rendergd gdHandle

Generates a rendering of a graph to a new or existing gifImage structure (see
gdTcl(1) ). Returns the gdHandle of the image. If the layout hasn't been already
done, then it will be done as part of this operation using the same rules for
selecting the layout engine as for the layout command.

If no canvas argument is provided then render returns a string of commands which,
when evaluated, will render the graph to a Tk canvas whose canvasHandle is
available in variable $c

If a canvas argument is provided then render produces a set of commands for canvas
instead of $c.

If the layout hasn't been already done, then it will be done as part of this
operation using the same rules for selecting the layout engine as for the layout
command.

#!/usr/local/bin/wish
package require Tcldot
set c [canvas .c]
pack $c
set g [dotnew digraph rankdir LR]
$g setnodeattribute style filled color white
[$g addnode Hello] addedge [$g addnode World!]
$g layout
if {[info exists debug]} {
puts [$g render] ;# see what render produces
}
eval [$g render]

Render generates a series of canvas commands for each graph element, for example a
node typically consist of two items on the canvas, one for the shape and the other
for the label. The canvas items are automatically tagged (See canvas(n) ) by the
commands generated by render. The tags take one of two forms: text items are
tagged with 0<handle> and shapes and lines are rendered with 1<handle>.

The tagging can be used to recognize when a user wants to interact with a graph
element using the mouse. See the script in examples/disp of the tcldot
distribution for a demonstration of this facility.

BUGS

       Still  batch-oriented.  It would be nice if the layout was maintained incrementally.  (The
       intent is to address this limitation in graphviz_2_0.)

AUTHOR

       John Ellson (ellson@graphviz.org)

ACKNOWLEDGEMENTS

       John Ousterhout, of course, for tcl and tk.  Steven North and Eleftherios  Koutsofios  for
       dot.   Karl  Lehenbauer  and  Mark  Diekhans  of  NeoSoft for the handles.c code which was
       derived from tclXhandles.c.  Tom Boutell of the Quest Center at Cold  Spring  Harbor  Labs
       for  the  gif drawing routines.  Spencer Thomas of the University of Michigan for gdTcl.c.
       Dayatra Shands for coding much of the initial implementation of tcldot.

KEYWORDS

       graph, tcl, tk, dot, neato.

                                          Tcl Extensions                             tcldot(3tcl)