8 use vars
qw( $VERSION @ISA @EXPORT @EXPORT_OK );
10 @ISA = qw( DynaLoader Exporter );
11 @EXPORT = qw( DDumper DDsort DPeek DDisplay DDump DHexDump DDual DGrow );
12 @EXPORT_OK = qw( triplevar );
13 push @EXPORT, "DDump_IO";
15 bootstrap Data
::Peek
$VERSION;
17 ### ############# DDumper () ##################################################
27 V
=> sub { # Sort by value
29 [ sort { $r->{$a} cmp $r->{$b} } keys %$r ];
31 VN
=> sub { # Sort by value numeric
33 [ sort { $r->{$a} <=> $r->{$b} } keys %$r ];
35 VNR
=> sub { # Sort by value numeric reverse
37 [ sort { $r->{$b} <=> $r->{$a} } keys %$r ];
39 VR
=> sub { # Sort by value reverse
41 [ sort { $r->{$b} cmp $r->{$a} } keys %$r ];
43 R
=> sub { # Sort reverse
45 [ reverse sort keys %$r ];
54 $_sortkeys = exists $sk{$_[0]} ?
$sk{$_[0]} : $_[0];
61 foreach my $p (@exp) {
62 exists $sk{$p} and DDsort
($p), next;
66 __PACKAGE__
->export_to_level (1, @etl);
71 local $Data::Dumper
::Sortkeys
= $_sortkeys;
72 local $Data::Dumper
::Indent
= 1;
73 local $Data::Dumper
::Quotekeys
= 0;
74 local $Data::Dumper
::Deparse
= 1;
75 local $Data::Dumper
::Terse
= 1;
76 local $Data::Dumper
::Useqq
= 0; # I want unicode visible
78 my $s = Data
::Dumper
::Dumper
@_;
79 $s =~ s/^(\s*)(.*?)\s*=>/sprintf "%s%-16s =>", $1, $2/gme; # Align =>
80 $s =~ s/\bbless\s*\(\s*/bless (/gm and $s =~ s/\s+\)([;,])$/)$1/gm;
81 $s =~ s/^(?= *[]}](?:[;,]|$))/ /gm;
82 $s =~ s/^(\s*[{[]) *\n *(?=\S)(?![{[])/$1 /gm;
83 $s =~ s/^(\s+)/$1$1/gm;
85 defined wantarray or warn $s;
89 ### ############# DDump () ####################################################
95 $has_perlio = ($Config{useperlio
} || "undef") eq "define";
100 my (undef, $down) = (@_, 0);
103 if ($ref eq "SCALAR" || $ref eq "REF") {
104 my %hash = DDump
(${$_[0]}, $down);
107 if ($ref eq "ARRAY") {
109 foreach my $list (@
{$_[0]}) {
110 my %hash = DDump
($list, $down);
111 push @list, { %hash };
115 if ($ref eq "HASH") {
117 foreach my $key (sort keys %{$_[0]}) {
118 $hash{DPeek
($key)} = { DDump
($_[0]->{$key}, $down) };
127 my (undef, $down, $dump, $fh) = (@_, "");
129 if ($has_perlio and open $fh, ">", \
$dump) {
130 #print STDERR "Using DDump_IO\n";
131 DDump_IO
($fh, $_[0], $down);
135 #print STDERR "Using DDump_XS\n";
136 $dump = DDump_XS
($_[0]);
144 my (undef, $down) = (@_, 0);
145 my @dump = split m/[\r\n]+/, _DDump
($_[0], wantarray || $down) or return;
149 ($hash{sv
} = $dump[0]) =~ s/^SV\s*=\s*//;
150 m/^\s+(\w+)\s*=\s*(.*)/ and $hash{$1} = $2 for @dump;
152 if (exists $hash{FLAGS
}) {
153 $hash{FLAGS
} =~ tr/()//d;
154 $hash{FLAGS
} = { map { $_ => 1 } split m/,/ => $hash{FLAGS
} };
157 $down && ref $_[0] and
158 $hash{RV
} = _DDump_ref
($_[0], $down - 1) || $_[0];
162 my $dump = join "\n", @dump, "";
164 defined wantarray and return $dump;
174 my $var = @_ ?
$_[0] : $_;
175 defined $var or return;
176 my $str = "$var"; # force stringification
177 for (unpack "(A32)*", unpack "H*", $str) {
178 my @b = unpack "(A2)*", $_;
179 my $out = sprintf "%04x ", $off;
180 $out .= " ".($b[$_]||" ") for 0 .. 7;
182 $out .= " ".($b[$_]||" ") for 8 .. 15;
184 $out .= ($_ < 0x20 || $_ >= 0x7f ?
"." : chr $_) for map { hex $_ } @b;
185 push @out, $out."\n";
189 wantarray and return @out;
191 defined wantarray and return join "", @out;
202 Data::Peek - A collection of low-level debug facilities
208 print DDumper \%hash; # Same syntax as Data::Dumper
211 my ($pv, $iv, $nv, $rv, $magic) = DDual ($var [, 1]);
212 print DPeek for DDual ($!, 1);
213 print DDisplay ("ab\nc\x{20ac}\rdef\n");
214 print DHexDump ("ab\nc\x{20ac}\rdef\n");
216 my $dump = DDump $var;
217 my %hash = DDump \@list;
220 my %hash = DDump (\%hash, 5); # dig 5 levels deep
223 open my $fh, ">", \$dump;
224 DDump_IO ($fh, \%hash, 6);
228 use Data::Peek qw( DGrow triplevar );
229 my $x = ""; DGrow ($x, 10000);
230 my $tv = triplevar ("\N{GREEK SMALL LETTER PI}", 3, "3.1415");
234 Data::Peek started off as C<DDumper> being a wrapper module over
235 L<Data::Dumper>, but grew out to be a set of low-level data
236 introspection utilities that no other module provided yet, using the
237 lowest level of the perl internals API as possible.
239 =head2 DDumper ($var, ...)
241 Not liking the default output of Data::Dumper, and always feeling the need
242 to set C<$Data::Dumper::Sortkeys = 1;>, and not liking any of the default
243 layouts, this function is just a wrapper around Data::Dumper::Dumper with
244 everything set as I like it.
246 $Data::Dumper::Sortkeys = 1;
247 $Data::Dumper::Indent = 1;
249 And the result is further beautified to meet my needs:
251 * quotation of hash keys has been removed (with the disadvantage
252 that the output might not be parseable again).
253 * arrows for hashes are aligned at 16 (longer keys don't align)
254 * closing braces and brackets are now correctly aligned
256 In void context, C<DDumper ()> warn ()'s.
260 print DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};
271 =head2 DDsort ( 0 | 1 | R | V | VR | VN | VNR )
273 Set the hash sort algorithm for DDumper. The default is to sort by key value.
277 R - Reverse sort by key
279 VR - Reverse sort by value
280 VN - Sort by value numerical
281 VNR - Reverse sort by value numerical
283 These can also be passed to import:
285 $ perl -MDP=VNR -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
291 $ perl -MDP=V -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
302 Playing with C<sv_dump ()>, I found C<Perl_sv_peek ()>, and it might be
303 very useful for simple checks. If C<$var> is omitted, uses $_.
307 print DPeek "abc\x{0a}de\x{20ac}fg";
309 PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
311 In void context, C<DPeek ()> prints to C<STDERR> plus a newline.
315 =head2 DDisplay ($var)
317 Show the PV content of a scalar the way perl debugging would have done.
318 UTF-8 detection is on, so this is effectively the same as returning the
319 first part the C<DPeek ()> returns for non-UTF8 PV's or the second part
320 for UTF-8 PV's. C<DDisplay ()> returns the empty string for scalars that
325 print DDisplay "abc\x{0a}de\x{20ac}fg";
331 =head2 DHexDump ($var)
333 Show the (stringified) content of a scalar as a hex-dump. If C<$var>
334 is omitted, C<$_> is dumped. Returns C<undef> or an empty list if
335 C<$var> (or C<$_>) is undefined.
337 In void context, the dump is done to STDERR. In scalar context, the
338 complete dump is returned as a single string. In list context, the dump
339 is returned as lines.
343 print DHexDump "abc\x{0a}de\x{20ac}fg";
345 0000 61 62 63 0a 64 65 e2 82 ac 66 67 abc.de...fg
347 =head2 my ($pv, $iv, $nv, $rv, $hm) = DDual ($var [, $getmagic])
349 DDual will return the basic elements in a variable, guaranteeing that no
350 conversion takes place. This is very useful for dual-var variables, or
351 when checking is a variable has defined entries for a certain type of
352 scalar. For each String (PV), Integer (IV), Double (NV), and Reference (RV),
353 the current value of C<$var> is returned or undef if it is not set (yet).
354 The 5th element is an indicator if C<$var> has magic, which is B<not> invoked
355 in the returned values, unless explicitly asked for with a true optional
360 print DPeek for DDual ($!, 1);
362 In void context, DDual does the equivalent of
364 { my @d = DDual ($!, 1);
367 " PV: ", DPeek ($d[0]), "\n",
368 " IV: ", DPeek ($d[1]), "\n",
369 " NV: ", DPeek ($d[2]), "\n",
370 " RV: ", DPeek ($d[3]), "\n";
373 =head2 my $len = DGrow ($pv, $size)
375 Fastest way to preallocate space for a PV scalar. Returns the allocated
376 length. If $size is smaller than the already allocated space, it will
380 pack => q{my $x = ""; $x = pack "x20000"; $x = "";},
381 op_x => q{my $x = ""; $x = "x" x 20000; $x = "";},
382 grow => q{my $x = ""; DGrow ($x, 20000); $x = "";},
386 op_x 62127/s -- -59% -96%
387 pack 152046/s 145% -- -91%
388 grow 1622943/s 2512% 967% --
391 =head2 my $tp = triplevar ($pv, $iv, $nv)
393 When making C<DDual ()> I wondered if it were possible to create triple-val
394 scalar variables. L<Scalar::Util> already gives us C<dualvar ()>, that creates
395 you a scalar with different numeric and string values that return different
396 values in different context. Not that C<triplevar ()> would be very useful,
397 compared to C<dualvar ()>, but at least this shows that it is possible.
399 C<triplevar ()> is not exported by default.
403 print DPeek for DDual
404 Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
406 PV("\317\200"\0) [UTF8 "\x{3c0}"]
412 =head2 DDump ($var [, $dig_level])
414 A very useful module when debugging is C<Devel::Peek>, but is has one big
415 disadvantage: it only prints to STDERR, which is not very handy when your
416 code wants to inspect variables at a low level.
418 Perl itself has C<sv_dump ()>, which does something similar, but still
419 prints to STDERR, and only one level deep.
421 C<DDump ()> is an attempt to make the innards available to the script level
422 with a reasonable level of compatibility. C<DDump ()> is context sensitive.
424 In void context, it behaves exactly like C<Perl_sv_dump ()>.
426 In scalar context, it returns what C<Perl_sv_dump ()> would have printed.
428 In list context, it returns a hash of the variable's properties. In this mode
429 you can pass an optional second argument that determines the depth of digging.
433 print scalar DDump "abc\x{0a}de\x{20ac}fg"
435 SV = PV(0x723250) at 0x8432b0
437 FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
438 PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
442 my %h = DDump "abc\x{0a}de\x{20ac}fg";
454 PV => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
456 sv => 'PV(0x723250) at 0x8432c0'
462 bar => [ 2, "baz", undef ],
482 sv => 'IV(0x747020) at 0x843a10'
496 sv => 'PVIV(0x7223e0) at 0x843a10'
508 PV => '0x7496c0 "egg"\\0',
510 sv => 'PVIV(0x7223e0) at 0x843a10'
513 sv => 'RV(0x79d058) at 0x843310'
516 =head2 DDump_IO ($io, $var [, $dig_level])
518 A wrapper function around perl's internal C<Perl_do_sv_dump ()>, which
519 makes C<Devel::Peek> completely superfluous.
524 open my $eh, ">", \$dump;
525 DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
529 SV = RV(0x79d9e0) at 0x843f00
533 SV = PVHV(0x79c948) at 0x741090
538 ARRAY = 0x748ff0 (0:7, 2:1)
545 Elt "ape" HASH = 0x97623e03
546 SV = RV(0x79d9d8) at 0x8440e0
550 SV = PVAV(0x7264b0) at 0x741470
561 SV = IV(0x7467c8) at 0x7c1aa0
566 SV = IV(0x7467b0) at 0x8440f0
571 SV = IV(0x746810) at 0x75be00
576 SV = IV(0x746d38) at 0x7799d0
580 Elt "3" HASH = 0xa400c7f3
581 SV = IV(0x746fd0) at 0x7200e0
588 C<DDump ()> uses an XS wrapper around C<Perl_sv_dump ()> where the
589 STDERR is temporarily caught to a pipe. The internal XS helper functions
590 are not meant for user space
592 =head2 DDump_XS (SV *sv)
594 Base interface to internals for C<DDump ()>.
598 Windows and AIX might be using a build where not all symbols that were
599 supposed to be exported in the public API are not. Perl_pv_peek () is
602 Not all types of references are supported.
604 No idea how far back this goes in perl support, but Devel::PPPort has
605 proven to be a big help.
609 L<Devel::Peek>, L<Data::Dumper>, L<Data::Dump>, L<Devel::Dumpvar>,
610 L<Data::Dump::Streamer>
614 H.Merijn Brand <h.m.brand@xs4all.nl>
616 =head1 COPYRIGHT AND LICENSE
618 Copyright (C) 2008-2010 H.Merijn Brand
620 This library is free software; you can redistribute it and/or modify
621 it under the same terms as Perl itself.