=head1 NAME

Devel::Trace::Method - Track how your object methods interact



=head1 SYNOPSIS

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

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

  # in each method call within your object, inform the method
  # that you want it tracked

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


=head1 DESCRIPTION

This module takes any object, and injects into it the ability to
have it track itself through all of its progress. As of now, it
creates an ordered stack trace, and a list of ordered method calls.

Note that I do have a rendering engine for both CLI and HTML,
for the output, but I have not hooked them in yet.



=head1 FUNCTIONS


=head2 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.


=head2 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.


=head2 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 array containing the list of methods
                  called, in the order they were called.

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

Given no optional parameters, the return is an array reference
that contains an array reference for all the above types.



=head1 EXAMPLES

# print the stack trace

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

$VAR1 = [
          {
            'sub' => 'Dude::say_hi',
            'filename' => './dude.pl',
            'caller' => 0,
            'line' => 26,
            'package' => 'Dude'
          },
          {
            'sub' => 'Dude::say_bye',
            'filename' => './dude.pl',
            'caller' => 'Dude::say_hi',
            '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'
        ];



=head1 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.



=head1 AUTHOR
Steve Bertrand, E<lt>steveb@cpan.orgE<gt>



=head1 COPYRIGHT AND LICENSE

Copyright (C) 2012 by Steve Bertrand

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.