Seth Woolley's Man Viewer

tcldot(n) - tcldot - graph manipulation in tcl - man n tcldot

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

TCLDOT(N)                                                            TCLDOT(N)



NAME
       tcldot - graph manipulation in(1,8) 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(7,n,1 builtins) of commands to control
       those facilities.  tcldot converts dot and neato from batch  processing
       tools to an interpreted and, if(3,n) needed, interactive set(7,n,1 builtins) 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(1,8) detail below, but in(1,8) summary:

       Graph methods are:

              addedge, addnode, addsubgraph, countedges,  countnodes,  layout,
              listattributes,  listedgeattributes,  listnodeattributes,  list-
              edges,  listnodes,  listsubgraphs,  render,  rendergd,  queryat-
              tributes,   queryedgeattributes,  querynodeattributes,  queryat-
              tributevalues, queryedgeattributevalues,  querynodeattributeval-
              ues,  setattributes, setedgeattributes, setnodeattributes, show-
              name, write.

       Node methods are:

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

       Edge methods are:

              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(2,8) an arbitrary number of  attribute  name/value  pairs
              for  the  graph.  Certain special graph attributes and permitted
              values are described in(1,8) 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(7,n,1 builtins) g [dotnew digraph rankdir LR]


       dotread fileHandle

              reads in(1,8) a dot-language description of a graph from a previously
              opened  file(1,n)  identified by the fileHandle.  The command returns
              the graphHandle of the newly read(2,n,1 builtins) graph.  e.g.

                  set(7,n,1 builtins) f [open(2,3,n) test.dot r]
                  set(7,n,1 builtins) g [dotread $f]


       dotstring string(3,n)

              reads in(1,8) a dot-language  description  of  a  graph  from  a  Tcl
              string(3,n);  The  command  returns the graphHandle of the newly read(2,n,1 builtins)
              graph.  e.g.

                  set(7,n,1 builtins) g [dotread $dotsyntaxstring]


       graphHandle addnode ?nodeName? ?attributeName attributeValue? ?...?

              creates a new node in(1,8) the graph whose handle is graphHandle  and
              returns  its nodeHandle.  The handle of a node is a string(3,n) 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(1,8) dot(1), but the programmer can arbitrar-
              ily invent and assign values  to  additional  attributes  beyond
              these.  e.g.

                  set(7,n,1 builtins) n [$g addnode "N" label "Top\nNode" shape triangle eggs easyover]

              A  possible  cause  of  confusion  in(1,8)  tcldot is the distinction
              between handles, names, labels, and variables.  The  distinction
              is  primarily in(1,8) 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(1,8) 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(3,n) representation of the handle, if(3,n) a  label
              is not specified then it defaults to the name.


       graphHandle  addedge  tailNode  headNode ?attributeName attributeValue?
       ?...?

              creates  a new edge in(1,8) 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(7,n,1 builtins) n [$g addnode]
                  set(7,n,1 builtins) 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(3,n) 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(1,8) dot(1), but the programmer can arbitrar-
              ily  invent  and  assign  values to additional attributes beyond
              these.


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

              creates a new subgraph in(1,8) 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(1,8)  dot(1),
              but  the  programmer can arbitrarily invent and assign values to
              additional attributes beyond these.  e.g.

                  set(7,n,1 builtins) sg [$g addsubgraph dinglefactor 6]

              Clusters, as described in(1,8) 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(7,n,1 builtins) 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(1,8) which this is drawn is the graph in(1,8) 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(1,8) 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(1,8) the the deletion of all subtending  edges
              on  that node.  Deletion of a graph also results in(1,8) 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(1,8) the graph.


       graphHandle listedges

       graphHandle listnodes

       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(3,n) found, or an error(8,n) if(3,n) 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

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

       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?

              Annotate the graph with layout information.  This commands takes
              an abstract graph add  shape  and  position  information  to  it
              according  to  dot's or neato's rules of eye-pleasing graph lay-
              out. If the layout engine is unspecified then it defaults to DOT
              for  directed  graphs,  and  NEATO otherwise.  The result of the
              layout is stored as additional attributes  name/value  pairs  in(1,8)
              the  graph, node and edges.  These attributes are intended to be
              interpreted by subsequent write(1,2) or render commands.


       graphHandle write(1,2) fileHandle format ?DOT|NEATO?

              Write a graph to the open(2,3,n) file(1,n) represented by  fileHandle  in(1,8)  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(3,n)
              of commands which, when evaluated, will render the graph to a Tk
              canvas whose canvasHandle is available in(1,8) variable $c

              If  a  canvas argument is provided then render produces a set(7,n,1 builtins) 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.

                  #!/usr/local/bin/wish
                  package require Tcldot
                  set(7,n,1 builtins) c [canvas .c]
                  pack(3,n,n pack-old) $c
                  set(7,n,1 builtins) g [dotnew digraph rankdir LR]
                  $g setnodeattribute style filled color white
                  [$g addnode Hello] addedge [$g addnode World!]
                  $g layout
                  if(3,n) {[info(1,5,n) exists debug]} {
                      puts(3,n) [$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(1,8)
              examples/disp of the tcldot distribution for a demonstration  of
              this facility.


BUGS
       Still  batch-oriented.   It  would be nice(1,2) if(3,n) the layout was maintained
       incrementally.   (The  intent  is  to  address   this   limitation   in(1,8)
       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                      TCLDOT(N)

References for this manual (incoming links)