---
name: "lexical::underscore"
section: "3pm"
platform: "linux"
package: "liblexical-underscore-perl"
version: "0.004-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lexical::underscore"
---

# lexical::underscore(3pm)

access your caller's lexical underscore

## 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, 2014 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.