Commit | Line | Data |
3fea05b9 |
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 |