ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Devel-FindRef/FindRef.pm
(Generate patch)

Comparing Devel-FindRef/FindRef.pm (file contents):
Revision 1.5 by root, Wed Feb 7 21:34:02 2007 UTC vs.
Revision 1.13 by root, Fri Jul 11 22:18:10 2008 UTC

1package Devel::FindRef; 1package Devel::FindRef;
2 2
3use strict; 3use strict;
4 4
5use XSLoader; 5use XSLoader;
6 6use Scalar::Util;
7 7
8BEGIN { 8BEGIN {
9 our $VERSION = '0.2'; 9 our $VERSION = '1.3';
10 XSLoader::load __PACKAGE__, $VERSION; 10 XSLoader::load __PACKAGE__, $VERSION;
11} 11}
12 12
13=head1 NAME 13=head1 NAME
14 14
15Devel::FindRef - where is that reference to my scalar hiding? 15Devel::FindRef - where is that reference to my variable hiding?
16 16
17=head1 SYNOPSIS 17=head1 SYNOPSIS
18 18
19 use Devel::FindRef; 19 use Devel::FindRef;
20 20
… …
45 testsub; 45 testsub;
46 46
47The output is as follows (or similar to this, in case I forget to update 47The output is as follows (or similar to this, in case I forget to update
48the manpage after some changes): 48the manpage after some changes):
49 49
50 SCALAR(0x676fa0) is 50 SCALAR(0x814ece8) is
51 +- in the global $Test::var.
51 referenced by REF(0x676fb0), which is 52 +- referenced by REF(0x814f9e4), which is
52 in the lexical '$x' in CODE(0x676370), which is 53 | in the lexical '$x' in CODE(0x814ed78), which is
53 not found anywhere I looked :( 54 | the containing scope for CODE(0x820c4b0), which is
55 | in the global &Test::testsub.
54 referenced by REF(0x676360), which is 56 +- referenced by REF(0x814ed6c), which is
55 in the member 'ukukey' of HASH(0x756660), which is 57 | in the member 'ukukey' of HASH(0x81da20c), which is
56 in the global %Test::hash. 58 | in the global %Test::hash.
57 in the global $Test::var.
58 referenced by REF(0x6760e0), which is 59 +- referenced by REF(0x814ec28), which is
60 | not found anywhere I looked :(
61 +- referenced by REF(0x814eb44), which is
59 in the member 'ukukey2' of HASH(0x676f30), which is 62 in the member 'ukukey2' of HASH(0x814f99c), which is
60 referenced by REF(0x77bcf0), which is 63 +- referenced by REF(0x820c450), which is
61 in the lexical '$local' in CODE(0x77bcb0), which is 64 | in the lexical '$local' in CODE(0x820c4b0), which was seen before.
62 in the global &Test::testsub.
63 referenced by REF(0x77bc80), which is 65 +- referenced by REF(0x820c204), which is
64 in the global $Test::hash2. 66 in the global $Test::hash2.
65
66 67
67It is a bit convoluted to read, but basically it says that the value 68It is a bit convoluted to read, but basically it says that the value
68stored in C<$var> can be found: 69stored in C<$var> can be found:
69 70
70=over 4 71=over 4
… …
78 79
79=item - in the hash element C<ukukey2>, in the hash in the my variable 80=item - in the hash element C<ukukey2>, in the hash in the my variable
80C<$local> in the sub C<Test::testsub> and also in the hash referenced by 81C<$local> in the sub C<Test::testsub> and also in the hash referenced by
81C<$Test::hash2>. 82C<$Test::hash2>.
82 83
84=back
85
83=head1 EXPORTS 86=head1 EXPORTS
84 87
85None. 88None.
86 89
87=head1 FUNCTIONS 90=head1 FUNCTIONS
… …
99=cut 102=cut
100 103
101sub find($); 104sub find($);
102 105
103sub track { 106sub track {
107 my ($ref, $depth) = @_;
108 @_ = ();
109
104 my $buf = ""; 110 my $buf = "";
111 my %seen;
112
113 Scalar::Util::weaken $ref;
105 114
106 my $track; $track = sub { 115 my $track; $track = sub {
107 my (undef, $depth, $indent) = @_; 116 my ($refref, $depth, $indent) = @_;
108 117
109 if ($depth) { 118 if ($depth) {
110 my (@about) = find $_[0]; 119 my (@about) = find $$refref;
111 if (@about) { 120 if (@about) {
112 for my $about (@about) { 121 for my $about (@about) {
113 $buf .= (" ") x $indent; 122 $buf .= "$indent" . (@about > 1 ? "+- " : " ") . $about->[0];
114 $buf .= $about->[0];
115 if (@$about > 1) { 123 if (@$about > 1) {
124 if ($seen{$about->[1]+0}++) {
125 $buf .= " $about->[1], which was seen before.\n";
126 } else {
116 $buf .= " $about->[1], which is\n"; 127 $buf .= " $about->[1], which is\n";
117 $track->($about->[1], $depth - 1, $indent + 1); 128 $track->(\$about->[1], $depth - 1, $about == $about[-1] ? "$indent " : "$indent| ");
129 }
118 } else { 130 } else {
119 $buf .= ".\n"; 131 $buf .= ".\n";
120 } 132 }
121 } 133 }
122 } else { 134 } else {
123 $buf .= (" ") x $indent;
124 $buf .= "not found anywhere I looked :(\n"; 135 $buf .= "$indent not found anywhere I looked :(\n";
125 } 136 }
126 } else { 137 } else {
127 $buf .= (" ") x $indent;
128 $buf .= "not referenced within the search depth.\n"; 138 $buf .= "$indent not referenced within the search depth.\n";
129 } 139 }
130 }; 140 };
131 141
132 $buf .= "$_[0] is\n"; 142 $buf .= "$ref is\n";
133 $track->($_[0], $_[1] || 10, 1); 143 $track->(\$ref, $depth || $ENV{PERL_DEVEL_FINDREF_DEPTH} || 10, "");
134 $buf 144 $buf
135} 145}
136 146
137=item @references = Devel::FindRef::find $ref 147=item @references = Devel::FindRef::find $ref
138 148
139Return arrayrefs that contain [$message, $ref] pairs. The message 149Return arrayrefs that contain [$message, $ref] pairs. The message
140describes what kind of reference was found and the C<$ref> is the 150describes what kind of reference was found and the C<$ref> is the
141reference itself, which cna be omitted if C<find> decided to end the 151reference itself, which can be omitted if C<find> decided to end the
142search. 152search. The returned references are all weak references.
143 153
144The C<track> function uses this to find references to the value you are 154The C<track> function uses this to find references to the value you are
145interested in and recurses on the returned references. 155interested in and recurses on the returned references.
146 156
147=cut 157=cut
148 158
149sub find($) { 159sub find($) {
150 my ($about, $excl) = &find_; 160 my ($about, $excl) = &find_;
151 my %excl = map +($_ => 1), @$excl; 161 my %excl = map +($_ => undef), @$excl;
152 grep !$excl{$_->[1] + 0}, @$about 162 grep !exists $excl{$_->[1] + 0}, @$about
153} 163}
154 164
155=item $ref = Devel::FindRef::ref2ptr $ptr 165=item $ref = Devel::FindRef::ptr2ref $integer
156 166
157Sometimes you know (from debugging output) the address of a perl scalar 167Sometimes you know (from debugging output) the address of a perl scalar
158you are interested in. This function can be used to turn the address into 168you are interested in (e.g. C<HASH(0x176ff70)>). This function can be used
159a reference to that scalar. It is quite safe to call on valid addresses, 169to turn the address into a reference to that scalar. It is quite safe to
160but extremely dangerous to call on invalid ones. 170call on valid addresses, but extremely dangerous to call on invalid ones.
171
172 # we know that HASH(0x176ff70) exists, so turn it into a hashref:
173 my $ref_to_hash = Devel::FindRef::ptr2ref 0x176ff70;
161 174
162=back 175=back
176
177=head1 ENVIRONMENT VARIABLES
178
179You can set the environment variable C<PERL_DEVEL_FINDREF_DEPTH> to an
180integer to override the default depth in C<track>. If a call explicitly
181specified a depth it is not overridden.
163 182
164=head1 AUTHOR 183=head1 AUTHOR
165 184
166Marc Lehmann <pcg@goof.com>. 185Marc Lehmann <pcg@goof.com>.
167 186

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines