NAME

Module::Dependency::Grapher - 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::makeSvg( $kind, $seeds, $filename, $options );

As makeImage() but does it in SVG. 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 (and related) options, 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; if set to 'return' then the imagemap text is the return value of makeHtml() so that the caller can process the string further.

An imagemap looks like this example, but you can change the href attributes using the HrefFormat option (see below) so that they match what your CGI program is expecting.

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

If you want to totally change the format of each 'area' element see the ImageMapCode option below.

Note that the href attributes are deliberately left empty, for users of the 'return' method to easily post-process the string. 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.

See the bundled 'cgidepend.plx' CGI program to see a use for this imagemap.

ImageMapCode

Used by makeHtml() only - must be a code reference. Called once for each 'area' required. The first argument is the package name that the 'area' corresponds to, 'Foo::Bar' or 'baz.pl' for example. The second argument is the current HrefFormat setting, but you may ignore that, seeing as you're going to be writing the entire element. The default coderef creates the 'area' elements as shown above and respects the HrefFormat option.

HrefFormat

Used by makeHtml() and makeSvg() only - default is ''. A sprintf() formatting string used to format the 'href' attribute in EACH 'area' element of the imagemap, or the href of the anchors in SVG output. E.g. '?myparam=%s' would create an href of '?myparam=Foo'.

If empty (as is the default) then you get no clickable links in the SVG output.

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. If you want to use the makeSvg() method you'll need the SVG module. 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 6632 2006-07-11 14:00:38Z timbo $