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