local-lib5/lib/perl5/i486-linux-gnu-thread-multi/PadWalker.pm

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