NAME

Module::Dependency::Graph - creates visual dependency charts and accessible text versions

SYNOPSIS

use Module::Dependency::Grapher;
Module::Dependency::Grapher::setIndex( '/var/tmp/dependence/unified.dat' );
Module::Dependency::Grapher::makeImage( 'both', ['Foo::Bar', 'Foo::Baz'], '/home/www/foodep.png', {Format => 'png'} );
Module::Dependency::Grapher::makePs( 'both', ['Foo::Bar', 'Foo::Baz'], '/home/www/foodep.eps' );
Module::Dependency::Grapher::makeText( 'both', ['Foo::Bar', 'Foo::Baz'], '/home/www/foodep.txt', {NoLegend => 1} );
Module::Dependency::Grapher::makeHtml( 'both', ['Foo::Bar', 'Foo::Baz'], '/home/www/foodep.ssi', {NoLegend => 1} );

DESCRIPTION

Module::Dependency::Grapher::setIndex( $filename );

This tells the module where the database is. It doesn't affect the other modules - they have their own setIndex routines. The default is /var/tmp/dependence/unified.dat

Module::Dependency::Grapher::makeImage( $kind, $seeds, $filename, $options );

Draws an image showing the dependency links between a set of items. The 'tree' of dependencies is started at the item or items named in the $seeds array reference. The code then links to all the parent and/or child dependencies of those seeds. And repeat for those items, etc.

$kind is 'parent', 'child' or 'both'. This parameter tells the code whether to plot (respectively) things that depend upon the seed items, things that the seed items depend upon, or both directions.

$seeds is a reference to an array of item names

$filename is the file to which the output should go. Use '-' for STDOUT. Clobbers existing files.

See below for the options. See README.EXAMPLES too.

Module::Dependency::Grapher::makePs( $kind, $seeds, $filename, $options );

As makeImage() but does it in PostScript or EPS. EPS is the default. See below for the options. See README.EXAMPLES too.

Module::Dependency::Grapher::makeText( $kind, $seeds, $filename, $options );

Creates a plain-text rendition of the dependency heirarchy. As it's only ASCII it can't plot the individual links between items, so it simplifies and presents only each level of the tree as a whole.

Parameters are as for makeImage()

See below for options. See README.EXAMPLES too.

Module::Dependency::Grapher::makeHtml( $kind, $seeds, $filename, $options );

Creates an HTML fragment rendition of the dependency heirarchy. As it's only text it can't plot the individual links between items, so it simplifies and presents only each level of the tree. Information comes out in a table, and the whole fragment uses CLASS attributes so that you can apply CSS to it. Typical fragment is:

<div class="MDGraph"><h2>Dependencies for all scripts</h2>
<h4>Grapher.pm 1.7 - Fri Jan 11 00:00:56 2002</h4>
Key:<br />Parent indicates parent dependencies<br />
	**** indicates the item(s) from which the relationships are drawn<br />
    Child are child dependencies<br />

<table class="MDGraphTable">
<tr><th>Kind</th><th>Items</th></tr>
<tr><td class="MDGraphSeed">****</td><td class="MDGraphSeed">x.pl, y.pl</td></tr>
<tr><td class="MDGraphChild">Child</td><td class="MDGraphChild">a, b, c</td></tr>
</table>
</div>

Parameters are as for makeImage().

See below for options - especially the ImageMap option, which allows this method to return an HTML client-side imagemap. See README.EXAMPLES too.

OPTIONS

Options are case-sensitive, and you pass them in as a hash reference, e.g.

Module::Dependency::Grapher::makeImage( $kind, $objlist, $IMGFILE, {Title => $title, Format => 'GIF'} );

These are the recognized options:

Title

Sets the title of the output to whatever string you want. Displayed at the top.

Format

The output image format - can be (case-insensitive) GIF, PNG, GD, or JPG - but some may not be available depending on how your local copy of libgd was compiled. You'll need to examine you local GD setup (PNG is pretty standard thesedays though) Default is PNG.

The makePs() method recognizes only 'EPS' or 'PS' as format options. Default is 'EPS'.

IncludeRegex

A regular expression use to filter the items displayed. If this is '::' for example then the output will only show dependencies that contain those characters.

ExcludeRegex

A regular expression use to filter the items displayed. If this is '::' for example then the output will not show dependencies that contain those characters.

NoLegend

If true, don't print the 'legend' box/text

NoVersion

If true, don't print the version/date line.

Colour

Used by makePs() only - if 1 it makes a colour image, if 0 it makes a greyscale image. Default is 1.

Font

sed by makePs() only. Set the font used in the drawing. Default is 'Helvetica'.

ImageMap

Used by makeHtml() only - if set to 'print' it will print a skeleton imagemap to the output file of this form:

<map name="dependence">
<!-- PACK a --><area href="" shape="rect" coords="217,110,229,122" alt="Root dependency tree on a" title="Root dependency tree on a">
<!-- PACK x.pl --><area href="" shape="rect" coords="17,110,44,122" alt="Root dependency tree on x.pl" title="Root dependency tree on x.pl">
</map>

Note that the href attributes are deliberately left empty so you need to go through the map and insert the right URL. The PACK comment at the start of each line is provided to tell you what the package or scriptname is. The imagemap corresponds to the image that _would_ be produced by makeImage() if it were given the same arguments.

If set to 'return' then makeHtml() will return this same imagemap string to the caller so that they can process it further. See the bundled 'cgidepend.plx' CGI program to see a use for this imagemap.

PREREQUISITES

If you want to use the makePs() method you'll need PostScript::Simple installed. If you want to use the makeImage() method you'll need GD installed. However, these modules are 'require'd as needed so you can quite happily use the makeText and makeHtml routines.

SEE ALSO

Module::Dependency and the README files.

VERSION

$Id: Grapher.pm,v 1.18 2002/05/19 19:09:40 piers Exp $