1tcldot(3tcl)                                                      tcldot(3tcl)
2
3
4

NAME

6       tcldot - graph manipulation in tcl
7
8

SYNOPSIS

10       #!/usr/local/bin/tclsh
11       package require Tcldot
12
13

USAGE

15       Requires the dynamic loading facilities of tcl7.6 or later.
16
17

INTRODUCTION

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

COMMANDS

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

BUGS

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

AUTHOR

418       John Ellson (ellson@graphviz.org)
419
420

ACKNOWLEDGEMENTS

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

KEYWORDS

432       graph, tcl, tk, dot, neato.
433
434
435
436                                Tcl Extensions                    tcldot(3tcl)
Impressum