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
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 rerunumlclass.pl
with the right regex pattern.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.