


TCLDOT(N)                                               TCLDOT(N)


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  facili-
       ties  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 manip-
       ulation 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  com-
       mand 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,  list-
              edges, listnodes, listnodesrev, listsubgraphs, render, rendergd,
              queryattributes,    queryedgeattributes,    querynodeattributes,
              queryattributevalues,   queryedgeattributevalues,   querynodeat-
              tributevalues,   setattributes,   setedgeattributes,  setnodeat-
              tributes, showname, write.

       Node methods are:

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

       Edge methods are:




                         02 December 1996                       1





TCLDOT(N)                                               TCLDOT(N)


              delete,  listattributes,  listnodes,  queryattributes,  queryat-
              tributevalues, 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 arbitrar-
              ily  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 [dotread $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 arbitrar-
              ily invent and assign values  to  additional  attributes  beyond



                         02 December 1996                       2





TCLDOT(N)                                               TCLDOT(N)


              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 han-
              dles and variables are essential to tcldot's ability to  manipu-
              late  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 poten-
              tial 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 arbitrar-
              ily invent and assign values  to  additional  attributes  beyond
              these.


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



                         02 December 1996                       3





TCLDOT(N)                                               TCLDOT(N)


              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 sub-
              graph  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 nodeHan-
              dle  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




                         02 December 1996                       4





TCLDOT(N)                                               TCLDOT(N)


       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 con-
              nector "->" 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





                         02 December 1996                       5





TCLDOT(N)                                               TCLDOT(N)


       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 ?...?




                         02 December 1996                       6





TCLDOT(N)                                               TCLDOT(N)


       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 com-
              mand.


       graphHandle layout ?DOT|NEATO|CIRCO|TWOPI|FDP|NOP?

              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.


       graphHandle write fileHandle format ?DOT|NEATO|CIRCO|TWOPI|FDP|NOP?

              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.


       graphHandle render ?canvas ?DOT|NEATO??

              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.



                         02 December 1996                       7





TCLDOT(N)                                               TCLDOT(N)


                  #!/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 ele-
              ment,  for  example a node typically consist of two items on the
              canvas, one for the shape and the other for the label.  The can-
              vas  items are automatically tagged (See canvas(n) ) by the com-
              mands generated by render.  The tags take one of two forms: text
              items  are  tagged  with 0<handle> and shapes and lines are ren-
              dered with 1<handle>.

              The tagging can be used to recognize when a user wants to inter-
              act  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 Elefthe-
       rios 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.







                         02 December 1996                       8


