NAME
Text::ProcessMap - Create process diagrams in plain text format.
DESCRIPTION
This module provides a text based tool for the generation process diagrams, sometimes called process maps. The process maps produced by this module are similar to UML Interaction Diagrams, only much simpler.
SYNOPSIS
use strict;
use warnings;
use Text::ProcessMap;
my $pmap = Text::ProcessMap->new;
$pmap->header(
title => 'Hello World',
name => 'test'
);
$pmap->body(
coltitles => ['Column 1', 'Column 2', 'Column 3'],
colwidths => [20, 20, 20],
);
$pmap->node(
col => 1,
id => '11',
title => 'My Input',
elements => [ 'Input Element 1', 'Input Element 2' ]
);
$pmap->node(
col => 2,
id => '21',
title => 'My Process',
elements => [ 'Process Element 1', 'Process Element 2' ]
);
$pmap->node(
col => 3,
id => '31',
title => 'My Output',
elements => [ 'Output Element 1', 'Output Element 2' ]
);
$pmap->draw;SUMMARY
A process map provides a simple method to document the high-level details of a system process or computer activity.
Information to display can be defined directly in a Perl script using methods provided by the module, or using text based definition files. The definition files are structured like ini files, making them easy to build and maintain.
Output can be directed to either a file or to STDOUT, making it possible to use the module interactively, in batch mode, or as a component in a CGI script.
SAMPLE DIAGRAM
Below is an example diagram demonstrating the 'matrix' layout option:
----------------------------------------------------------------
Lorem
Lorem Ipsum
Diagram Number 1
----------------------------------------------------------------
Lorem Ipsum dolor sit amet, consectetuer adipiscing elit.
----------------------------------------------------------------
Column 1 || Column 2 || Column 3
----------------------------------------------------------------
+------------------. +------------------.
| HEADER | This is an arrow | [I04] |
|------------------| with description | Title |
| [I01] | text. | Lorem Ipsum |
| Title | -------------------> | dolor sit amet, |
| Lorem Ipsum | | consectetuer |
| dolor sit amet, | | adipiscing elit. |
| consectetuer | `------------------'
| adipiscing elit. | |
|The final element.| |
`------------------' |
|
+------------------. |
| [I02] | |
| Title | |
| Lorem Ipsum | |
| dolor sit amet, | |
| consectetuer | |
| adipiscing elit. | |
|------------------| |
| FOOTER | |
`------------------' |
|
+------------------. |
| This is a header | |
|showing word wrap.| |
|------------------| |
| [I03] | |
| Title | |
| Lorem Ipsum | |
| dolor sit amet, | |
| consectetuer | |
| adipiscing elit. | |
|------------------| |
| This is a footer | |
|showing word wrap.| |
`------------------' |
|
+------------------.
| [I05] |
| Title |
| Lorem Ipsum |
| dolor sit amet, |
| consectetuer |
| adipiscing elit. |
`------------------'
Lorem Ipsum dolor sit amet, consectetuer adipiscing elit.
----------------------------------------------------------------
lorem_ipsum 02/28/2005
----------------------------------------------------------------METHODS
new()
No required parameters. You may optionally provide any of the parameters accepted by the header() and body() methods described below. Arguments are passed using an anonymous hash.
my $pmap = Text::ProcessMap->new;header()
Use this method to set the header characteristics and other general attributes of the process map. Arguments are passed using an anonymous hash.
$pmap->header(
title => 'Hello World',
description => 'The Hello World Process',
topnote => 'This note will be displayed in the header',
diagramnote => 'This note will be displayed in the footer',
number => '1', # displayed in header
name => 'A name for the diagram', # displayed in footer
loader_file => 'sample1',
output_file => 'output1',
);body()
Use this method to set the body characteristics of the Activity Diagram. Arguments are passed using an anonymous hash.
$pmap->body(
layout => 'stack', # can be either 'stack' or 'matrix'
coltitles => ['Column 1', 'Column 2', 'Column 3'],
colwidths => [20, 20, 20],
boxchars => ["+", ".", "'", "`", "-", "|"], # default
);node()
Use this method to define diagram objects. Arguments are passed using an anonymous hash. The example below demonstrates the use of all the arguments accepted by the node method. Each method call generates a single diagram object.
$pmap->node(
col => 2,
row => 3,
id => 'I03',
header => 'This is a header showing word wrap.',
title => 'Title',
elements => ['Lorem Ipsum','dolor sit amet,','consectetuer','adipiscing elit.'],
footer => 'This is a footer showing word wrap.'
);draw()
Draws the diagram. If no argument is provided, the diagram will be sent to STDOUT. Other arguments accepted are an existing file handle or a file name to be created.
$pmap->draw; # output to STDOUT
$pmap->draw(*DIAG); # use file handle
$pmap->draw($filename); # create file $filenameDEFINITION FILES
A definition file is a diagram definition that can be read at run-time. This allows the you to build and maintain a library of process maps. A sample definition file is shown below. The definition files are similar to ini files, each section of the file provides input to a method, the word put is used to indicate when a method should be invoked. This definition file was used to create the sample diagram shown above.
[Header]
title = Lorem
description = Lorem Ipsum
topnote = Lorem Ipsum dolor sit amet, consectetuer adipiscing elit.
diagramnote = Lorem Ipsum dolor sit amet, consectetuer adipiscing elit.
name = lorem_ipsum
number = 19
put
[Body]
colwidths = 20,20,20
coltitles = Column 1,Column 2,Column 3
layout = matrix
put
[Column 1]
row = 1
id = I01
title = Title
header = HEADER
element = Lorem Ipsum
element = dolor sit amet,
element = consectetuer
element = adipiscing elit.
element = The final element.
put
row = 2
id = I02
footer = FOOTER
title = Title
element = Lorem Ipsum
element = dolor sit amet,
element = consectetuer
element = adipiscing elit.
put
[Column 2]
row = 1
type = arrow:3
title = This is an arrow with description text.
put
row = 3
id = I03
header = This is a header showing word wrap.
title = Title
element = Lorem Ipsum
element = dolor sit amet,
element = consectetuer
element = adipiscing elit.
footer = This is a footer showing word wrap.
put
[Column 3]
row = 1
id = I04
title = Title
element = Lorem Ipsum
element = dolor sit amet,
element = consectetuer
element = adipiscing elit.
connect = |
put
row = 4
id = I05
title = Title
element = Lorem Ipsum
element = dolor sit amet,
element = consectetuer
element = adipiscing elit.
putTEXT FORMATTING
Text entries are automatically word-wrapped to multiple lines. There is one exception to this rule, if a word is longer then the width of a diagram object, it will be truncated and a footnote generated for that word. The footnote will show the original word alongside its truncted version.
REFERENCES
Scott Ambler, Agile Modeling: http://www.agilemodeling.com/
UML Distilled, Third Edition. Scott Ambler.
AUTHOR
Copyright 2005, Brad J. Adkins. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Address bug reports and comments to: bradjadkins@badkins.net.
If you find this module useful, please feel free to send the Author an email and describe how you are using it. Thanks.
CREDITS
Thanks are in order to the following individuals for their suggestions.
Joel and Doug.
BUGS
Address bug reports and comments to: bradjadkins@badkins.net.
TODO
Some additional arrow types would be nice, but consideration will need to go into the approach used to define arrows in order to accomplish this.
SEE ALSO
Text::Flowchart