NAME

SYNOPSIS

  use PadWalker qw(peek_my peek_our peek_sub closed_over);
  ...

DESCRIPTION

PadWalker is particularly useful for debugging. It's even used by Perl's built-in debugger. (It can also be used for evil, of course.)

I wouldn't recommend using PadWalker directly in production code, but it's your call. Some of the modules that use PadWalker internally are certainly safe for and useful in production.

peek_my LEVEL

peek_our LEVEL

The LEVEL argument is interpreted just like the argument to "caller". So peek_my(0) returns a reference to a hash of all the "my" variables that are currently in scope; peek_my(1) returns a reference to a hash of all the "my" variables that are in scope at the point where the current sub was called, and so on.

"peek_our" works in the same way, except that it lists the "our" variables rather than the "my" variables.

The hash associates each variable name with a reference to its value. The variable names include the sigil, so the variable $x is represented by the string '$x'.

For example:

  my $x = 12;
  my $h = peek_my (0);
  ${$h->{'$x'}}++;

  print $x;  # prints 13
    

Or a more complex example:

  sub increment_my_x {
    my $h = peek_my (1);
    ${$h->{'$x'}}++;
  }

  my $x=5;
  increment_my_x;
  print $x;  # prints 6
    

peek_sub SUB

The "peek_sub" routine takes a coderef as its argument, and returns a hash of the "my" variables used in that sub. The values will usually be undefined unless the sub is in use (i.e. in the call-chain) at the time. On the other hand:

  my $x = "Hello!";
  my $r = peek_sub(sub {$x})->{'$x'};
  print "$$r\n";        # prints 'Hello!'
    

If the sub defines several "my" variables with the same name, you'll get the last one. I don't know of any use for "peek_sub" that isn't broken as a result of this, and it will probably be deprecated in a future version in favour of some alternative interface.

closed_over SUB

"closed_over" is similar to "peek_sub", except that it only lists the "my" variables which are used in the subroutine but defined outside: in other words, the variables which it closes over. This does have reasonable uses: see Data::Dump::Streamer, for example (a future version of which may in fact use "closed_over").

set_closed_over SUB, HASH_REF

"set_closed_over" reassigns the pad variables that are closed over by the subroutine.

The second argument is a hash of references, much like the one returned from "closed_over".

var_name LEVEL, VAR_REF

var_name SUB, VAR_REF

"var_name(sub, var_ref)" returns the name of the variable referred to by "var_ref", provided it is a "my" variable used in the sub. The "sub" parameter can be either a CODE reference or a number. If it's a number, it's treated the same way as the argument to "peek_my".

For example,

  my $foo;
  print var_name(0, \$foo);    # prints '$foo'
  
  sub my_name {
    return var_name(1, shift);
  }
  print my_name(\$foo);        # ditto
    

AUTHOR

With contributions from Richard Soberberg, Jesse Luehrs and Yuval Kogman, bug-spotting from Peter Scott, Dave Mitchell and Goro Fuji, and suggestions from demerphq.

SEE ALSO

COPYRIGHT