.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "lexical::underscore 3pm"
.TH lexical::underscore 3pm 2024-03-06 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
lexical::underscore \- access your caller's lexical underscore
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&   use 5.010;
\&   use lexical::underscore;
\&   use Test::More;
\&   
\&   sub is_uppercase {
\&      my $var = @_ ? shift : ${lexical::underscore()};
\&      return $var eq uc($var);
\&   }
\&   
\&   my $thing = \*(AqFOO\*(Aq;
\&   my $works = 0;
\&   
\&   given ( $thing ) {
\&      when ( is_uppercase ) { $works++ }
\&   }
\&   
\&   ok($works);
\&   done_testing();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Starting with Perl 5.10, it is possible to create a lexical version of the Perl
default variable \f(CW$_\fR. Certain Perl constructs like the \f(CW\*(C`given\*(C'\fR keyword
automatically use a lexical \f(CW$_\fR rather than the global \f(CW$_\fR.
.PP
It is occasionallly useful for a sub to be able to access its caller's
\&\f(CW$_\fR variable regardless of whether it was lexical or not. The \f(CW\*(C`(_)\*(C'\fR
sub prototype is the official way to do so, however there are sometimes
disadvantages to this; in particular it can only appear as the final required
argument in a prototype, and there is no way of the sub differentiating between
an explicitly passed argument and \f(CW$_\fR.
.PP
This caused me problems with Scalar::Does, because I wanted to enable the
\&\f(CW\*(C`does\*(C'\fR function to be called as either:
.PP
.Vb 2
\&   does($thing, $role);
\&   does($role);  # assumes $thing = $_
.Ve
.PP
With \f(CW\*(C`_\*(C'\fR in the prototype, \f(CW$_\fR was passed to the function at the end
of its argument list; effectively \f(CW\*(C`does($role, $thing)\*(C'\fR, making it
impossible to tell which argument was the role.
.PP
Enter \f(CW\*(C`lexical::underscore\*(C'\fR which allows you to access your caller's lexical
\&\f(CW$_\fR variable as easily as:
.PP
.Vb 1
\&   ${lexical::underscore()}
.Ve
.PP
You can access lexical \f(CW$_\fR further up the call stack using:
.PP
.Vb 1
\&   ${lexical::underscore($level)}
.Ve
.PP
If you happen to ask for \f(CW$_\fR at a level where no lexical \f(CW$_\fR is
available, you get the global \f(CW$_\fR instead.
.PP
This module does work on Perl 5.8 but as there is no lexical \f(CW$_\fR, always
returns the global \f(CW$_\fR.
.SS "Technical Details"
.IX Subsection "Technical Details"
The \f(CW\*(C`lexical::underscore\*(C'\fR function returns a scalar reference to either a
lexical \f(CW$_\fR variable somewhere up the call stack (using PadWalker
magic), or to the global \f(CW$_\fR if there was no lexical version.
.PP
Wrapping \f(CW\*(C`lexical::underscore\*(C'\fR in \f(CW\*(C`${ ... }\*(C'\fR dereferences the scalar
reference, allowing you to access (and even assign to) it.
.SH BUGS
.IX Header "BUGS"
Please report any bugs to
<http://rt.cpan.org/Dist/Display.html?Queue=lexical\-underscore>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
PadWalker.
.SH AUTHOR
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2012, 2014 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.