Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

UML::Class::Simple
Render simple UML class diagrams, by loading the code

UML::Class::Simple - Render simple UML class diagrams, by loading the code


NAME

UML::Class::Simple - Render simple UML class diagrams, by loading the code


VERSION

This document describes UML::Class::Simple 0.09 released by April 10, 2007.


SYNOPSIS


    use UML::Class::Simple;

    # produce a class diagram for Alias's PPI

    # which has already installed to your perl:

    @classes = classes_from_runtime("PPI", qr/^PPI::/);

    $painter = UML::Class::Simple->new(\@classes);

    $painter->as_png('ppi.png');

    # produce a class diagram for your CPAN module on the disk

    @classes = classes_from_files(['lib/Foo.pm', 'lib/Foo/Bar.pm']);

    $painter = UML::Class::Simple->new(\@classes);

    # we can explicitly specify the image size

    $painter->size(5, 3.6); # in inches

    # ...and change the default title background color:

    $painter->node_color('#ffffff'); # defaults to '#f1e1f4'

    # only show public methods and properties

    $painter->public_only(1);

    $painter->as_png('my_module.png');


DESCRIPTION

UML::Class::Simple is a Perl CPAN module that generates UML class diagrams (PNG format, GIF format, or dot source) automatically from Perl 5 source or Perl 5 runtime.

Perl developers can use this module to obtain pretty class diagrams for arbitrary existing Perl class libraries (including modern perl OO modules based on Moose.pm), by only a single command. Companies can also use the resulting pictures to visualize the project hierarchy and embed them into their documentation.

The users no longer need to drag a mouse on the screen so as to draw figures themselves or provide any specs other than the source code of their own libraries that they want to depict. This module does all the jobs for them! :)

You know, I was really impressed by the outputs of the UML::Sequence manpage, so I decided to find something to (automatically) get pretty class diagrams too. The images from Autodia's Graphviz backend didn't quite fit my needs when I was making some slides for my presentations.

I think most of the time you just want to use the command-line utility umlclass.pl offered by this module (just like me). See the documentation of umlclass.pl for details.


SAMPLE OUTPUTS

PPI
http://perlcabal.org/agent/images/ppi_small.png

(See also samples/ppi_small.png in the distribution.)

Moose
http://perlcabal.org/agent/images/moose_small.png

(See also samples/moose_small.png in the distribution.)

FAST
http://perlcabal.org/agent/images/fast.png

(See also samples/fast.png in the distribution.)


SUBROUTINES

classes_from_runtime($module_to_load, $regex?)
classes_from_runtime(\@modules_to_load, $regex?)
Returns a list of class (or package) names by inspecting the perl runtime environment. $module_to_load is the main module name to load while $regex is a perl regex used to filter out interesting package names.

The second argument can be omitted.

classes_from_files($pmfile, $regex?)
classes_from_files(\@pmfiles, $regex?)
Returns a list of class (or package) names by scanning through the perl source files given in the first argument. $regex is used to filter out interesting package names.

The second argument can be omitted.

exclude_by_paths
Excludes package names via specifying one or more paths where the corresponding modules were installed into. For example:

    @classes = exclude_by_paths(\@classes, 'C:/perl/lib');

    @classes = exclude_by_paths(\@classes, '/home/foo', '/System/Library');

grep_by_paths
Filters out package names via specifying one or more paths where the corresponding modules were installed into. For instance:

    @classes = grep_by_paths(\@classes, '/home/malon', './blib/lib');

All these subroutines are exported by default.


METHODS

$obj->new( [@class_names] )
Create a new UML::Class::Simple instance with the specified class name list. This list can either be constructed manually or by the utility functions classes_from_runtime and classes_from_files.

$obj->as_png($filename?)
Generate PNG image file when $filename is given. It returns binary data when $filename is not given.

$obj->as_gif($filename?)
Similar to as_png, bug generate a GIF-format image.

