UMLCLASS(1) User Contributed Perl Documentation UMLCLASS(1)NAMEumlclass.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
$ umlclass.pl--without-inherited-methods -o blah.png -r lib
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.)
Perl libraries that use Moose
Perl classes that inherit from Moose will have tons of "meta methods"
like "before", "after", "has", and "meta", which are not very
interesting while plotting the class diagram. So it's common practice
to specify the "--without-inherited-methods" option like this:
$ umlclass.pl--without-inherited-methods -o uml.png -r lib
If you also add "--moose-roles", extra edges will appear in the graph,
in an alternate color, representing the relationships between roles and
their consumers.
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.pl-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 # DO NOT DO THIS!
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"".
--dot path
Tell it where the graphviz "dot" program is
--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::"
--no-methods
Don't display method names in the output.
--no-inheritance
Don't show the inheritance relationships in the output. Not
terribly useful unless you are using "Moose" and asking for
"--moose-roles".
--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. If you specify
""-o foo.xmi"", the XMI model file will be generated. 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.
--moose-roles
If a package appears to be a Moose::Role, determine which other
packages consume that role, and add that information to the graph
in a different color from the inheritance hierarchy. Depending on
the particular input classes and your personal artistic tastes,
this may substantially alter the usefulness and/or cleanliness of
the resulting diagram. For large package hierarchies, it is
recommended to combine this with --no-inheritance.
--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.
--without-inherited-methods
Do not show methods from parent classes.
All inherited and imported methods will be excluded. Note that if a
method is overridden in the current subclass, it will still be
included even if it appears in one of its ancestors.
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.)
AUTHORS
Agent Zhang <agentzh@gmail.com>, Maxim Zenin <max@foggy.ru>
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.
perl v5.20.2 2013-01-27 UMLCLASS(1)
