8 use vars
qw( $VERSION @ISA @EXPORT @EXPORT_OK );
10 @ISA = qw( DynaLoader Exporter );
11 @EXPORT = qw( DDumper DPeek DDisplay DDump DDual );
12 @EXPORT_OK = qw( triplevar );
13 $] >= 5.007003 and push @EXPORT, "DDump_IO";
15 bootstrap Data
::Peek
$VERSION;
17 ### ############# DDumper () ##################################################
23 local $Data::Dumper
::Sortkeys
= 1;
24 local $Data::Dumper
::Indent
= 1;
26 my $s = Data
::Dumper
::Dumper
@_;
27 $s =~ s!^(\s*)'([^']*)'\s*=>!sprintf "%s%-16s =>", $1, $2!gme; # Align => '
28 $s =~ s!\bbless\s*\(\s*!bless (!gm and $s =~ s!\s+\)([;,])$!)$1!gm;
29 $s =~ s!^(?= *[]}](?:[;,]|$))! !gm;
30 $s =~ s!^(\s+)!$1$1!gm;
32 defined wantarray or print STDERR
$s;
36 ### ############# DDump () ####################################################
42 $has_perlio = ($Config{useperlio
} || "undef") eq "define";
47 my ($var, $down) = (@_, 0);
50 if ($ref eq "SCALAR" || $ref eq "REF") {
51 my %hash = DDump
($$var, $down);
54 if ($ref eq "ARRAY") {
56 foreach my $list (@
$var) {
57 my %hash = DDump
($list, $down);
58 push @list, { %hash };
64 foreach my $key (sort keys %$var) {
65 $hash{DPeek
($key)} = { DDump
($var->{$key}, $down) };
74 my ($var, $down, $dump, $fh) = (@_, "");
76 if ($has_perlio and open $fh, ">", \
$dump) {
77 #print STDERR "Using DDump_IO\n";
78 DDump_IO
($fh, $var, $down);
82 #print STDERR "Using DDump_XS\n";
83 $dump = DDump_XS
($var);
91 my ($var, $down) = (@_, 0);
92 my @dump = split m/[\r\n]+/, _DDump
($var, wantarray || $down) or return;
96 ($hash{sv
} = $dump[0]) =~ s/^SV\s*=\s*//;
97 m/^\s+(\w+)\s*=\s*(.*)/ and $hash{$1} = $2 for @dump;
99 if (exists $hash{FLAGS
}) {
100 $hash{FLAGS
} =~ tr/()//d;
101 $hash{FLAGS
} = { map { $_ => 1 } split m/,/ => $hash{FLAGS
} };
104 $down && ref $var and
105 $hash{RV
} = _DDump_ref
($var, $down - 1) || $var;
109 my $dump = join "\n", @dump, "";
111 defined wantarray and return $dump;
122 Data::Peek - A collection of low-level debug facilities
128 print DDumper \%hash; # Same syntax as Data::Dumper
131 my ($pv, $iv, $nv, $rv, $magic) = DDual ($var [, 1]);
132 print DPeek for DDual ($!, 1);
133 print DDisplay ("ab\nc\x{20ac}\rdef\n");
135 my $dump = DDump $var;
136 my %hash = DDump \@list;
139 my %hash = DDump (\%hash, 5); # dig 5 levels deep
142 open my $fh, ">", \$dump;
143 DDump_IO ($fh, \%hash, 6);
147 use Data::Peek qw( triplevar );
148 my $tv = triplevar ("\N{GREEK SMALL LETTER PI}", 3, "3.1415");
152 Data::Peek started off as C<DDumper> being a wrapper module over
153 L<Data::Dumper>, but grew out to be a set of low-level data
154 introspection utilities that no other module provided yet, using the
155 lowest level of the perl internals API as possible.
157 =head2 DDumper ($var, ...)
159 Not liking the default output of Data::Dumper, and always feeling the need
160 to set C<$Data::Dumper::Sortkeys = 1;>, and not liking any of the default
161 layouts, this function is just a wrapper around Data::Dumper::Dumper with
162 everything set as I like it.
164 $Data::Dumper::Sortkeys = 1;
165 $Data::Dumper::Indent = 1;
167 And the result is further beautified to meet my needs:
169 * quotation of hash keys has been removed (with the disadvantage
170 that the output might not be parseable again).
171 * arrows for hashes are aligned at 16 (longer keys don't align)
172 * closing braces and brackets are now correctly aligned
174 In void context, C<DDumper ()> prints to STDERR.
178 print DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};
194 Playing with C<sv_dump ()>, I found C<Perl_sv_peek ()>, and it might be
195 very useful for simple checks. If C<$var> is omitted, uses $_.
199 print DPeek "abc\x{0a}de\x{20ac}fg";
201 PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
205 =head2 DDisplay ($var)
207 Show the PV content of a scalar the way perl debugging would have done.
208 UTF-8 detection is on, so this is effectively the same as returning the
209 first part the C<DPeek ()> returns for non-UTF8 PV's or the second part
210 for UTF-8 PV's. C<DDisplay ()> returns the empty string for scalars that
215 print DDisplay "abc\x{0a}de\x{20ac}fg";
219 =head2 my ($pv, $iv, $nv, $rv, $hm) = DDual ($var [, $getmagic])
221 DDual will return the basic elements in a variable, guaranteeing that no
222 conversion takes place. This is very useful for dual-var variables, or
223 when checking is a variable has defined entries for a certain type of
224 scalar. For each String (PV), Integer (IV), Double (NV), and Reference (RV),
225 the current value of C<$var> is returned or undef if it is not set (yet).
226 The 5th element is an indicator if C<$var> has magic, which is B<not> invoked
227 in the returned values, unless explicitly asked for with a true optional
232 print DPeek for DDual ($!, 1);
234 =head2 triplevar ($pv, $iv, $nv)
236 When making C<DDual ()> I wondered if it were possible to create triple-val
237 scalar variables. L<Scalar::Util> already gives us C<dualvar ()>, that creates
238 you a scalar with different numeric and string values that return different
239 values in different context. Not that C<triplevar ()> would be very useful,
240 compared to C<dualvar ()>, but at least this shows that it is possible.
242 C<triplevar ()> is not exported by default.
246 print DPeek for DDual
247 Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
249 PV("\317\200"\0) [UTF8 "\x{3c0}"]
255 =head2 DDump ($var [, $dig_level])
257 A very useful module when debugging is C<Devel::Peek>, but is has one big
258 disadvantage: it only prints to STDERR, which is not very handy when your
259 code wants to inspect variables al a low level.
261 Perl itself has C<sv_dump ()>, which does something similar, but still
262 prints to STDERR, and only one level deep.
264 C<DDump ()> is an attempt to make the innards available to the script level
265 with a reasonable level of compatibility. C<DDump ()> is context sensitive.
267 In void context, it behaves exactly like C<Perl_sv_dump ()>.
269 In scalar context, it returns what C<Perl_sv_dump ()> would have printed.
271 In list context, it returns a hash of the variable's properties. In this mode
272 you can pass an optional second argument that determines the depth of digging.
276 print scalar DDump "abc\x{0a}de\x{20ac}fg"
278 SV = PV(0x723250) at 0x8432b0
280 FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
281 PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
285 my %h = DDump "abc\x{0a}de\x{20ac}fg";
298 PV => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
300 sv => 'PV(0x723250) at 0x8432c0'
306 bar => [ 2, "baz", undef ],
327 sv => 'IV(0x747020) at 0x843a10'
341 sv => 'PVIV(0x7223e0) at 0x843a10'
353 PV => '0x7496c0 "egg"\\0',
355 sv => 'PVIV(0x7223e0) at 0x843a10'
358 sv => 'RV(0x79d058) at 0x843310'
361 =head2 DDump_IO ($io, $var [, $dig_level])
363 A wrapper function around perl's internal C<Perl_do_sv_dump ()>, which
364 makes C<Devel::Peek> completely superfluous. As PerlIO is only available
365 perl version 5.7.3 and up, this function is not available in older perls.
370 open my $eh, ">", \$dump;
371 DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
375 SV = RV(0x79d9e0) at 0x843f00
379 SV = PVHV(0x79c948) at 0x741090
384 ARRAY = 0x748ff0 (0:7, 2:1)
391 Elt "ape" HASH = 0x97623e03
392 SV = RV(0x79d9d8) at 0x8440e0
396 SV = PVAV(0x7264b0) at 0x741470
407 SV = IV(0x7467c8) at 0x7c1aa0
412 SV = IV(0x7467b0) at 0x8440f0
417 SV = IV(0x746810) at 0x75be00
422 SV = IV(0x746d38) at 0x7799d0
426 Elt "3" HASH = 0xa400c7f3
427 SV = IV(0x746fd0) at 0x7200e0
434 C<DDump ()> uses an XS wrapper around C<Perl_sv_dump ()> where the
435 STDERR is temporarily caught to a pipe. The internal XS helper functions
436 are not meant for user space
438 =head2 DDump_XS (SV *sv)
440 Base interface to internals for C<DDump ()>.
444 Windows and AIX might be using a build where not all symbols that were
445 supposed to be exported in the public API are not. Perl_pv_peek () is
448 Not all types of references are supported.
452 No idea how far back this goes in perl support, but Devel::PPPort has
453 proven to be a big help.
457 L<Devel::Peek(3)>, L<Data::Dumper(3)>, L<Data::Dump(3)>,
458 L<Data::Dump::Streamer(3)>
462 H.Merijn Brand <h.m.brand@xs4all.nl>
464 =head1 COPYRIGHT AND LICENSE
466 Copyright (C) 2008-2009 H.Merijn Brand
468 This library is free software; you can redistribute it and/or modify
469 it under the same terms as Perl itself.