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

              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.



                               02 December 1996                      TCLDOT(N)