$obj->as_dom()
Return the internal DOM tree used to generate dot and png. The tree's structure looks like this:

  {

    'classes' => [

                   {

                     'subclasses' => [],

                     'methods' => [],

                     'name' => 'PPI::Structure::List',

                     'properties' => []

                   },

                   {

                     'subclasses' => [

                                       'PPI::Structure::Block',

                                       'PPI::Structure::Condition',

                                       'PPI::Structure::Constructor',

                                       'PPI::Structure::ForLoop',

                                       'PPI::Structure::Unknown'

                                     ],

                     'methods' => [

                                    '_INSTANCE',

                                    '_set_finish',

                                    'braces',

                                    'content',

                                    'new',

                                    'refaddr',

                                    'start',

                                    'tokens'

                                  ],

                     'name' => 'PPI::Structure',

                     'properties' => []

                   },

                   ...

                ]

  }

You can adjust the data structure and feed it back to $obj via the set_dom method.

$obj->set_dom($dom)
Set the internal DOM structure to $obj. This will be used to generate the dot source and thus the PNG/GIF images.

$obj->as_dot()
Return the Graphviz dot source code generated by $obj.

$obj->set_dot($dot)
Set the dot source code used by $obj.


PROPERTIES

$obj->size($width, $height)
($width, $height) = $obj->size
Set/get the size of the output images, in inches.

$obj->public_only($bool)
$bool = $obj->public_only
When the public_only property is set to true, only public methods or properties are shown. It defaults to false.

$obj->node_color($color)
$color = $obj->node_color
Set/get the background color for the class nodes. It defaults to '#f1e1f4'.


INSTALLATION

Please download and intall a recent Graphviz release from its home:

http://www.graphviz.org/

UML::Class::Simple requires the HTML label feature which is only available on versions of Graphviz that are newer than mid-November 2003. In particular, it is not part of release 1.10.

Add Graphviz's bin/ path to your PATH environment. This module needs its dot utility.

Grab this module from the CPAN mirror near you and run the following commands:


    perl Makefile.PL

    make

    make test

    make install

For windows users, use nmake instead of make.

Note that it's recommended to use the cpan utility to install CPAN modules.


LIMITATIONS

  • It's pretty hard to distinguish perl methods from properties (actually they're both implemented by subs in perl). If you have any good thoughts on this issue, please drop me a line.

  • Only the inheritance relationships are shown in the images. I believe other subtle relations may mess up the Graphviz layouter. Hence the ``::Simple'' suffix in this module name.

  • Unlike Autodia, at this moment only Graphviz backend is provided.

  • There's no way to recognize real perl classes automatically. After all, Perl 5's classes are implemented by packages. I think Perl 6 will make my life much easier.

  • To prevent potential naming confusion. I'm using Perl's :: namespace separator in the class diagrams instead of dot (.) chosen by the UML standard. One can argue that following UML standards is more important since people in the same team may use different programming languages, but I think it's not the case for the majority (including myself) ;-)


TODO

  • Add more unit tests.

  • Add support for more image formats, such as as_ps, as_jpg, and etc.

  • Plot class relationships other than inheritance on the user's request.

  • Provide backends other than Graphviz.

Please send me your wish list by emails or preferably via the CPAN RT site. I'll add them here or even implement them promptly if I'm also interested in your (crazy) ideas. ;-)


BUGS

There must be some serious bugs lurking somewhere; if you found one, please report it to http://rt.cpan.org or contact the author directly.


ACKNOWLEDGEMENT

I must thank Adam Kennedy (Alias) for writing the excellent PPI and the Class::Inspector manpage modules. umlclass.pl uses the former to extract package names from user's .pm files or the latter to retrieve the function list of a specific package.

I'm also grateful to Christopher Malon since he has (unintentionally) motivated me to turn the original hack into this CPAN module. ;-)


SOURCE CONTROL

You can always grab the latest version from the following Subversion repository:

http://svn.berlios.de/svnroot/repos/umlclass/

It has anonymous access to all.

If you have the tuits to help out with this module, please let me know. I have a dream to keep sending out commit bits like Audrey Tang. ;-)


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

umlclass.pl, Autodia, the UML::Sequence manpage, PPI, the Class::Inspector manpage.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy