=head1 NAME

Devel::CallTrace - See what your code's doing

=head1 SYNOPSIS

#!/usr/bin/perl -d:CallTrace

package foo;

sub bar {
  print "bar\n";
  baz();
}

sub baz {
    print "boo\n";
}


foo::bar();

=head1 RATIONALE

There are a number of perl modules in the CPAN that are designed to trace
a program's execution as it runs. Each uses a different trick to do its job, 
but none of them quite met my needs.  The technique this module uses is quite 
simple and seems to be quite robust.  


=cut

package Devel::CallTrace;
use warnings;
use strict;
no strict 'refs';

use vars qw($SUBS_MATCHING);
our $VERSION = '1.0';

$SUBS_MATCHING = qw/.*/;



BEGIN { $^P |= 0x01 };

sub import {


}
package DB;

# Any debugger needs to have a sub DB. It doesn't need to do anything.
sub DB{};

# We want to track how deep our subroutines go
our $CALL_DEPTH = 0;


=head2 DB::sub

perl will automatically call DB::sub on each subroutine call and leave it up
to us to dispatch to where we want to go.

=cut


sub sub {
    # localize CALL_DEPTH so that we don't need to decrement it after the sub 
    # is called
    local $DB::CALL_DEPTH = $DB::CALL_DEPTH+1;

    # Report on what's going on, but only if it matches our regex
    Devel::CallTrace::called($DB::CALL_DEPTH, \@_) 
        if ($DB::sub =~ $Devel::CallTrace::SUBS_MATCHING);

    # Call our subroutine. @_ gets passed on for us.
    # by calling it last, we don't need to worry about "wantarray", etc
    # by returning it like this, the caller's expectations are conveyed to 
    # the called routine
    &{$DB::sub};
}

=head2 Devel::CallTrace::called 

This routine is called with two parameters:

=over

=item DEPTH

The integer "depth" that this call is being called at.

=item PARAMS

A reference to the routine's @INC

=back

To get at the subroutine that was being called, have a look at $DB::sub

=cut

sub Devel::CallTrace::called {
    my $depth = shift;
    my $routine = shift;
    # print STDERR is safe. warn is not. calling any routine 
    # not defined from within the DB:: package will not work. (see perldebguts)
    print STDERR " " x $depth . $DB::sub ."\n";
}

=head1 BUGS

It uses the debugger. How could it not have bugs?

=head1 SEE ALSO

L<perldebguts>, L<DB>, a licensed therapist.


L<trace> - Uses source filters. Scares me.

L<Devel::TraceCalls> - Very robust API. The code seems to do all sorts of scary
magic


L<Debug::Trace> - Uses symbol table magic to wrap your functions. 

L<Devel::TRaceFuncs> - Requires developers to instrument their source files.


=head1 COPYRIGHT

Copyright 2005 Jesse Vincent <jesse@bestpractical.com>

This module may be redistributed under the same terms as perl itself

=cut
1;