Provided by: libgv-tcl_2.40.1-2_amd64 bug

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  facilities  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
       manipulation 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 command 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,   listedges,   listnodes,   listnodesrev,
              listsubgraphs,    render,    rendergd,    queryattributes,     queryedgeattributes,
              querynodeattributes,         queryattributevalues,        queryedgeattributevalues,
              querynodeattributevalues,  setattributes,   setedgeattributes,   setnodeattributes,
              showname, write.

       Node methods are:

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

       Edge methods are:

              delete,   listattributes,   listnodes,    queryattributes,    queryattributevalues,
              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 arbitrarily 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 [dotstring $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 arbitrarily invent and
              assign values to additional attributes beyond 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 handles and  variables  are  essential  to  tcldot's
              ability to manipulate 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 potential 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  arbitrarily invent and assign values to additional attributes
              beyond these.

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

              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 subgraph 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 nodeHandle 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

       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 connector "->" 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 command.

       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|circo|twopi|fdp|nop??

              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.

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

              The  tagging  can  be  used to recognize when a user wants to interact 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 Eleftherios  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.

                                          Tcl Extensions                             tcldot(3tcl)