1tcldot(3tcl) tcldot(3tcl)
2
3
4
6 tcldot - graph manipulation in tcl
7
8
10 #!/usr/local/bin/tclsh
11 package require Tcldot
12
13
15 Requires the dynamic loading facilities of tcl7.6 or later.
16
17
19 tcldot is a tcl dynamically loaded extension that incorporates the di‐
20 rected graph facilities of dot(1), and the undirected graph facilities
21 of neato(1), into tcl and provides a set of commands to control those
22 facilities. tcldot converts dot and neato from batch processing tools
23 to an interpreted and, if needed, interactive set of graph manipulation
24 facilities.
25
26
28 tcldot initially adds only three commands to tcl, namely dotnew,
29 dotread, and dotstring. These commands return a handle for the graph
30 that has just been created and that handle can then be used as a com‐
31 mand for further actions on the graph.
32
33 All other "commands" are of the form:
34
35 handle <method> parameters
36
37 Many of the methods return further handles of graphs, nodes of edges,
38 which are themselves registered as commands.
39
40 The methods are described in detail below, but in summary:
41
42 Graph methods are:
43
44 addedge, addnode, addsubgraph, countedges, countnodes, layout,
45 listattributes, listedgeattributes, listnodeattributes, list‐
46 edges, listnodes, listnodesrev, listsubgraphs, render, rendergd,
47 queryattributes, queryedgeattributes, querynodeattributes,
48 queryattributevalues, queryedgeattributevalues, querynodeat‐
49 tributevalues, setattributes, setedgeattributes, setnodeat‐
50 tributes, showname, write.
51
52 Node methods are:
53
54 addedge, listattributes, listedges, listinedges, listoutedges,
55 queryattributes, queryattributevalues, setattributes, showname.
56
57 Edge methods are:
58
59 delete, listattributes, listnodes, queryattributes, queryat‐
60 tributevalues, setattributes, showname.
61
62
63 dotnew graphType ?attributeName attributeValue? ?...?
64
65 creates a new empty graph and returns its graphHandle.
66
67 graphType can be any supported by dot(1) namely: "graph," "di‐
68 graph," "graphstrict," or "digraphstrict." (In digraphs edges
69 have a direction from tail to head. "Strict" graphs or digraphs
70 collapse multiple edges between the same pair of nodes into a
71 single edge.)
72
73 Following the mandatory graphType parameter the dotnew command
74 will accept an arbitrary number of attribute name/value pairs
75 for the graph. Certain special graph attributes and permitted
76 values are described in dot(1), but the programmer can arbitrar‐
77 ily invent and assign values to additional attributes beyond
78 these. In dot the attribute name is separated from the value by
79 an "=" character. In tcldot the "=" has been replaced by a " "
80 (space) to be more consistent with tcl syntax. e.g.
81
82 set g [dotnew digraph rankdir LR]
83
84
85 dotread fileHandle
86
87 reads in a dot-language description of a graph from a previously
88 opened file identified by the fileHandle. The command returns
89 the graphHandle of the newly read graph. e.g.
90
91 set f [open test.dot r]
92 set g [dotread $f]
93
94
95 dotstring string
96
97 reads in a dot-language description of a graph from a Tcl
98 string; The command returns the graphHandle of the newly read
99 graph. e.g.
100
101 set g [dotstring $dotsyntaxstring]
102
103
104 graphHandle addnode ?nodeName? ?attributeName attributeValue? ?...?
105
106 creates a new node in the graph whose handle is graphHandle and
107 returns its nodeHandle. The handle of a node is a string like:
108 "node0" where the integer value is different for each node.
109 There can be an arbitrary number of attribute name/value pairs
110 for the node. Certain special node attributes and permitted
111 values are described in dot(1), but the programmer can arbitrar‐
112 ily invent and assign values to additional attributes beyond
113 these. e.g.
114
115 set n [$g addnode "N" label "Top\nNode" shape triangle eggs easyover]
116
117 A possible cause of confusion in tcldot is the distinction be‐
118 tween handles, names, labels, and variables. The distinction is
119 primarily in who owns them. Handles are owned by tcldot and are
120 guaranteed to be unique within one interpreter session. Typi‐
121 cally handles are assigned to variables, like "n" above, for ma‐
122 nipulation within a tcl script. Variables are owned by the pro‐
123 grammer. Names are owned by the application that is using the
124 graph, typically names are important when reading in a graph
125 from an external program or file. Labels are the text that is
126 displayed with the node (or edge) when the graph is displayed,
127 labels are meaningful to the reader of the graph. Only the han‐
128 dles and variables are essential to tcldot's ability to manipu‐
129 late abstract graphs. If a name is not specified then it de‐
130 faults to the string representation of the handle, if a label is
131 not specified then it defaults to the name.
132
133
134 graphHandle addedge tailNode headNode ?attributeName attributeValue?
135 ?...?
136
137 creates a new edge in the graph whose handle is graphHandle and
138 returns its edgeHandle. tailNode and headNode can be specified
139 either by their nodeHandle or by their nodeName. e.g.
140
141 set n [$g addnode]
142 set m [$g addnode]
143 $g addedge $n $m label "NM"
144
145 $g addnode N
146 $g addnode M
147 $g addedge N M label "NM"
148
149 The argument is recognized as a handle if possible and so it is
150 best to avoid names like "node6" for nodes. If there is poten‐
151 tial for conflict then use findnode to translate explicitly from
152 names to handles. e.g.
153
154 $g addnode "node6"
155 $g addnode "node99"
156 $g addedge [$g findnode "node6"] [$g findnode "node99"]
157
158 There can be an arbitrary number of attribute name/value pairs
159 for the edge. Certain special edge attributes and permitted
160 values are described in dot(1), but the programmer can arbitrar‐
161 ily invent and assign values to additional attributes beyond
162 these.
163
164
165 graphHandle addsubgraph ?graphName? ?attributeName attributeValue?
166 ?...?
167
168 creates a new subgraph in the graph and returns its graphHandle.
169 If the graphName is omitted then the name of the subgraph de‐
170 faults to it's graphHandle. There can be an arbitrary number of
171 attribute name/value pairs for the subgraph. Certain special
172 graph attributes and permitted values are described in dot(1),
173 but the programmer can arbitrarily invent and assign values to
174 additional attributes beyond these. e.g.
175
176 set sg [$g addsubgraph dinglefactor 6]
177
178 Clusters, as described in dot(1), are created by giving the sub‐
179 graph a name that begins with the string: "cluster". Cluster
180 can be labelled by using the label attibute. e.g.
181
182 set cg [$g addsubgraph cluster_A label dongle dinglefactor 6]
183
184
185 nodeHandle addedge headNode ?attributeName attributeValue? ?...?
186
187 creates a new edge from the tail node identified by tha nodeHan‐
188 dle to the headNode which can be specified either by nodeHandle
189 or by nodeName (with preference to recognizing the argument as a
190 handle). The graph in which this is drawn is the graph in which
191 both nodes are members. There can be an arbitrary number of at‐
192 tribute name/value pairs for the edge. These edge attributes
193 and permitted values are described in dot(1). e.g.
194
195 [$g addnode] addedge [$g addnode] label "NM"
196
197
198 graphHandle delete
199
200 nodeHandle delete
201
202 edgeHandle delete
203
204 Delete all data structures associated with the graph, node or
205 edge from the internal storage of the interpreter. Deletion of
206 a node also results in the the deletion of all subtending edges
207 on that node. Deletion of a graph also results in the deletion
208 of all nodes and subgraphs within that graph (and hence all
209 edges too). The return from these delete commands is a null
210 string.
211
212
213 graphHandle countnodes
214
215 graphHandle countedges
216
217 Returns the number of nodes, or edges, in the graph.
218
219
220 graphHandle listedges
221
222 graphHandle listnodes
223
224 graphHandle listnodesrev
225
226 graphHandle listsubgraphs
227
228 nodeHandle listedges
229
230 nodeHandle listinedges
231
232 nodeHandle listoutedges
233
234 edgeHandle listnodes
235
236 Each return a list of handles of graphs, nodes or edges, as ap‐
237 propriate.
238
239
240 graphHandle findnode nodeName
241
242 graphHandle findedge tailnodeName headNodeName
243
244 nodeHandle findedge nodeName
245
246 Each return the handle of the item if found, or an error if none
247 are found. For non-strict graphs when there are multiple edges
248 between two nodes findedge will return an arbitrary edge from
249 the set.
250
251
252 graphHandle showname
253
254 nodeHandle showname
255
256 edgeHandle showname
257
258 Each return the name of the item. Edge names are of the form:
259 "a->b" where "a" and "b" are the names of the nodes and the con‐
260 nector "->" indicates the tail-to-head direction of the edge. In
261 undirected graphs the connector "--" is used.
262
263
264 graphHandle setnodeattributes attributeName attributeValue ?...?
265
266 graphHandle setedgeattributes attributeName attributeValue ?...?
267
268 Set one or more default attribute name/values that are to apply
269 to all nodes (edges) unless overridden by subgraphs or per-node
270 (per-edge) attributes.
271
272
273 graphHandle listnodeattributes
274
275 graphHandle listedgeattributes
276
277 Return a list of attribute names.
278
279
280 graphHandle querynodeattributes attributeName ?...?
281
282 graphHandle queryedgeattributes attributeName ?...?
283
284 Return a list of default attribute value, one value for each of
285 the attribute names provided with the command.
286
287
288 graphHandle querynodeattributes attributeName ?...?
289
290 graphHandle queryedgeattributes attributeName ?...?
291
292 Return a list of pairs of attrinute name and default attribute
293 value, one pair for each of the attribute names provided with
294 the command.
295
296
297 graphHandle setattributes attributeName attributeValue ?...?
298
299 nodeHandle setattributes attributeName attributeValue ?...?
300
301 edgeHandle setattributes attributeName attributeValue ?...?
302
303 Set one or more attribute name/value pairs for a specific graph,
304 node, or edge instance.
305
306
307 graphHandle listattributes
308
309 nodeHandle listattributes
310
311 edgeHandle listattributes
312
313 Return a list of attribute names (attribute values are provided
314 by queryattribute
315
316
317 graphHandle queryattributes attributeName ?...?
318
319 nodeHandle queryattributes attributeName ?...?
320
321 edgeHandle queryattributes attributeName ?...?
322
323 Return a list of attribute value, one value for each of the at‐
324 tribute names provided with the command.
325
326
327 graphHandle queryattributevalues attributeName ?...?
328
329 nodeHandle queryattributevalues attributeName ?...?
330
331 edgeHandle queryattributevalues attributeName ?...?
332
333 Return a list of pairs or attribute name and attribute value,
334 one value for each of the attribute names provided with the com‐
335 mand.
336
337
338 graphHandle layout ?dot|neato|circo|twopi|fdp|nop?
339
340 Annotate the graph with layout information. This commands takes
341 an abstract graph add shape and position information to it ac‐
342 cording to the layout engine's rules of eye-pleasing graph lay‐
343 out. If the layout engine is unspecified then it defaults to dot
344 for directed graphs, and neato otherwise. If the nop engine is
345 specified then layout information from the input graph is used.
346 The result of the layout is stored as additional attributes
347 name/value pairs in the graph, node and edges. These attributes
348 are intended to be interpreted by subsequent write or render
349 commands.
350
351
352 graphHandle write fileHandle format ?dot|neato|circo|twopi|fdp|nop?
353
354 Write a graph to the open file represented by fileHandle in a
355 specific format. Possible formats are: "ps" "mif" "plain" "dot"
356 "gif" "ismap" If the layout hasn't been already done, then it
357 will be done as part of this operation using the same rules for
358 selecting the layout engine as for the layout command.
359
360
361 graphHandle rendergd gdHandle
362
363 Generates a rendering of a graph to a new or existing gifImage
364 structure (see gdTcl(1) ). Returns the gdHandle of the image.
365 If the layout hasn't been already done, then it will be done as
366 part of this operation using the same rules for selecting the
367 layout engine as for the layout command.
368
369
370 graphHandle render ?canvas ?dot|neato|circo|twopi|fdp|nop??
371
372 If no canvas argument is provided then render returns a string
373 of commands which, when evaluated, will render the graph to a Tk
374 canvas whose canvasHandle is available in variable $c
375
376 If a canvas argument is provided then render produces a set of
377 commands for canvas instead of $c.
378
379 If the layout hasn't been already done, then it will be done as
380 part of this operation using the same rules for selecting the
381 layout engine as for the layout command.
382
383 #!/usr/local/bin/wish
384 package require Tcldot
385 set c [canvas .c]
386 pack $c
387 set g [dotnew digraph rankdir LR]
388 $g setnodeattribute style filled color white
389 [$g addnode Hello] addedge [$g addnode World!]
390 $g layout
391 if {[info exists debug]} {
392 puts [$g render] ;# see what render produces
393 }
394 eval [$g render]
395
396
397 Render generates a series of canvas commands for each graph ele‐
398 ment, for example a node typically consist of two items on the
399 canvas, one for the shape and the other for the label. The can‐
400 vas items are automatically tagged (See canvas(n) ) by the com‐
401 mands generated by render. The tags take one of two forms: text
402 items are tagged with 0<handle> and shapes and lines are ren‐
403 dered with 1<handle>.
404
405 The tagging can be used to recognize when a user wants to inter‐
406 act with a graph element using the mouse. See the script in ex‐
407 amples/disp of the tcldot distribution for a demonstration of
408 this facility.
409
410
412 Still batch-oriented. It would be nice if the layout was maintained
413 incrementally. (The intent is to address this limitation in
414 graphviz_2_0.)
415
416
418 John Ellson (ellson@graphviz.org)
419
420
422 John Ousterhout, of course, for tcl and tk. Steven North and Elefthe‐
423 rios Koutsofios for dot. Karl Lehenbauer and Mark Diekhans of NeoSoft
424 for the handles.c code which was derived from tclXhandles.c. Tom
425 Boutell of the Quest Center at Cold Spring Harbor Labs for the gif
426 drawing routines. Spencer Thomas of the University of Michigan for
427 gdTcl.c. Dayatra Shands for coding much of the initial implementation
428 of tcldot.
429
430
432 graph, tcl, tk, dot, neato.
433
434
435
436 Tcl Extensions tcldot(3tcl)