Perl6::Caller - OO caller() interface

Version 0.04

 use Perl6::Caller;

 my $sub         = caller->subroutine;
 my $line_number = caller->line;
 my $is_require  = caller(3)->is_require;

 # standard usage
 print "In ",           caller->subroutine,
       " called from ", caller->file,
       " line ",        caller->line;

 # get a caller object
 my $caller = caller;
 my $caller = caller();   # same thing

 # get a caller object for a different stack from
 my $caller = caller(2);  # two stack frames up
 print $caller->package;  # prints the package name

 # enjoy the original flavor
 my @caller = caller;     # original caller behavior
 print $caller[0],        # prints the package name

This module is experimental. It's also alpha. Bug reports and patches welcome.

By default, this module exports the caller function. This automatically returns a new caller object. An optional argument specifies how many stack frames back to skip, just like the CORE::caller function. This lets you do things like this:

 print "In ",           caller->subroutine,
       " called from ", caller->file,
       " line ",        caller->line;

If you do not wish the caller function imported, specify an empty import list and instantiate a new Perl6::Caller object.

 use Perl6::Caller ();
 my $caller = Perl6::Caller->new;
 print $caller->line;

Note: if the results from the module seem strange, please read perldoc -s caller carefully. It has stranger behavior than you might be aware.

The following methods are available on the caller object. They return the same values as documented in perldoc -f caller.

There are no hints and bitmask methods because those are documented as for internal use only.

* package

* filename

* line

* subroutine

* hasargs

* wantarray

* evaltext

* is_require

Note that each of these values will report correctly for when the caller object was created. For example, the following will probably print different line numbers:

 print caller->line;
 foo();
 sub foo { 
    print caller->line;
 }

However, the following will print the same line numbers:

 my $caller = Perl6::Caller->new;   # everything is relative to here
 print $caller->line;
 foo($caller);
 sub foo { 
    my $caller = shift;
    print $caller->line;
 }

Most of the time, this package should just work and not interfere with anything else.

* $hints, $bitmask

'hints' and 'bitmask' are not available. They are documented to be for internal use only and should not be relied upon. Further, the bitmask caused strange test failures, so I opted not to include them.

* Subclassing

Don't.

* Perl 6

I'm not entirely comfortable with the namespace. The Perl 6 caller actually does considerably more, but for me to have a hope of working that in, I need proper introspection and I don't have that. Thus, I've settled for simply having a caller object.

* *CORE::GLOBAL::caller

I didn't implement this, though I was tempted. It turns out to be a bit tricky in spots and I'm very concerned about globally overriding behavior. I might change my mind in the future if there's enough demand.

* Overloading

In string context, this returns the package name. This is to support the original caller behavior.

* List Context

In list context, we simply default to the original behavior of CORE::caller. However, this always assumes we've called caller with an argument. Calling caller and caller(0) are identical with this module. It's difficult to avoid since the stack frame changes.

Curtis "Ovid" Poe, <ovid@cpan.org>

Thanks to phaylon for helping me revisit a bad design issue with this.

Please report any bugs or feature requests to bug-perl6-caller@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl6-Caller. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Copyright 2007 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.