NAME
    GraphViz - Interface to the GraphViz graphing tool

SYNOPSIS
      use GraphViz;

      my $g = GraphViz->new();

      $g->add_node('London');
      $g->add_node('Paris', label => 'City of\nlurve');
      $g->add_node('New York');

      $g->add_edge('London' => 'Paris');
      $g->add_edge('London' => 'New York', label => 'Far');
      $g->add_edge('Paris' => 'London');

      print $g->as_png;

DESCRIPTION
    This module provides an interface to layout and image generation of
    directed and undirected graphs in a variety of formats (PostScript, PNG,
    etc.) using the "dot", "neato" and "twopi" programs from the GraphViz
    project (http://www.graphviz.org/ or
    http://www.research.att.com/sw/tools/graphviz/).

  What is a graph?
    A (undirected) graph is a collection of nodes linked together with
    edges.

    A directed graph is the same as a graph, but the edges have a direction.

  What is GraphViz?
    This module is an interface to the GraphViz toolset
    (http://www.graphviz.org/). The GraphViz tools provide automatic graph
    layout and drawing. This module simplifies the creation of graphs and
    hides some of the complexity of the GraphViz module.

    Laying out graphs in an aesthetically-pleasing way is a hard problem -
    there may be multiple ways to lay out the same graph, each with their
    own quirks. GraphViz luckily takes part of this hard problem and does a
    pretty good job in a couple of seconds for most graphs.

  Why should I use this module?
    Observation aids comprehension. That is a fancy way of expressing that
    popular faux-Chinese proverb: "a picture is worth a thousand words".

    Text is not always the best way to represent anything and everything to
    do with a computer programs. Pictures and images are easier to
    assimilate than text. The ability to show a particular thing graphically
    can aid a great deal in comprehending what that thing really represents.

    Diagrams are computationally efficient, because information can be
    indexed by location; they group related information in the same area.
    They also allow relations to be expressed between elements without
    labeling the elements.

    A friend of mine used this to his advantage when trying to remember
    important dates in computer history. Instead of sitting down and trying
    to remember everything, he printed over a hundred posters (each with a
    date and event) and plastered these throughout his house. His spatial
    memory is still so good that asked last week (more than a year since the
    experiment) when Lisp was invented, he replied that it was upstairs,
    around the corner from the toilet, so must have been around 1958.

    Spreadsheets are also a wonderfully simple graphical representation of
    computational models.

  Applications
    Bundled with this module are several modules to help graph data
    structures (GraphViz::Data::Dumper), XML (GraphViz::XML), and
    Parse::RecDescent, Parse::Yapp, and yacc grammars
    (GraphViz::Parse::RecDescent, GraphViz::Parse::Yapp, and
    GraphViz::Parse::Yacc).

    Note that Marcel Grunauer has released some modules on CPAN to graph
    various other structures. See GraphViz::DBI and GraphViz::ISA for
    example.

    brian d foy has written an article about Devel::GraphVizProf for Dr.
    Dobb's Journal:
    http://www.ddj.com/columns/perl/2001/0104pl002/0104pl002.htm

  Award winning!
    I presented a paper and talk on "Graphing Perl" using GraphViz at the
    3rd German Perl Workshop and received the "Best Knowledge Transfer"
    prize.

        Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf
      Slides: http://www.astray.com/graphing_perl/

METHODS
  new
    This is the constructor. It accepts several attributes.

    The most two important attributes are 'layout' and 'directed'. The
    'layout' attribute determines which layout algorithm GraphViz.pm will
    use. Possible values are: 'dot' (the default GraphViz layout for
    directed graph layouts), 'neato' (for undirected graph layouts - spring
    model) or 'twopi' (for undirected graph layouts - circular).

    The 'directed' attribute, which defaults to 1 (true) specifies directed
    (edges have arrows) graphs. Setting this to zero produces undirected
    graphs (edges do not have arrows).

    Another attribute 'rankdir' controls the direction the nodes are linked
    together. If true it will do left->right linking rather than the default
    up-down linking.

    The 'width' and 'height' attributes control the size of the bounding box
    of the drawing in inches. This is more useful for PostScript output as
    for raster graphic (such as PNG) the pixel dimensions can not be set,
    although there are generally 96 pixels per inch.

    The 'pagewidth' and 'pageheight' attributes set the PostScript
    pagination size in inches. That is, if the image is larger than the page
    then the resulting PostScript image is a sequence of pages that can be
    tiled or assembled into a mosaic of the full image. (This only works for
    PostScript output).

      my $g = GraphViz->new();
      my $g = GraphViz->new(directed => 0);
      my $g = GraphViz->new(layout => 'neato');
      my $g = GraphViz->new(rankdir  => 1);
      my $g = GraphViz->new(width => 8.5, height => 11);
      my $g = GraphViz->new(width => 30, height => 20,
                            pagewidth => 8.5, pageheight => 11);

    The 'concentrate' attribute controls enables an edge merging technique
    to reduce clutter in dense layouts of directed graphs. The default is
    not to merge edges.

    For undirected graphs, the 'random_start' attribute requests an initial
    random placement for the graph, which may give a better result. The
    default is not random.

    For undirected graphs, the 'epsilon' attribute decides how long the
    graph solver tries before finding a graph layout. Lower numbers allow
    the solver to fun longer and potentially give a better layout. Larger
    values can decrease the running time but with a reduction in layout
    quality. The default is 0.1.

    The 'no_overlap' overlap option, if set, tells the graph solver to not
    overlap the nodes.

    The 'bgcolor' option sets the background colour. A colour value may be
    "h,s,v" (hue, saturation, brightness) floating point numbers between 0
    and 1, or an X11 color name such as 'white', 'black', 'red', 'green',
    'blue', 'yellow', 'magenta', 'cyan', or 'burlywood'.

    The 'node', 'edge' and 'graph' attributes allow you to specify global
    node, edge and graph attributes (in addition to those controlled by the
    special attributes described above). The value should be a hash
    reference containing the corresponding key-value pairs. For example, to
    make all nodes box-shaped (unless explicity given another shape):

      my $g = GraphViz->new(node => {shape => 'box'});

  add_node
    A graph consists of at least one node. All nodes have a name attached
    which uniquely represents that node.

    The add_node method creates a new node and optionally assigns it
    attributes.

    The simplest form is used when no attributes are required, in which the
    string represents the name of the node:

      $g->add_node('Paris');

    Various attributes are possible: "label" provides a label for the node
    (the label defaults to the name if none is specified). The label can
    contain embedded newlines with '\n', as well as '\c', '\l', '\r' for
    center, left, and right justified lines:

      $g->add_node('Paris', label => 'City of\nlurve');

    Attributes need not all be specified in the one line: successive
    declarations of the same node have a cumulative effect, in that any
    later attributes are just added to the existing ones. For example, the
    following two lines are equivalent to the one above:

      $g->add_node('Paris');
      $g->add_node('Paris', label => 'City of\nlurve');

    Note that multiple attributes can be specified. Other attributes
    include:

    height, width
        sets the minimum height or width

    shape
        sets the node shape. This can be one of: 'record', 'plaintext',
        'ellipse', 'circle', 'egg', 'triangle', 'box', 'diamond',
        'trapezium', 'parallelogram', 'house', 'hexagon', 'octagon'

    fontsize
        sets the label size in points

    fontname
        sets the label font family name

    color
        sets the outline colour, and the default fill colour if the 'style'
        is 'filled' and 'fillcolor' is not specified

        A colour value may be "h,s,v" (hue, saturation, brightness) floating
        point numbers between 0 and 1, or an X11 color name such as 'white',
        'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or
        'burlywood'

    fillcolor
        sets the fill colour when the style is 'filled'. If not specified,
        the 'fillcolor' when the 'style' is 'filled' defaults to be the same
        as the outline color

    style
        sets the style of the node. Can be one of: 'filled', 'solid',
        'dashed', 'dotted', 'bold', 'invis'

    URL sets the url for the node in image map and PostScript files. The
        string '\N' value will be replaced by the node name. In PostScript
        files, URL information is embedded in such a way that Acrobat
        Distiller creates PDF files with active hyperlinks

    If you wish to add an anonymous node, that is a node for which you do
    not wish to generate a name, you may use the following form, where the
    GraphViz module generates a name and returns it for you. You may then
    use this name later on to refer to this node:

      my $nodename = $g->add_node('label' => 'Roman city');

    Nodes can be clustered together with the "cluster" attribute, which is
    drawn by having a labelled rectangle around all the nodes in a cluster.
    An empty string means not clustered.

      $g->add_node('London', cluster => 'Europe');
      $g->add_node('Amsterdam', cluster => 'Europe');

    Clusters can also take a hashref so that you can set attributes:

      my $eurocluster = {
        name      =>'Europe',
        style     =>'filled',
        fillcolor =>'lightgray',
        fontname  =>'arial',
        fontsize  =>'12',
      };
      $g->add_node('London', cluster => $eurocluster, @default_attrs);

    Nodes can be located in the same rank (that is, at the same level in the
    graph) with the "rank" attribute. Nodes with the same rank value are
    ranked together.

      $g->add_node('Paris', rank => 'top');
      $g->add_node('Boston', rank => 'top');

    Also, nodes can consist of multiple parts (known as ports). This is
    implemented by passing an array reference as the label, and the parts
    are displayed as a label. GraphViz has a much more complete port system,
    this is just a simple interface to it. See the 'from_port' and 'to_port'
    attributes of add_edge:

      $g->add_node('London', label => ['Heathrow', 'Gatwick']);

  add_edge
    Edges are directed (or undirected) links between nodes. This method
    creates a new edge between two nodes and optionally assigns it
    attributes.

    The simplest form is when now attributes are required, in which case the
    nodes from and to which the edge should be are specified. This works
    well visually in the program code:

      $g->add_edge('London' => 'Paris');

    Attributes such as 'label' can also be used. This specifies a label for
    the edge. The label can contain embedded newlines with '\n', as well as
    '\c', '\l', '\r' for center, left, and right justified lines.

      $g->add_edge('London' => 'New York', label => 'Far');

    Note that multiple attributes can be specified. Other attributes
    include:

    minlen
        sets an integer factor that applies to the edge length (ranks for
        normal edges, or minimum node separation for flat edges)

    weight
        sets the integer cost of the edge. Values greater than 1 tend to
        shorten the edge. Weight 0 flat edges are ignored for ordering nodes

    fontsize
        sets the label type size in points

    fontname
        sets the label font family name

    fontcolor
        sets the label text colour

    color
        sets the line colour for the edge

        A colour value may be "h,s,v" (hue, saturation, brightness) floating
        point numbers between 0 and 1, or an X11 color name such as 'white',
        'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or
        'burlywood'

    style
        sets the style of the node. Can be one of: 'filled', 'solid',
        'dashed', 'dotted', 'bold', 'invis'

    dir sets the arrow direction. Can be one of: 'forward', 'back', 'both',
        'none'

    tailclip, headclip
        when set to false disables endpoint shape clipping

    arrowhead, arrowtail
        sets the type for the arrow head or tail. Can be one of: 'none',
        'normal', 'inv', 'dot', 'odot', 'invdot', 'invodot.'

    arrowsize
        sets the arrow size: (norm_length=10,norm_width=5,
        inv_length=6,inv_width=7,dot_radius=2)

    headlabel, taillabel
        sets the text for port labels. Note that labelfontcolor,
        labelfontname, labelfontsize are also allowed

    labeldistance, port_label_distance
        sets the distance from the edge / port to the label. Also labelangle

    decorateP
        if set, draws a line from the edge to the label

    samehead, sametail
        if set aim edges having the same value to the same port, using the
        average landing point

    constraint
        if set to false causes an edge to be ignored for rank assignment

    Additionally, adding edges between ports of a node is done via the
    'from_port' and 'to_port' parameters, which currently takes in the
    offset of the port (ie 0, 1, 2...).

      $g->add_edge('London' => 'Paris', from_port => 0);

  as_canon, as_text, as_gif etc. methods
    There are a number of methods which generate input for dot / neato /
    twopi or output the graph in a variety of formats.

    Note that if you pass a filename, the data is written to that filename.
    If you pass a filehandle, the data will be streamed to the filehandle.
    If you pass a scalar reference, then the data will be stored in that
    scalar. If you pass it a code reference, then it is called with the data
    (note that the coderef may be called multiple times if the image is
    large). Otherwise, the data is returned:

    Win32 Note: you will probably want to binmode any filehandles you write
    the output to if you want your application to be portable to Win32.

      my $png_image = $g->as_png;
      # or
      $g->as_png("pretty.png"); # save image
      # or
      $g->as_png(\*STDOUT); # stream image to a filehandle
      # or
      #g->as_png(\$text); # save data in a scalar
      # or
      $g->as_png(sub { $png_image .= shift });

    as_canon
        The as_canon method returns the canonical dot / neato / twopi file
        which corresponds to the graph. It does not layout the graph - every
        other as_* method does.

          print $g->as_canon;

          # prints out something like:
          digraph test {
              node [    label = "\N" ];
              London [label=London];
              Paris [label="City of\nlurve"];
              New_York [label="New York"];
              London -> Paris;
              London -> New_York [label=Far];
              Paris -> London;
          }

    as_text
        The as_text method returns text which is a layed-out dot / neato /
        twopi format file.

          print $g->as_text;

          # prints out something like:
          digraph test {
              node [    label = "\N" ];
              graph [bb= "0,0,162,134"];
              London [label=London, pos="33,116", width="0.89", height="0.50"];
              Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
              New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
              London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
              London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
              Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
          }

    as_ps
        Returns a string which contains a layed-out PostScript-format file.

          print $g->as_ps;

    as_hpgl
        Returns a string which contains a layed-out HP pen plotter-format
        file.

          print $g->as_hpgl;

    as_pcl
        Returns a string which contains a layed-out Laserjet printer-format
        file.

          print $g->as_pcl;

    as_mif
        Returns a string which contains a layed-out FrameMaker
        graphics-format file.

          print $g->as_mif;

    as_pic
        Returns a string which contains a layed-out PIC-format file.

          print $g->as_pic;

    as_gd
        Returns a string which contains a layed-out GD-format file.

          print $g->as_gd;

    as_gd2
        Returns a string which contains a layed-out GD2-format file.

          print $g->as_gd2;

    as_gif
        Returns a string which contains a layed-out GIF-format file.

          print $g->as_gif;

    as_jpeg
        Returns a string which contains a layed-out JPEG-format file.

          print $g->as_jpeg;

    as_png
        Returns a string which contains a layed-out PNG-format file.

          print $g->as_png;
          $g->as_png("pretty.png"); # save image

    as_wbmp
        Returns a string which contains a layed-out Windows BMP-format file.

          print $g->as_wbmp;

    as_cmap
        Returns a string which contains a layed-out HTML client-side image
        map format file.

          print $g->as_cmap;

    as_ismap
        Returns a string which contains a layed-out old-style server-side
        image map format file.

          print $g->as_ismap;

    as_imap
        Returns a string which contains a layed-out HTML new-style
        server-side image map format file.

          print $g->as_imap;

    as_vrml
        Returns a string which contains a layed-out VRML-format file.

          print $g->as_vrml;

    as_vtx
        Returns a string which contains a layed-out VTX (Visual Thought)
        format file.

          print $g->as_vtx;

    as_mp
        Returns a string which contains a layed-out MetaPost-format file.

          print $g->as_mp;

    as_fig
        Returns a string which contains a layed-out FIG-format file.

          print $g->as_fig;

    as_svg
        Returns a string which contains a layed-out SVG-format file.

          print $g->as_svg;

    as_plain
        Returns a string which contains a layed-out simple-format file.

          print $g->as_plain;

NOTES
    Older versions of GraphViz used a slightly different syntax for node and
    edge adding (with hash references). The new format is slightly clearer,
    although for the moment we support both. Use the new, clear syntax,
    please.

SEE ALSO
    GraphViz::XML, GraphViz::Regex

AUTHOR
    Leon Brocard <acme@astray.com>

COPYRIGHT
    Copyright (C) 2000-4, Leon Brocard

    This module is free software; you can redistribute it or modify it under
    the same terms as Perl itself.

