local-lib5/man/man3/PadWalker.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "PadWalker 3"
 132 .TH PadWalker 3 "2009-06-26" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 PadWalker \- play with other peoples' lexical variables
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  use PadWalker qw(peek_my peek_our peek_sub closed_over);
 139 \&  ...
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 PadWalker is a module which allows you to inspect (and even change!)
 144 lexical variables in any subroutine which called you. It will only
 145 show those variables which are in scope at the point of the call.
 146 .PP
 147 PadWalker is particularly useful for debugging. It's even
 148 used by Perl's built-in debugger. (It can also be used
 149 for evil, of course.)
 150 .PP
 151 I wouldn't recommend using PadWalker directly in production
 152 code, but it's your call. Some of the modules that use
 153 PadWalker internally are certainly safe for and useful
 154 in production.
 155 .IP "peek_my \s-1LEVEL\s0" 4
 156 .IX Item "peek_my LEVEL"
 157 .PD 0
 158 .IP "peek_our \s-1LEVEL\s0" 4
 159 .IX Item "peek_our LEVEL"
 160 .PD
 161 The \s-1LEVEL\s0 argument is interpreted just like the argument to \f(CW\*(C`caller\*(C'\fR.
 162 So \f(CWpeek_my(0)\fR returns a reference to a hash of all the \f(CW\*(C`my\*(C'\fR
 163 variables that are currently in scope;
 164 \&\f(CWpeek_my(1)\fR returns a reference to a hash of all the \f(CW\*(C`my\*(C'\fR
 165 variables that are in scope at the point where the current
 166 sub was called, and so on.
 167 .Sp
 168 \&\f(CW\*(C`peek_our\*(C'\fR works in the same way, except that it lists
 169 the \f(CW\*(C`our\*(C'\fR variables rather than the \f(CW\*(C`my\*(C'\fR variables.
 170 .Sp
 171 The hash associates each variable name with a reference
 172 to its value. The variable names include the sigil, so
 173 the variable \f(CW$x\fR is represented by the string '$x'.
 174 .Sp
 175 For example:
 176 .Sp
 177 .Vb 3
 178 \&  my $x = 12;
 179 \&  my $h = peek_my (0);
 180 \&  ${$h\->{'$x'}}++;
 181 .Ve
 182 .Sp
 183 .Vb 1
 184 \&  print $x;  # prints 13
 185 .Ve
 186 .Sp
 187 Or a more complex example:
 188 .Sp
 189 .Vb 4
 190 \&  sub increment_my_x {
 191 \&    my $h = peek_my (1);
 192 \&    ${$h\->{'$x'}}++;
 193 \&  }
 194 .Ve
 195 .Sp
 196 .Vb 3
 197 \&  my $x=5;
 198 \&  increment_my_x;
 199 \&  print $x;  # prints 6
 200 .Ve
 201 .IP "peek_sub \s-1SUB\s0" 4
 202 .IX Item "peek_sub SUB"
 203 The \f(CW\*(C`peek_sub\*(C'\fR routine takes a coderef as its argument, and returns a hash
 204 of the \f(CW\*(C`my\*(C'\fR variables used in that sub. The values will usually be undefined
 205 unless the sub is in use (i.e. in the call\-chain) at the time. On the other
 206 hand:
 207 .Sp
 208 .Vb 3
 209 \&  my $x = "Hello!";
 210 \&  my $r = peek_sub(sub {$x})\->{'$x'};
 211 \&  print "$$r\en";        # prints 'Hello!'
 212 .Ve
 213 .Sp
 214 If the sub defines several \f(CW\*(C`my\*(C'\fR variables with the same name, you'll get the
 215 last one. I don't know of any use for \f(CW\*(C`peek_sub\*(C'\fR that isn't broken as a result
 216 of this, and it will probably be deprecated in a future version in favour of
 217 some alternative interface.
 218 .IP "closed_over \s-1SUB\s0" 4
 219 .IX Item "closed_over SUB"
 220 \&\f(CW\*(C`closed_over\*(C'\fR is similar to \f(CW\*(C`peek_sub\*(C'\fR, except that it only lists
 221 the \f(CW\*(C`my\*(C'\fR variables which are used in the subroutine but defined outside:
 222 in other words, the variables which it closes over. This \fIdoes\fR have
 223 reasonable uses: see Data::Dump::Streamer, for example (a future version
 224 of which may in fact use \f(CW\*(C`closed_over\*(C'\fR).
 225 .IP "set_closed_over \s-1SUB\s0, \s-1HASH_REF\s0" 4
 226 .IX Item "set_closed_over SUB, HASH_REF"
 227 \&\f(CW\*(C`set_closed_over\*(C'\fR reassigns the pad variables that are closed over by the subroutine.
 228 .Sp
 229 The second argument is a hash of references, much like the one returned from \f(CW\*(C`closed_over\*(C'\fR.
 230 .IP "var_name \s-1LEVEL\s0, \s-1VAR_REF\s0" 4
 231 .IX Item "var_name LEVEL, VAR_REF"
 232 .PD 0
 233 .IP "var_name \s-1SUB\s0,   \s-1VAR_REF\s0" 4
 234 .IX Item "var_name SUB,   VAR_REF"
 235 .PD
 236 \&\f(CW\*(C`var_name(sub, var_ref)\*(C'\fR returns the name of the variable referred to
 237 by \f(CW\*(C`var_ref\*(C'\fR, provided it is a \f(CW\*(C`my\*(C'\fR variable used in the sub. The \f(CW\*(C`sub\*(C'\fR
 238 parameter can be either a \s-1CODE\s0 reference or a number. If it's a number,
 239 it's treated the same way as the argument to \f(CW\*(C`peek_my\*(C'\fR.
 240 .Sp
 241 For example,
 242 .Sp
 243 .Vb 2
 244 \&  my $foo;
 245 \&  print var_name(0, \e$foo);    # prints '$foo'
 246 .Ve
 247 .Sp
 248 .Vb 4
 249 \&  sub my_name {
 250 \&    return var_name(1, shift);
 251 \&  }
 252 \&  print my_name(\e$foo);        # ditto
 253 .Ve
 254 .SH "AUTHOR"
 255 .IX Header "AUTHOR"
 256 Robin Houston <robin@cpan.org>
 257 .PP
 258 With contributions from Richard Soberberg, Jesse Luehrs and
 259 Yuval Kogman, bug-spotting from Peter Scott, Dave Mitchell and
 260 Goro Fuji, and suggestions from demerphq.
 261 .SH "SEE ALSO"
 262 .IX Header "SEE ALSO"
 263 Devel::LexAlias, Devel::Caller, Sub::Parameters
 264 .SH "COPYRIGHT"
 265 .IX Header "COPYRIGHT"
 266 Copyright (c) 2000\-2009, Robin Houston. All Rights Reserved.
 267 This module is free software. It may be used, redistributed
 268 and/or modified under the same terms as Perl itself.