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
20       directed graph facilities of dot(1), and the undirected  graph  facili‐
21       ties  of  neato(1),  into tcl and provides a set of commands to control
22       those facilities.  tcldot converts dot and neato from batch  processing
23       tools to an interpreted and, if needed, interactive set of graph manip‐
24       ulation 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,"
68              "digraph,"  "graphstrict,"  or  "digraphstrict."   (In  digraphs
69              edges have a direction from tail to  head.  "Strict"  graphs  or
70              digraphs  collapse multiple edges between the same pair of nodes
71              into a 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 [dotread $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
118              between  handles, names, labels, and variables.  The distinction
119              is primarily in who owns them.  Handles are owned by tcldot  and
120              are  guaranteed  to  be  unique  within one interpreter session.
121              Typically handles are assigned to variables, like "n" above, for
122              manipulation  within  a  tcl script.  Variables are owned by the
123              programmer.  Names are owned by the application  that  is  using
124              the 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
130              defaults  to the string representation of the handle, if a label
131              is 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
170              defaults  to it's graphHandle.  There can be an arbitrary number
171              of 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
192              attribute 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
237              appropriate.
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
324              attribute 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
342              according to the layout engine's  rules  of  eye-pleasing  graph
343              layout.  If the layout engine is unspecified then it defaults to
344              dot for directed graphs, and neato otherwise.  If the nop engine
345              is  specified  then  layout  infomation  from the input graph is
346              used.   The  result  of  the  layout  is  stored  as  additional
347              attributes name/value pairs in the graph, node and edges.  These
348              attributes are intended to be interpreted by subsequent write or
349              render 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"  "hpgl"
356              "plain"  "dot"  "gif"  "ismap" If the layout hasn't been already
357              done, then it will be done as part of this operation  using  the
358              same  rules  for  selecting  the layout engine as for the layout
359              command.
360
361
362       graphHandle rendergd gdHandle
363
364              Generates a rendering of a graph to a new or  existing  gifImage
365              structure  (see  gdTcl(1) ).  Returns the gdHandle of the image.
366              If the layout hasn't been already done, then it will be done  as
367              part  of  this  operation using the same rules for selecting the
368              layout engine as for the layout command.
369
370
371       graphHandle render ?canvas ?dot|neato|circo|twopi|fdp|nop??
372
373              If no canvas argument is provided then render returns  a  string
374              of commands which, when evaluated, will render the graph to a Tk
375              canvas whose canvasHandle is available in variable $c
376
377              If a canvas argument is provided then render produces a  set  of
378              commands for canvas instead of $c.
379
380              If  the layout hasn't been already done, then it will be done as
381              part of this operation using the same rules  for  selecting  the
382              layout engine as for the layout command.
383
384                  #!/usr/local/bin/wish
385                  package require Tcldot
386                  set c [canvas .c]
387                  pack $c
388                  set g [dotnew digraph rankdir LR]
389                  $g setnodeattribute style filled color white
390                  [$g addnode Hello] addedge [$g addnode World!]
391                  $g layout
392                  if {[info exists debug]} {
393                      puts [$g render]         ;# see what render produces
394                  }
395                  eval [$g render]
396
397
398              Render generates a series of canvas commands for each graph ele‐
399              ment, for example a node typically consist of two items  on  the
400              canvas, one for the shape and the other for the label.  The can‐
401              vas items are automatically tagged (See canvas(n) ) by the  com‐
402              mands generated by render.  The tags take one of two forms: text
403              items are tagged with 0<handle> and shapes and  lines  are  ren‐
404              dered with 1<handle>.
405
406              The tagging can be used to recognize when a user wants to inter‐
407              act with a graph element using the mouse.   See  the  script  in
408              examples/disp  of the tcldot distribution for a demonstration of
409              this facility.
410
411

BUGS

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

AUTHOR

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

ACKNOWLEDGEMENTS

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

KEYWORDS

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