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

VERSION
    This document describes "UML::Class::Simple" 0.01 released by Oct 30,
    2006.

SYNOPSIS
        use UML::Class::Simple;

        # produce a class diagram for fglock's Pugs::Compiler::Perl6
        # 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 UML::Sequence, 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 representations, so I started
    another competing project after getting some guide from "#perl" on
    "irc.perl.org". ;-)

    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 (See samples/ppi_small.png in the distribution.)

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

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

SUBROUTINES
    classes_from_runtime($module_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 $regex argument can be omitted.

    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 $regex argument can be omitted.

    These subroutines are not imported by default.

METHODS
    "$obj->new( [@class_names] )"
        Creates 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?)"
        Generates 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()"
        Returns 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::List',
                                               'PPI::Structure::Subscript',
                                               'PPI::Structure::Unknown'
                                             ],
                             'methods' => [
                                            '_INSTANCE',
                                            '_set_finish',
                                            'braces',
                                            'content',
                                            'elements',
                                            'finish',
                                            'first_element',
                                            'insert_after',
                                            'insert_before',
                                            'last_element',
                                            '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 image.

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

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

PROPERTIES
    "$obj->size($width, $height)"
    "($width, $height) = $obj->size"
        Sets/gets 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"
        Sets/gets the background color for the class nodes. It defaults to
        '#f1e1f4'.

INSTALLATION
    Please download and intall the latest Graphviz binary 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 subs in perl). If you have any good ideas,
        please drop me a line.

    *   Only the inheritance relationships are shown in the images. I
        believe other subtle relations can only 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 (".") in
        the standard UML syntax. One can argue that following UML standards
        are more important since people in the same team may use different
        programming languages. But sorry, it's not the case for me. ;-)

TODO
    *   Add more unit tests.

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

    *   Provide a DOM interface for the class hierarchy so that the user can
        control what's in there and what not.

    *   Provide backends other than Graphviz.

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

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

BUGS
    There must be some serious bugs lurking somewhere. so if you found one,
    please report it to <http://rt.cpan.org>.

ACKNOWLEDGEMENT
    I must thank Adam Kennedy (Alias) for writing the excellent PPI module
    and Class::Inspector. pm2png uses the former to extract package names
    from user's .pm files while rt2png uses the latter to retrieve the
    function list of a specific package.

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, UML::Sequence, PPI, Class::Inspector.

