debian man page for perl6::caller

Perl6::Caller(3pm)					User Contributed Perl Documentation					Perl6::Caller(3pm)

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.

       o   "package"

       o   "filename"

       o   "line"

       o   "subroutine"

       o   "hasargs"

       o   "wantarray"

       o   "evaltext"

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

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

       o   Subclassing

	   Don't.

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

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

       o   Overloading

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

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

perl v5.10.1							    2009-10-18							Perl6::Caller(3pm)