/ 
Devel-Graph-0.03
River stage zero No dependents
/ Devel::Graph

NAME

Devel::Graph - Turn Perl code into an Graph::Easy object

SYNOPSIS

use Devel::Graph;

my $graph = Devel::Graph->graph( '$a = 9 if $b == 1' );

print $graph->as_ascii();

DESCRIPTION

This module decomposes Perl code into blocks and generates an Graph::Easy object out of these. The resulting object represents the code in a flowchart manner and you can turn it into all output formats currently supported by Graph::Easy, namely HTML, SVG, ASCII text etc.

Note: The actual decomposing parts are not yet implemented. Currently there is only code to assemble the flowchart manually via methods.

EXPORT

Exports nothing.

METHODS

graph() provides a simple function-style interface, while all other methods are for an object-oriented model.

All block-inserting routines on the this model will insert the block on the given position, or if this is not provided, on the current position. After inserting the blocks, the current position will be updated.

In addition, the newly inserted block(s) might be merged with blocks at the current position.

graph()

my $graph = Devel::Graph->graph( $code );

Takes Perl code in $code (as string or code ref) and returns a flowchart as Graph::Easy object.

This is a shortcut to avoid the OO interface described below and will be equivalent to:

my $grapher = Devel::Graph->new();
$grapher->decompose( $code );
my $graph = $grapher->as_graph();

Please see Graph::Easy for further details on what to do with the returned object.

new()

my $grapher = Devel::Graph->new();

Creates a new Devel::Graph object.

decompose()

$grapher->decompose( $code );

Takes Perl code in $code (as string or code ref) and decomposes it into blocks and updates the internal structures with a flowchart representing this code.

Note: Not yet implemented.

as_graph()

my $graph = $grapher->as_graph();

Return the internal data structure as Graph::Easy object.

current_block()

my $insertion = $grapher->current_block();

Returns the current block in the flow chart, e.g. where new code blocks will be inserted by the add_* methods.

first_block()

my $first = $grapher->first_block();

Returns the first block in the flow chart, usually the 'start' block.

last_block()

my $last = $grapher->first_block();

Returns the last block in the flow chart, usually the block where you last added something via one of the add_* routines.

finish()

my $last = $grapher->finish( $block );
my $last = $grapher->finish( );

Adds an end-block. If no parameter is given, uses the current position, otherwise appends the end block to the given $block. See also current_block. Will also update the position of last_block to point to the newly added block, and return this block.

new_block()

my $block = $grapher->add_block( $code );
my $block = $grapher->add_block( $code, Devel::Graph::Node::N_BLOCK );

Creates a new block/node from the given code and the optional type.

add_block()

my $current = $grapher->add_block( $block );
my $current = $grapher->add_block( $block, $where );

Add the given block. See new_block on creating the block before hand.

The optional $where parameter is the point where the code will be inserted. If not specified, it will be appended to the current block, see current_block.

Returns the newly added block as current.

Example:

    +---------+
--> | $a = 9; | -->
    +---------+

add_if_then()

my $current = $grapher->add_if_then( $if, $then);
my $current = grapher->add_if_then( $if, $then, $where);

Add an if-then branch to the flowchart. The optional $where parameter defines at which block to attach the construct.

Returns the new current block, which is a joint.

Example:

                                         false
      +--------------------------------------------+
      |                                            v
    +-------------+  true   +---------+
--> | if ($a = 9) | ------> | $b = 1; | ------->   *   -->
    +-------------+         +---------+

add_if_then_else()

my $current = $grapher->add_if_then_else( $if, $then, $else);
my $current = $grapher->add_if_then_else( $if, $then, $else, $where);

Add an if-then-else branch to the flowchart.

The optional $where parameter defines at which block to attach the construct.

Returns the new current block, which is a joint.

Example:

    +-------------+
    |   $b = 2;   | --------------------------+
    +-------------+                           |
      ^                                       |
      | false                                 |
      |                                       v
    +-------------+  true   +---------+
--> | if ($a = 9) | ------> | $b = 1; | -->   *   -->
    +-------------+         +---------+

add_for()

my ($current,$body) = $grapher->add_for( $init, $while, $cont, $body);
my ($current,$body) = $grapher->add_for( $init, $while, $cont, $body, $where);

Add a for (my $i = 0; $i < 12; $i++) { ... } style loop.

The optional $where parameter defines at which block to attach the construct.

This routine returns two block positions, the current block (e.g. after the loop) and the block of the loop body.

Example:

    +--------------------+  false        
--> |   for: $i < 10;    | ------->  *  -->
    +--------------------+
      |                ^
      | true           +----+
      v                     |
    +---------------+     +--------+
    |     $a++;     | --> |  $i++  |
    +---------------+     +--------+

add_while

  	my ($current,$body, $cont) = 
	  $grapher->add_while($while, $body, $cont, $where) = @_;

To skip the continue block, pass $cont as undef.

This routine returns three block positions, the current block (e.g. after the loop), the block of the loop body and the continue block.

Example of a while loop with only the body (or only the continue block):

    +----------------------+  false  
--> |   while ($b < 19)    | ------->  *  -->
    +----------------------+
      |                  ^
      | true             |
      v                  |
    +-----------------+  |
    |      $b++;      |--+
    +-----------------+

Example of a while loop with body and continue block (not similiarity to for loop):

    +--------------------+  false        
--> | while ($i < 10)    | ------->  *  -->
    +--------------------+
      |                ^
      | true           +----+
      v                     |
    +---------------+     +--------+
    |     $a++;     | --> |  $i++  |
    +---------------+     +--------+

add_joint()

my $joint = $grapher->add_joint( @blocks );

Adds a joint (an unlabeled, star-shaped node) to the flowchart and then connects each block in the given list to that joint. This is used f.i. by if-then-else constructs that need a common joint where all the branches join together again.

When adding a block right after a joint, they will be merged together and the joint will be effectively replaced by the block.

Example:

-->   *   -->

merge_blocks()

$grapher->merge_blocks($first,$second);

If possible, merge the given two blocks into one block, keeping all connections to the first, and all from the second. Any connections between the two blocks is dropped.

Example:

                      |
                      |
                      v
    +---------+     +---------+
--> | $a = 9; | --> | $b = 2; | -->
    +---------+     +---------+
      |
      |
      v

This will be turned into:

      |
      |
      v
    +---------+ 
--> | $a = 9; | -->
    | $b = 2; | 
    +---------+
      |
      |
      v

connect()

my $edge = $grapher->connect( $from, $to );
my $edge = $grapher->connect( $from, $to, $edge_label );

Connects two blocks with an edge, setting the optional edge label.

Returns the <Graph::Easy::Edge> object for the connection.

SEE ALSO

Graph::Easy.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms of the GPL version 2. See the LICENSE file for information.

AUTHOR

Copyright (C) 2004-2005 by Tels http://bloodgate.com