NAME
    lexical::underscore - access your caller's lexical underscore

SYNOPSIS
       use 5.010;
       use lexical::underscore;
       use Test::More;
   
       sub is_uppercase {
          my $var = @_ ? shift : ${lexical::underscore()};
          return $var eq uc($var);
       }
   
       my $thing = 'FOO';
       my $works = 0;
   
       given ( $thing ) {
          when ( is_uppercase ) { $works++ }
       }
   
       ok($works);
       done_testing();

DESCRIPTION
    Starting with Perl 5.10, it is possible to create a lexical version of
    the Perl default variable $_. Certain Perl constructs like the "given"
    keyword automatically use a lexical $_ rather than the global $_.

    It is occasionallly useful for a sub to be able to access its caller's
    $_ variable regardless of whether it was lexical or not. The "(_)" 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 $_.

    This caused me problems with Scalar::Does, because I wanted to enable
    the "does" function to be called as either:

       does($thing, $role);
       does($role);  # assumes $thing = $_

    With "_" in the prototype, $_ was passed to the function at the end of
    its argument list; effectively "does($role, $thing)", making it
    impossible to tell which argument was the role.

    Enter "lexical::underscore" which allows you to access your caller's
    lexical $_ variable as easily as:

       ${lexical::underscore()}

    You can access lexical $_ further up the call stack using:

       ${lexical::underscore($level)}

    If you happen to ask for $_ at a level where no lexical $_ is available,
    you get the global $_ instead.

    This module does work on Perl 5.8 but as there is no lexical $_, always
    returns the global $_.

  Technical Details
    The "lexical::underscore" function returns a scalar reference to either
    a lexical $_ variable somewhere up the call stack (using PadWalker
    magic), or to the global $_ if there was no lexical version.

    Wrapping "lexical::underscore" in "${ ... }" dereferences the scalar
    reference, allowing you to access (and even assign to) it.

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=lexical-underscore>.

SEE ALSO
    PadWalker.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2012 by Toby Inkster.

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

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.