Provided by: libgraphviz-perl_2.24-1_all bug

NAME

       GraphViz - Interface to AT&T's GraphViz. Deprecated. See GraphViz2

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", "twopi", "circo" and "fdp"  programs from the Graphviz project
       (http://www.graphviz.org/ or http://www.research.att.com/sw/tools/graphviz/).

       GraphViz is deprecated in favour of GraphViz2.

Installation

       Of course you need to install AT&T's Graphviz before using this module.  See
       <http://www.graphviz.org/Download.php>.

       You are strongly advised to download the stable version of Graphviz, because the
       development snapshots (click on 'Source code'), are sometimes non-functional.

       Install GraphViz as you would for any "Perl" module:

       Run:

               cpanm GraphViz

               Note: cpanm ships in App::cpanminus. See also App::perlbrew.

       or run:

               sudo cpan GraphViz

       or unpack the distro, and then either:

               perl Build.PL
               ./Build
               ./Build test
               sudo ./Build install

       or:

               perl Makefile.PL
               make (or dmake or nmake)
               make test
               make install

Overview

   Modules in this distro
       o GraphViz
       o GraphViz::No
       o GraphViz::Small
       o GraphViz::Regex
       o GraphViz::XML
       o GraphViz::Data::Grapher
       o GraphViz::Parse::RecDescent
       o GraphViz::Parse::Yacc
       o GraphViz::Parse::Yapp

   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.

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

       The most two important attributes are 'layout' and 'directed'.

       layout
           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

           twopi
               For undirected graph layouts - radial

           circo
               For undirected graph layouts - circular

           fdp For undirected graph layouts - force directed spring model

       directed
           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).

       rankdir
           Another attribute 'rankdir' controls the direction in which the nodes are linked
           together. The default is 'TB' (arrows from top to bottom). Other legal values are 'BT'
           (bottom->top), 'LR' (left->right) and 'RL' (right->left).

       width, height
           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.

       pagewidth, pageheight
           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).

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

       orientation
           This option controls the angle, in degrees, used to rotate polygon node shapes.

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

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

       overlap
           The 'overlap' option allows you to set layout behavior for graph nodes that overlap.
           (From GraphViz documentation:)

           Determines if and how node overlaps should be removed.

           true
               (the default) overlaps are retained.

           scale
               overlaps are removed by uniformly scaling in x and y.

           false
               If the value converts to "false", node overlaps are removed by a Voronoi-based
               technique.

           scalexy
               x and y are separately scaled to remove overlaps.

           orthoxy, orthxy
               If the value is "orthoxy" or "orthoyx", overlaps are moved by optimizing two
               constraint problems, one for the x axis and one for the y. The suffix indicates
               which axis is processed first.

               NOTE: The methods related to "orthoxy" and "orthoyx" are still evolving. The
               semantics of these may change, or these methods may disappear altogether.

           compress
               If the value is "compress", the layout will be scaled down as much as possible
               without introducing any overlaps.

           Except for the Voronoi method, all of these transforms preserve the orthogonal
           ordering of the original layout. That is, if the x coordinates of two nodes are
           originally the same, they will remain the same, and if the x coordinate of one node is
           originally less than the x coordinate of another, this relation will still hold in the
           transformed layout. The similar properties hold for the y coordinates.

       no_overlap
           The 'no_overlap' overlap option, if set, tells the graph solver to not overlap the
           nodes.  Deprecated,  Use 'overlap' => 'false'.

       ratio
           The 'ratio' option sets the aspect ratio (drawing height/drawing width) for the
           drawing. Note that this is adjusted before the size attribute constraints are
           enforced.  Default value is "fill".

           numeric
               If ratio is numeric, it is taken as the desired aspect ratio. Then, if the actual
               aspect ratio is less than the desired ratio, the drawing height is scaled up to
               achieve the desired ratio; if the actual ratio is greater than that desired ratio,
               the drawing width is scaled up.

           fill
               If ratio = "fill" and the size attribute is set, node positions are scaled,
               separately in both x and y, so that the final drawing exactly fills the specified
               size.

           compress
               If ratio = "compress" and the size attribute is set, dot attempts to compress the
               initial layout to fit in the given size. This achieves a tighter packing of nodes
               but reduces the balance and symmetry. This feature only works in dot.

           expand
               If ratio = "expand" the size attribute is set, and both the width and the height
               of the graph are less than the value in size, node positions are scaled uniformly
               until at least one dimension fits size exactly. Note that this is distinct from
               using size as the desired size, as here the drawing is expanded before edges are
               generated and all node and text sizes remain unchanged.

           auto
               If ratio = "auto" the page attribute is set and the graph cannot be drawn on a
               single page, then size is set to an ``ideal'' value. In particular, the size in a
               given dimension will be the smallest integral multiple of the page size in that
               dimension which is at least half the current size. The two dimensions are then
               scaled independently to the new size. This feature only works in dot.

       bgcolor
           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'.

       name
           The 'name' option sets name of the graph. This option is useful in few situations,
           like client side image map generation, see cmapx.  By default 'test' is used.

       node,edge,graph
           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 explicitly 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

       decorate
           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 / circo / fdp
       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_debug
           The as_debug method returns the dot file which we pass to GraphViz. It does not lay
           out the graph. This is mostly useful for debugging.

             print $g->as_debug;

       as_canon
           The as_canon method returns the canonical dot / neato / twopi / circo / fdp  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 / circo / fdp
           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  (deprecated)
           Returns a string which contains a layed-out HTML client-side image map format file.
           Use as_cmapx instead.

             print $g->as_cmap;

       as_cmapx
           Returns a string which contains a layed-out HTML HTML/X client-side image map format
           file. Name and id attributes of map element are set to name of the graph.

             print $g->as_cmapx;

       as_ismap (deprecated)
           Returns a string which contains a layed-out old-style server-side image map format
           file.  Use as_imap instead.

             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_vdx
           Returns a string which contains a VDX-format (Microsoft Visio) file.

             print $g->as_vdx;

       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_svgz
           Returns a string which contains a layed-out SVG-format file that is compressed.

             print $g->as_svgz;

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

             print $g->as_plain;

