NAME

Devel::Trace::Method - Follow the flow of your object's method calls

SYNOPSIS

  use Devel::Trace::Method qw( 
                                track_object_methods    
                                track_method
                                fetch_trace
                            );

  # configure your object for method tracking within your
  # new() method
 
  track_object_methods( $self ); 

  # add the tracking call within each of your methods

  track_method( $self );
  
  # retrieve the data  
    
  my $all        = fetch_trace( $obj ); # or $self
  my $codeflow   = fetch_trace( $obj, 'codeflow' );
  my $stacktrace = fetch_trace( $obj, 'stacktrace' );

DESCRIPTION

This module takes any object, and injects into it the ability to have it track its own method calls, and store this information for later retrieval. It creates and stores an ordered stack trace, and a list of ordered method calls.

NOTE: This is alpha software, and *will* go through API changes in the early stages.

FUNCTIONS

track_object_methods( OBJ )

Prepares and configures your object so that it can create and retain its own codeflow and stack trace data over time.

Takes an object as its only parameter, and returns the object.

This function should be called within your new() method, after blessing your object, and prior to returning it.

track_method( OBJ )

This function appends tracking data to what is currently saved for each method call that calls this function.

Currently, this function call must be manually listed in each method you want to track. It should be entered in all of your class methods, or the program flow won't make much sense ;)

Takes your $self object as the only parameter, and returns 0 upon success.

fetch_trace( OBJ, STRING )

Retrieves the stored data that had accumulated thus far in the run of your program. Can be called from within one of your methods, or by a program using one of your methods.

Takes an object as the first mandatory parameter. The second optional string parameter states which data you'd like returned:

    'codeflow'   -returns an arrayref containing the list of methods
                  called, in the order they were called.

    'stacktrace' -returns an arrayref of hash references, where
                  each hash ref contains details of each method call

Given no optional parameters, returns a hash reference that contains an array reference for each of the available data.

EXAMPLES

    # print the stack trace

    my $stack = fetch_trace( $obj, 'stacktrace' );
    print Dumper $stack;

    $VAR1 = [
          {
            'caller' => 0,
            'sub' => 'Dude::say_hi',
            'filename' => './dude.pl',
            'line' => 26,
            'package' => 'Dude'
          },
          {
            'caller' => 'Dude::say_hi',
            'sub' => 'Dude::say_bye',
            'filename' => './dude.pl',
            'line' => 46,
            'package' => 'Dude'
          }
        ];

    # print the code flow

    my $codeflow = fetch_trace( $obj, 'codeflow' );
    print Dumper $codeflow;

    $VAR1 = [
          '0 => Dude::say_hi',
          '1 => Dude::say_bye'
        ];

LIMITATIONS ETC

This is pure alpha software. Although the code works well, there are some serious limitations, and for large class hierarchies, there may be a significant performance hit. There is no internal method to bypass the work this module does (yet), so use it only for testing, or wrap the track_method() calls within an if($debug) type block.

Until I figure out how to get around it, the trace_method() call must be manually placed in all methods you want to keep track of.

Currently, we do not munge the symbol table of the object to create its own methods, therefore your object has to pass itself in as an argument. In the future, we'll have an option to have it either way.

AUTHOR

Steve Bertrand, <steveb@cpan.org>

COPYRIGHT

Copyright (C) 2012 by Steve Bertrand

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.

cpanm Devel::Trace::Method

perl -MCPAN -e shell
install Devel::Trace::Method