NAME

       Perl6::Caller - OO "caller()" interface

VERSION

       Version 0.04

SYNOPSIS

        use Perl6::Caller;

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

EXPORT

"caller"

        # 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

DESCRIPTION

       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.

METHODS

       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;
        }

CAVEATS

       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.

AUTHOR

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

ACKNOWLEDGEMENTS

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

BUGS

       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.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

       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.