FAQ

   Why do I get error messages like the following?
               Error: <stdin>:1: syntax error near line 1
               context: digraph >>>  Graph <<<  {

       Graphviz reserves some words as keywords, meaning they can't be used as an ID, e.g. for
       the name of the graph.  So, don't do this:

               strict graph graph{...}
               strict graph Graph{...}
               strict graph strict{...}
               etc...

       Likewise for non-strict graphs, and digraphs. You can however add double-quotes around
       such reserved words:

               strict graph "graph"{...}

       Even better, use a more meaningful name for your graph...

       The keywords are: node, edge, graph, digraph, subgraph and strict. Compass points are not
       keywords.

       See keywords <http://www.graphviz.org/content/dot-language> in the discussion of the
       syntax of DOT for details.

   How do you handle XXE within XML?
       Due to security risks with XXE in XML, Graphviz does not support XML that contains XXE.
       Thus it automatically prevents external entities being parsed by using the no_xxe option
       in XML::Twig when calling XML::Twig -> new(). And for this reason also the pre-reqs in
       Makefile.PL specify XML::Twig V 3.52.

       See <https://metacpan.org/pod/release/MIROD/XML-Twig-3.52/Twig.pm#no_xxe>

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 is deprecated in favour of GraphViz2.

Machine-Readable Change Log

       The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Repository

       <https://github.com/ronsavage/GraphViz>

AUTHOR

       Leon Brocard: <acme@astray.com>.

       Current maintainer: Ron Savage <ron@savage.net.au>.

       My homepage: <http://savage.net.au/>.

COPYRIGHT

       Copyright (C) 2000-4, Leon Brocard

LICENSE

       This module is free software; you can redistribute it or modify it under the Perl License,
       a copy of which is available at <http://dev.perl.org/licenses/>.