| 1 |
----------------------------------------------------------------------------- |
| 2 |
| PadWalker v2.5 - Robin Houston |
| 3 |
----------------------------------------------------------------------------- |
| 4 |
|
| 5 |
NAME |
| 6 |
PadWalker - play with other peoples' lexical variables |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
use PadWalker qw(peek_my peek_our peek_sub closed_over); |
| 10 |
... |
| 11 |
|
| 12 |
DESCRIPTION |
| 13 |
PadWalker is a module which allows you to inspect (and even change!) |
| 14 |
lexical variables in any subroutine which called you. It will only show |
| 15 |
those variables which are in scope at the point of the call. |
| 16 |
|
| 17 |
PadWalker is particularly useful for debugging. It's even used by |
| 18 |
Perl's built-in debugger. (It can also be used for evil, of course.) |
| 19 |
|
| 20 |
I wouldn't recommend using PadWalker directly in production code, but |
| 21 |
it's your call. Some of the modules that use PadWalker internally are |
| 22 |
certainly safe for and useful in production. |
| 23 |
|
| 24 |
peek_my LEVEL |
| 25 |
peek_our LEVEL |
| 26 |
The LEVEL argument is interpreted just like the argument to |
| 27 |
"caller". So peek_my(0) returns a reference to a hash of all the |
| 28 |
"my" variables that are currently in scope; peek_my(1) returns a |
| 29 |
reference to a hash of all the "my" variables that are in scope at |
| 30 |
the point where the current sub was called, and so on. |
| 31 |
|
| 32 |
"peek_our" works in the same way, except that it lists the "our" |
| 33 |
variables rather than the "my" variables. |
| 34 |
|
| 35 |
The hash associates each variable name with a reference to its |
| 36 |
value. The variable names include the sigil, so the variable $x is |
| 37 |
represented by the string '$x'. |
| 38 |
|
| 39 |
For example: |
| 40 |
|
| 41 |
my $x = 12; |
| 42 |
my $h = peek_my (0); |
| 43 |
${$h->{'$x'}}++; |
| 44 |
|
| 45 |
print $x; # prints 13 |
| 46 |
|
| 47 |
Or a more complex example: |
| 48 |
|
| 49 |
sub increment_my_x { |
| 50 |
my $h = peek_my (1); |
| 51 |
${$h->{'$x'}}++; |
| 52 |
} |
| 53 |
|
| 54 |
my $x=5; |
| 55 |
increment_my_x; |
| 56 |
print $x; # prints 6 |
| 57 |
|
| 58 |
peek_sub SUB |
| 59 |
The "peek_sub" routine takes a coderef as its argument, and returns |
| 60 |
a hash of the "my" variables used in that sub. The values will usu- |
| 61 |
ally be undefined unless the sub is in use (i.e. in the call-chain) |
| 62 |
at the time. On the other hand: |
| 63 |
|
| 64 |
my $x = "Hello!"; |
| 65 |
my $r = peek_sub(sub {$x})->{'$x'}; |
| 66 |
print "$$r\n"; # prints 'Hello!' |
| 67 |
|
| 68 |
If the sub defines several "my" variables with the same name, |
| 69 |
you'll get the last one. I don't know of any use for "peek_sub" |
| 70 |
that isn't broken as a result of this, and it will probably be dep- |
| 71 |
recated in a future version in favour of some alternative inter- |
| 72 |
face. |
| 73 |
|
| 74 |
closed_over SUB |
| 75 |
"closed_over" is similar to "peek_sub", except that it only lists |
| 76 |
the "my" variables which are used in the subroutine but defined |
| 77 |
outside: in other words, the variables which it closes over. This |
| 78 |
does have reasonable uses: see Data::Dump::Streamer, for example (a |
| 79 |
future version of which may in fact use "closed_over"). |
| 80 |
|
| 81 |
set_closed_over SUB, HASH_REF |
| 82 |
"set_closed_over" reassigns the pad variables that are closed over |
| 83 |
by the subroutine. |
| 84 |
|
| 85 |
The second argument is a hash of references, much like the one |
| 86 |
returned from "closed_over". |
| 87 |
|
| 88 |
var_name LEVEL, VAR_REF |
| 89 |
var_name SUB, VAR_REF |
| 90 |
"var_name(sub, var_ref)" returns the name of the variable referred |
| 91 |
to by "var_ref", provided it is a "my" variable used in the sub. |
| 92 |
The "sub" parameter can be either a CODE reference or a number. If |
| 93 |
it's a number, it's treated the same way as the argument to |
| 94 |
"peek_my". |
| 95 |
|
| 96 |
For example, |
| 97 |
|
| 98 |
my $foo; |
| 99 |
print var_name(0, \$foo); # prints '$foo' |
| 100 |
|
| 101 |
sub my_name { |
| 102 |
return var_name(1, shift); |
| 103 |
} |
| 104 |
print my_name(\$foo); # ditto |
| 105 |
|
| 106 |
AUTHOR |
| 107 |
Robin Houston <[email protected]> |
| 108 |
|
| 109 |
With contributions from Father Chrysostomous, Richard Soberberg, Florian Ragwitz, |
| 110 |
Yuval Kogman, and Fuji, Goro, bug-spotting from Peter Scott and Dave Mitchell, and |
| 111 |
suggestions from demerphq. |
| 112 |
|
| 113 |
SEE ALSO |
| 114 |
Devel::LexAlias, Devel::Caller, Sub::Parameters |
| 115 |
|
| 116 |
COPYRIGHT |
| 117 |
Copyright (c) 2000-2012, Robin Houston. All Rights Reserved. This mod- |
| 118 |
ule is free software. It may be used, redistributed and/or modified |
| 119 |
under the same terms as Perl itself. |