NAME

Sub::Caller - Add caller information to the end of @_.

DESCRIPTION

Sub::Caller provides an easy way to pass caller information to all, or specific, sub-routines:

   use Sub::Caller qw(all); ## Pass to all non-anon subs
   use Sub::Caller qw(sub1 sub2); ## Only these subs

   -- OR --

   use Sub::Caller;

   sub test { }

   &Sub::Caller::addCaller('test');

The sub-routines must be loaded before addCaller() can be called successfully. If you call addCaller() on the same sub-routine(s) multiple times, all calls after the first are silently ignored.

Caller information takes the form of:

   {
      package  => 'main',
      function => 'test',
      file     => 'test.pl',
      line     => 7,
   }

This hash reference is added to the end of @_.

EXAMPLE

   #!/usr/bin/perl
   # test.pl

   use Data::Dumper;
   use Sub::Caller('test');


   test('a');


   sub test {
      ## Make sure we have @_ and it is what we expect
      if (@_ && Sub::Caler::isCaller($_[-1])){
         print Dumper(\@_);
      }
   }

   __END__
   Dumper will print:

   $VAR1 = [
             'a',
             bless( {
                      'function' => 'main',
                      'file' => 'test.pl',
                      'line' => 8,
                      'package' => 'main'
                    }, 'Sub::Caller' )
           ];

AUTHOR

Shay Harding <sharding@ccbill.com>

CHANGES 2003-05-27 Added more tests. Updated POD with a clear example of usage.

TODO

Would be nice to add this to anonymous functions, but alas, I haven't figured that part out yet. Would probably have to dig into XS more and mess with OP code stuff.

ACKNOWLEDGEMENTS

I just want to say that Gisle Aas' "PerlGuts Illustrated" at http://gisle.aas.no/perl/illguts is fantastic. It really sheds some light on how all those darn SVs work out. Now if only the PERL_CONTEXT section were finished so I knew what those were...