The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
UML-Class-Simple-0.07
River stage zero No dependents
6 ++
/ umlclass.pl

NAME

umlclass.pl - Utility to generate UML class diagrams from Perl source or runtime

SYNOPSIS

    $ umlclass.pl -M Foo -o foo.png -p "^Foo::"

    $ umlclass.pl -o bar.gif -p "Bar::|Baz::" lib/Bar.pm lib/*/*.pm

    $ umlclass.pl -o blah.png -p Blah -r ./blib

DESCRIPTION

This is a simple command-line frontend for the UML::Class::Simple module.

I'll illustrate the usage of this tool via some real-world examples.

Draw Stevan's Moose

  $ umlclass.pl -M Moose -o samples/moose_small.png -p "^(Class::MOP|Moose::)" -s 4x8

This command will generate a simple class diagram in PNG format for the Moose module with classes having names matching the regex "^(Class::MOP|Moose::)". The image's width is 4 inches while its height is 8 inches.

We need the -M option here since umlclass.pl needs to preload Moose into the memory so as to inspect it at runtime.

The graphical output is given below:

(See also http://perlcabal.org/agent/images/moose_small.png.)

Yes, the image above looks very fuzzy since the whole stuff is huge. If you strip the -s option, then the resulting image will enlarge automatically:

  $ umlclass.pl -M Moose -o samples/moose_big.png -p "^(Class::MOP|Moose::)"

The image obtained is really really large, I won't show it here, but you can browse it in your favorite picture browser from http://perlcabal.org/agent/images/moose_big.png.

Before trying out these commands yourself, please make sure that you have Moose already installed. (It's also on CPAN, btw.)

Draw Alias's PPI

  $ umlclass.pl -M PPI -o samples/ppi_small.png -p "^PPI::" -s 10x10

(See also http://perlcabal.org/agent/images/ppi_small.png.)

Or the full-size version:

  $ umlclass -M PPI -o samples/ppi_big.png -p "^PPI::"

(See http://perlcabal.org/agent/images/ppi_big.png.)

BTW, PPI is a prerequisite of this module.

Draw FAST.pm from UML::Class::Simple's Test Suite

  $ umlclass.pl -M FAST -o samples/fast.png -s 5x10 -r t/FAST/lib

This is an example of drawing classes contained in Perl source files.

Draw Modules of Your Own

Suppose that you're a CPAN author too and want to produce a class diagram for all the classes contained in your lib/ directory. The following command can do all the hard work for you:

    $ umlclass.pl -o mylib.png -r lib

or just plot the packages in the specified .pm files:

    $ umlclass.pl -o a.png lib/foo.pm lib/bar/baz.pm

or even specify a pattern (in perl regex) to filter out the packages you want to draw:

    $ umlclass.pl -o a.png -p "^Foo::" lib/foo.pm

Quite handy, isn't it? ;-)

IMPORTANT ISSUES

Never feed plain module names to umlclass.pl, for intance,

  $ umlclass.pl Scalar::Defer

will lead you to the following error message:

  error: input file Scalar::Defer not found.

Use -M and -p options to achieve your goals:

  $ umlclass.pl -M Scalar::Defer -p "Scalar::Defer"

In this example, I must warn you that you may miss the packages which belong to Scalar::Defer but don't have "Scalar::Defer" in their names. I'm sorry for that. umlclass.pl is not that smart.

The safest ways to do this are

  1. Don't specify the -p regex option and generate a large image which shows every classes including CORE modules, figure out the appropriate class name pattern yourself, and rerun umlclass.pl with the right regex pattern.

  2. Grab the Scalar::Defer's tarball, and do something like this:

       $ umlclass.pl -r Scalar-Defer-0.07/lib

It's worth mentioning that when .pl or .pm files are passing as the command line arguments, only the classes defined in these files will be drawn. This is a feature. :)

For .pm files on your disk, simply pass them as the command line arguments. For instance:

   $ umlclass.pl -o bar.gif lib/Bar.pm lib/*/*.pm

or tell umlclass.pl to iterate through the directories for you:

   $ umlclass.pl -o blah.png -r ./lib

OPTIONS

--color color
-c color

Sets the node color. Defaults to #f1e1f4.

You can either specify RGB values like #rrggbb in hex form, or color names like "grey" and "red".

--exclude path
-E path

excludes modules that were installed to path from the drawing. multiple -E options are supported.

--help
-h

Shows the help message.

--include path
-I path

Draws only the classes that were installed to path in the drawing. multiple -I options are supported.

-M module

Preloads the module which contains the classes you want to depict. For example,

    $ umlclass.pl -M PPI -o ppi.png -p "^PPI::"

Multiple -M options are accepted. For instance:

    $ umlclass.pl -M Foo -M Bar::Baz -p "Class::"
--out outfile
-o outfile

Specifies the output file name. Note that the file extension will be honored. If you specify "-o foo.png", a PNG image named foo.png will be generated, and if you specify "-o foo.dot", the dot source file named foo.dot will be obtained. Likewise, "-o foo.yml" will lead to a YAML file holding the whole internal DOM data.

A typical usage is as follows:

    $ umlclass.pl -o foo.yml lib/Foo.pm

    # ...edit the foo.yml so as to adjust the class info
    # feed the updated foo.dot back
    $ umlclass.pl -o foo.dot foo.yml

    # ...edit the foo.dot so as to adjust the graphviz dot source
    # now feed the updated foo.dot back
    $ umlclass.pl -o foo.png foo.dot

You see, umlclass.pl allows you to control the behaviors at several different levels. I really like this freedom, since tools can't always do exactly what I want.

If no -o option was specified, a.png will be assumed.

--pattern regex
-p regex

Specifies the pattern (perl regex) used to filter out the class names to be drawn.

--public-only
-P

Shows public methods only.

--recursive
-r

Processes subdirectories of input directories recursively.

--size
-s <w>x<h>

Specifies the width and height of the resulting image. For example:

    -s 3.6x7

    --size 5x6

where the unit is inches instead of pixels.

TODO

  • If the user passes plain module names like "Foo::Bar", then its (and only its) ancestors and subclasses will be drawn. (This is suggested by Christopher Malon.)

AUTHOR

Agent Zhang <agentzh@gmail.com>

COPYRIGHT

Copyright 2006 by Agent Zhang. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as perl itself.

SEE ALSO

UML::Class::Simple.