NAME

UML::State - an object oriented module which draws simple state diagrams

VERSION

This documentation covers version 0.01, the initial release made in May 2003.

SYNOPSIS

    use UML::State;

    my $diagram = UML::State->new(
        $node_array,
        $start_list,
        $accept_list,
        $edges
    );

    # You may change these defaults (doing so may even work):
    $UML::State::ROW_SPACING = 75;  # all numbers are in pixels
    $UML::State::LEFT_MARGIN = 20;
    $UML::State::WIDTH       = 800;
    $UML::State::HEIGHT      = 800;

    print $diagram->draw();

ABSTRACT

Are you tired of pointing and clicking to make simple diagrams? Do your wrists hurt thinking about making the pretty UML your boss likes so well? Consider using UML::State and UML::Sequence to make your life easier.

UML::State together with drawstate.pl allows you to easily generate state diagrams. You enter them in something like a cross between ASCII art and school room algebra. They come out looking like something from a drawing program like Visio. See drawstate.pl in the distribution for details about the input format and the samples directory for some examples of input and output.

DESCRIPTION

You will probably use this class by running drawstate.pl or drawstatexml.pl which are included in the distribution. But you can use this package directly to gain control over the appearance of your pictures.

The two methods you need are new and draw (see below). If you want, you may change the dimensions by setting the package global variables as shown in the SYNOPSIS. Obviously, no error checking is done, so be careful to use reasonable values (positive numbers are good). All numbers are in pixels (sorry by Bezier's in SVG seem to require pixels). I have not tried changing the numbers, so I don't have any idea if doing so makes reasonable changes to the output.

EXPORT

Nothing, this module is object oriented.

METHODS

new

This constructor expects the following things:

$node_array

A reference to a two dimensional array holding the names (and implicit positions) of the nodes in your state graph. If you want to leave a blank space in the diagram, include the empty string as the name of a node you want to omit.

Example:

    $nodes = [ [ "A", "B", "C"],
               [ "D",  "", "E"] ];

This is six nodes labeled A-E arranged in two rows with three nodes in each row. The middle node of the second row is omitted.

$start_list

A reference to an array listing the start state edge(s). Each arrow should be of the form: col,row,head_direction tail_direction. The entry $node_array->[col][row] must be defined. The directions can be any of N, S, E, or W representing compass points on the centers of the sides of the node's box. N is the top center, S is the bottom center, etc. The head_direction is the one the arrow points to. 0,0,N N is a common start edge.

$accept_list

A reference to an array listing the accepting states in your graph. Each entry in the array should be an ordered pair col,row. The entry $node_array->[col][row] must be defined. The only affect of a node being in the accept list is to make a doubled box around its name.

$edges

A reference to a hash. Each key in the hash is an edge label. The corresponding value is a list of edges. Each edge is a string with two or three parts. The first two parts are positions and are required. The third element is optional. It controls curving edges. If absent the edge is straight. If present it may match /Counter.*/ for counterclockwise, or anything else for clockwise. Trying some examples will make more sense than what I might write.

The positions are of the same form as starting edges: col,row,direction. The tail is listed first, then the head. If you must include a self referencing edge, use exactly the same entry for tail and head. Currently this makes a small circle at that point. Self reference circles have no arrow head.

Examples:

    0,0,S 0,1,N Counter
    0,1,W 1,1,E
    1,1,N 1,1,N

The first edge connects the south side of the node at 0,0 to the north side of the node at 0,1 with an arc curved in the counter-clockwise direction. The second edge connects the west side of the node at 0,1 to the east side of the node at 1,1. The third edge is a self reference drawn on the north side of node 1,1.

draw

This method can be called any time after the constructor. It returns a string containing the svg for your state graph. You can print that, or parse it with standard XML techniques.

BUGS

Self reference edges are just circles, they don't have arrows.

There is no way to control the placement of labels.

Only one letter labels look good.

Resizing (changing the class constants) is unreliable.

AUTHOR

Phil Crow <philcrow2000@yahoo.com<gt>

COPYRIGHT AND LICENSE

Copyright 2003 by Phil Crow. All rights reserved. This is free software. You may modify and/or redistribute it under the same terms as Perl 5.8.0.