1
.TH TCLDOT N "02 December 1996"
5
tcldot \- graph manipulation in tcl
11
package require \fBTcldot\fR
14
Requires the dynamic loading facilities of tcl7.6 or later.
19
is a tcl dynamically loaded extension that incorporates
20
the directed graph facilities of
22
and the undirected graph facilities of
24
into tcl and provides a set of commands to control those
31
from batch processing tools to an interpreted and, if needed, interactive set
32
of graph manipulation facilities.
37
initially adds only three commands to tcl, namely
42
These commands return a handle for the graph that has just been created
43
and that handle can then be used as a command for further actions on the graph.
45
All other "commands" are of the form:
51
Many of the methods return further
52
handles of graphs, nodes of edges, which are themselves registered as commands.
54
The methods are described in detail below, but in summary:
58
.B "addedge, addnode, addsubgraph, countedges, countnodes, layout, listattributes, listedgeattributes, listnodeattributes, listedges, listnodes, listsubgraphs, render, rendergd, queryattributes, queryedgeattributes, querynodeattributes, queryattributevalues, queryedgeattributevalues, querynodeattributevalues, setattributes, setedgeattributes, setnodeattributes, showname, write."
62
.B "addedge, listattributes, listedges, listinedges, listoutedges, queryattributes, queryattributevalues, setattributes, showname."
66
.B "delete, listattributes, listnodes, queryattributes, queryattributevalues, setattributes, showname."
69
\fBdotnew\fR \fIgraphType ?attributeName attributeValue? ?...?\fR
71
creates a new empty graph and returns its
75
can be any supported by
77
namely: "graph," "digraph," "graphstrict," or "digraphstrict."
78
(In digraphs edges have a direction from tail to head. "Strict" graphs
79
or digraphs collapse multiple edges between the same pair of
80
nodes into a single edge.)
82
Following the mandatory
86
command will accept an arbitrary number of attribute name/value pairs
88
Certain special graph attributes and permitted values are described in
90
but the programmer can arbitrarily invent and assign values
91
to additional attributes beyond these.
94
the attribute name is separated from the value by an "=" character.
97
the "=" has been replaced by a " " (space) to be more consistent
104
set g [dotnew digraph rankdir LR]
108
\fBdotread\fR \fIfileHandle\fR
110
reads in a dot-language description of a graph from a previously opened
111
file identified by the
113
The command returns the
115
of the newly read graph. e.g.
118
set f [open test.dot r]
123
\fBdotstring\fR \fIstring\fR
125
reads in a dot-language description of a graph from a Tcl string;
126
The command returns the
128
of the newly read graph. e.g.
131
set g [dotread $dotsyntaxstring]
135
\fIgraphHandle\fR \fBaddnode\fR \fI?nodeName? ?attributeName attributeValue? ?...?\fR
137
creates a new node in the graph whose handle is
141
The handle of a node is a string like: "node0" where the integer value is
142
different for each node.
143
There can be an arbitrary number of attribute name/value pairs
145
Certain special node attributes and permitted values are described in
147
but the programmer can arbitrarily invent and assign values
148
to additional attributes beyond these.
152
set n [$g addnode "N" label "Top\\nNode" shape triangle eggs easyover]
155
A possible cause of confusion in
157
is the distinction between handles, names, labels, and variables.
158
The distinction is primarily in who owns them.
159
Handles are owned by tcldot and are guaranteed to be unique within
160
one interpreter session. Typically handles are assigned to variables,
161
like "n" above, for manipulation within a tcl script.
162
Variables are owned by the programmer.
163
Names are owned by the application that is using the
164
graph, typically names are important when reading in a graph from
165
an external program or file. Labels are the text that is displayed with
167
(or edge) when the graph is displayed, labels are meaningful to the
168
reader of the graph. Only the handles and variables are essential to
170
ability to manipulate abstract graphs. If a name is not specified then
171
it defaults to the string representation of the handle, if a label is
172
not specified then it defaults to the name.
175
\fIgraphHandle\fR \fBaddedge\fR \fItailNode headNode ?attributeName attributeValue? ?...?\fR
177
creates a new edge in the graph whose handle is
184
can be specified either by their
193
$g addedge $n $m label "NM"
197
$g addedge N M label "NM"
200
The argument is recognized as a handle if possible and so it is best
201
to avoid names like "node6" for nodes. If there is potential for conflict then use
203
to translate explicitly from names to handles.
209
$g addedge [$g findnode "node6"] [$g findnode "node99"]
212
There can be an arbitrary number of attribute name/value pairs
214
Certain special edge attributes and permitted values are described in
216
but the programmer can arbitrarily invent and assign values
217
to additional attributes beyond these.
220
\fIgraphHandle\fR \fBaddsubgraph\fR \fI?graphName? ?attributeName attributeValue? ?...?\fR
222
creates a new subgraph in the graph and returns its
226
is omitted then the name of the subgraph defaults to it's
228
There can be an arbitrary number of attribute name/value pairs
230
Certain special graph attributes and permitted values are described in
232
but the programmer can arbitrarily invent and assign values
233
to additional attributes beyond these.
237
set sg [$g addsubgraph dinglefactor 6]
240
Clusters, as described in
242
are created by giving the subgraph a name that begins with the string:
243
"cluster". Cluster can be labelled by using the \fIlabel\fR attibute.
247
set cg [$g addsubgraph cluster_A label dongle dinglefactor 6]
251
\fInodeHandle\fR \fBaddedge\fR \fIheadNode ?attributeName attributeValue? ?...?\fR
253
creates a new edge from the tail node identified by tha
257
which can be specified either by
261
(with preference to recognizing the argument as a handle).
262
The graph in which this is drawn is the graph in which both nodes are
264
There can be an arbitrary number of attribute name/value pairs
266
These edge attributes and permitted values are described in
271
[$g addnode] addedge [$g addnode] label "NM"
275
\fIgraphHandle\fR \fBdelete\fR
277
\fInodeHandle\fR \fBdelete\fR
279
\fIedgeHandle\fR \fBdelete\fR
281
Delete all data structures associated with the graph, node or edge
282
from the internal storage of the interpreter. Deletion of a node also
283
results in the the deletion of all subtending edges on that node.
284
Deletion of a graph also results in the deletion of all nodes and
285
subgraphs within that graph (and hence all edges too). The return from
286
these delete commands is a null string.
289
\fIgraphHandle\fR \fBcountnodes\fR
291
\fIgraphHandle\fR \fBcountedges\fR
293
Returns the number of nodes, or edges, in the graph.
296
\fIgraphHandle\fR \fBlistedges\fR
298
\fIgraphHandle\fR \fBlistnodes\fR
300
\fIgraphHandle\fR \fBlistsubgraphs\fR
302
\fInodeHandle\fR \fBlistedges\fR
304
\fInodeHandle\fR \fBlistinedges\fR
306
\fInodeHandle\fR \fBlistoutedges\fR
308
\fIedgeHandle\fR \fBlistnodes\fR
310
Each return a list of handles of graphs, nodes or edges, as appropriate.
313
\fIgraphHandle\fR \fBfindnode\fR \fInodeName\fR
315
\fIgraphHandle\fR \fBfindedge\fR \fItailnodeName headNodeName\fR
317
\fInodeHandle\fR \fBfindedge\fR \fInodeName\fR
319
Each return the handle of the item if found, or an error if none are found.
320
For non-strict graphs when there are multiple edges between two nodes
322
will return an arbitrary edge from the set.
325
\fIgraphHandle\fR \fBshowname\fR
327
\fInodeHandle\fR \fBshowname\fR
329
\fIedgeHandle\fR \fBshowname\fR
331
Each return the name of the item. Edge names are of the form:
332
"a->b" where "a" and "b" are the names of the nodes and the connector
333
"->" indicates the tail-to-head direction of the edge. In undirected
334
graphs the connector "--" is used.
337
\fIgraphHandle\fR \fBsetnodeattributes\fR \fIattributeName attributeValue ?...?\fR
339
\fIgraphHandle\fR \fBsetedgeattributes\fR \fIattributeName attributeValue ?...?\fR
341
Set one or more default attribute name/values that are to apply to
342
all nodes (edges) unless overridden by subgraphs or per-node
343
(per-edge) attributes.
346
\fIgraphHandle\fR \fBlistnodeattributes\fR
348
\fIgraphHandle\fR \fBlistedgeattributes\fR
350
Return a list of attribute names.
353
\fIgraphHandle\fR \fBquerynodeattributes\fR \fIattributeName ?...?\fR
355
\fIgraphHandle\fR \fBqueryedgeattributes\fR \fIattributeName ?...?\fR
357
Return a list of default attribute value, one value for each of the
358
attribute names provided with the command.
361
\fIgraphHandle\fR \fBquerynodeattributes\fR \fIattributeName ?...?\fR
363
\fIgraphHandle\fR \fBqueryedgeattributes\fR \fIattributeName ?...?\fR
365
Return a list of pairs of attrinute name and default attribute value,
366
one pair for each of the attribute names provided with the command.
369
\fIgraphHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
371
\fInodeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
373
\fIedgeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
375
Set one or more attribute name/value pairs for a specific graph, node,
379
\fIgraphHandle\fR \fBlistattributes\fR
381
\fInodeHandle\fR \fBlistattributes\fR
383
\fIedgeHandle\fR \fBlistattributes\fR
385
Return a list of attribute names (attribute values are provided by
389
\fIgraphHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
391
\fInodeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
393
\fIedgeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
395
Return a list of attribute value, one value for each of the
396
attribute names provided with the command.
399
\fIgraphHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
401
\fInodeHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
403
\fIedgeHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
405
Return a list of pairs or attribute name and attribute value,
406
one value for each of the attribute names provided with the command.
409
\fIgraphHandle\fR \fBlayout ?DOT|NEATO?\fR
411
Annotate the graph with layout information. This commands takes an
412
abstract graph add shape and position information to it according to
416
rules of eye-pleasing graph layout. If the layout engine is
417
unspecified then it defaults to DOT for directed graphs, and NEATO otherwise.
418
The result of the layout is stored
419
as additional attributes name/value pairs in the graph, node and edges.
420
These attributes are intended to be interpreted by subsequent
427
\fIgraphHandle\fR \fBwrite\fR \fIfileHandle format ?DOT|NEATO?\fR
429
Write a graph to the open file represented by
435
are: "ps" "mif" "hpgl" "plain" "dot" "gif" "ismap"
436
If the layout hasn't been already done, then it will be done as part
437
of this operation using the same rules for selecting the layout engine
438
as for the layout command.
441
\fIgraphHandle\fR \fBrendergd\fR \fIgdHandle\fR
443
Generates a rendering of a graph to a new
444
or existing gifImage structure (see
449
If the layout hasn't been already done, then it will be done as part
450
of this operation using the same rules for selecting the layout engine
451
as for the layout command.
454
\fIgraphHandle\fR \fBrender\fR \fI?canvas ?DOT|NEATO??\fR
456
If no \fIcanvas\fR argument is provided then \fBrender\fR
457
returns a string of commands which, when evaluated, will render the
462
is available in variable
465
If a \fIcanvas\fR argument is provided then \fBrender\fR
466
produces a set of commands for \fIcanvas\fR instead of $c.
468
If the layout hasn't been already done, then it will be done as part
469
of this operation using the same rules for selecting the layout engine
470
as for the layout command.
473
#!/usr/local/bin/wish
474
package require Tcldot
477
set g [dotnew digraph rankdir LR]
478
$g setnodeattribute style filled color white
479
[$g addnode Hello] addedge [$g addnode World!]
481
if {[info exists debug]} {
482
puts [$g render] ;# see what render produces
489
generates a series of canvas commands for each graph element, for example
490
a node typically consist of two items on the canvas, one for the shape
491
and the other for the label. The canvas items are automatically
495
) by the commands generated by render. The tags take one of two forms:
496
text items are tagged with 0<handle> and
497
shapes and lines are rendered with 1<handle>.
499
The tagging can be used to recognize when a user wants to interact with
500
a graph element using the mouse. See the script in
502
of the tcldot distribution for a demonstration of this facility.
506
Still batch-oriented. It would be nice if the layout was maintained incrementally.
507
(The intent is to address this limitation in graphviz_2_0.)
511
John Ellson, Lucent Technologies, Holmdel, NJ. (ellson@lucent.com)
515
John Ousterhout, of course, for
519
Steven North and Eleftherios Koutsofios for
521
Karl Lehenbauer and Mark Diekhans of NeoSoft
522
for the handles.c code which was derived from tclXhandles.c.
523
Tom Boutell of the Quest Center at Cold Spring Harbor Labs for the gif drawing routines.
524
Spencer Thomas of the University of Michigan for gdTcl.c.
525
Dayatra Shands for coding much of the initial implementation of
530
graph, tcl, tk, dot, neato.
added
removed
tcldot/tcldot.n
