NAME
Data::Peek - A collection of low-level debug facilities
SYNOPSIS
use Data::Peek;
print DDumper \%hash; # Same syntax as Data::Dumper
print DPeek \$var;
my ($pv, $iv, $nv, $rv, $magic) = DDual ($var [, 1]);
print DPeek for DDual ($!, 1);
my $dump = DDump $var;
my %hash = DDump \@list;
DDump \%hash;
my %hash = DDump (\%hash, 5); # dig 5 levels deep
my $dump;
open my $fh, ">", \$dump;
DDump_IO ($fh, \%hash, 6);
close $fh;
print $dump;DESCRIPTION
Data::Peek started off as DDumper being a wrapper module over Data::Dumper, but grew out to be a set of low-level data introspection utilities that no other module provided yet, using the lowest level of the perl internals API as possible.
DDumper ($var, ...)
Not liking the default output of Data::Dumper, and always feeling the need to set $Data::Dumper::Sortkeys = 1;, and not liking any of the default layouts, this function is just a wrapper around Data::Dumper::Dumper with everything set as I like it.
$Data::Dumper::Sortkeys = 1;
$Data::Dumper::Indent = 1;And the result is further beautified to meet my needs:
* quotation of hash keys has been removed (with the disadvantage
that the output might not be parseable again).
* arrows for hashes are aligned at 16 (longer keys don't align)
* closing braces and brackets are now correctly alignedIn void context, DDumper () prints to STDERR.
Example
print DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};
$VAR1 = {
ape => 1,
bar => [
2,
'baz',
undef
],
foo => 'egg'
};DPeek
DPeek ($var)
Playing with sv_dump (), I found Perl_sv_peek (), and it might be very useful for simple checks. If $var is omitted, uses $_.
Example
print DPeek "abc\x{0a}de\x{20ac}fg";
PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]DDual ($var [, $getmagic])
DDual will return the basic elements in a variable, guaranteeing that no conversion takes place. This is very useful for dual-var variables, or when checking is a variable has defined entries for a certain type of scalar. For each Integer (IV), Double (NV), String (PV), and Reference (RV), the current value of $var is returned or undef if it is not set (yet). The 5th element is an indicator if $var has magic, which is not invoked in the returned values, unless explicitly asked for with a true optional second argument.
Example
print DPeek for DDual ($!, 1);DDump ($var [, $dig_level])
A very useful module when debugging is Devel::Peek, but is has one big disadvantage: it only prints to STDERR, which is not very handy when your code wants to inspect variables al a low level.
Perl itself has sv_dump (), which does something similar, but still prints to STDERR, and only one level deep.
DDump () is an attempt to make the innards available to the script level with a reasonable level of compatibility. DDump () is context sensitive.
In void context, it behaves exactly like Perl_sv_dump ().
In scalar context, it returns what Perl_sv_dump () would have printed.
In list context, it returns a hash of the variable's properties. In this mode you can pass an optional second argument that determines the depth of digging.
Example
print scalar DDump "abc\x{0a}de\x{20ac}fg"
SV = PV(0x723250) at 0x8432b0
REFCNT = 1
FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
CUR = 11
LEN = 16
my %h = DDump "abc\x{0a}de\x{20ac}fg";
print DDumper \%h;
$VAR1 = {
CUR => '11',
FLAGS => {
PADBUSY => 1,
PADMY => 1,
POK => 1,
UTF8 => 1,
pPOK => 1
},
LEN => '16',
PV => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
REFCNT => '1',
sv => 'PV(0x723250) at 0x8432c0'
};
my %h = DDump {
ape => 1,
foo => "egg",
bar => [ 2, "baz", undef ],
}, 1;
print DDumper \%h;
$VAR1 = {
FLAGS => {
PADBUSY => 1,
PADMY => 1,
ROK => 1
},
REFCNT => '1',
RV => {
PVIV("ape") => {
FLAGS => {
IOK => 1,
PADBUSY => 1,
PADMY => 1,
pIOK => 1
},
IV => '1',
REFCNT => '1',
sv => 'IV(0x747020) at 0x843a10'
},
PVIV("bar") => {
CUR => '0',
FLAGS => {
PADBUSY => 1,
PADMY => 1,
ROK => 1
},
IV => '1',
LEN => '0',
PV => '0x720210 ""',
REFCNT => '1',
RV => '0x720210',
sv => 'PVIV(0x7223e0) at 0x843a10'
},
PVIV("foo") => {
CUR => '3',
FLAGS => {
PADBUSY => 1,
PADMY => 1,
POK => 1,
pPOK => 1
},
IV => '1',
LEN => '8',
PV => '0x7496c0 "egg"\\0',
REFCNT => '1',
sv => 'PVIV(0x7223e0) at 0x843a10'
}
},
sv => 'RV(0x79d058) at 0x843310'
};DDump_IO ($io, $var [, $dig_level])
A wrapper function around perl's internal Perl_do_sv_dump (), which makes Devel::Peek completely superfluous. As PerlIO is only available perl version 5.7.3 and up, this function is not available in older perls.
Example
my $dump;
open my $eh, ">", \$dump;
DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
close $eh;
print $dump;
SV = RV(0x79d9e0) at 0x843f00
REFCNT = 1
FLAGS = (TEMP,ROK)
RV = 0x741090
SV = PVHV(0x79c948) at 0x741090
REFCNT = 1
FLAGS = (SHAREKEYS)
IV = 2
NV = 0
ARRAY = 0x748ff0 (0:7, 2:1)
hash quality = 62.5%
KEYS = 2
FILL = 1
MAX = 7
RITER = -1
EITER = 0x0
Elt "ape" HASH = 0x97623e03
SV = RV(0x79d9d8) at 0x8440e0
REFCNT = 1
FLAGS = (ROK)
RV = 0x741470
SV = PVAV(0x7264b0) at 0x741470
REFCNT = 2
FLAGS = ()
IV = 0
NV = 0
ARRAY = 0x822f70
FILL = 3
MAX = 3
ARYLEN = 0x0
FLAGS = (REAL)
Elt No. 0
SV = IV(0x7467c8) at 0x7c1aa0
REFCNT = 1
FLAGS = (IOK,pIOK)
IV = 5
Elt No. 1
SV = IV(0x7467b0) at 0x8440f0
REFCNT = 1
FLAGS = (IOK,pIOK)
IV = 6
Elt No. 2
SV = IV(0x746810) at 0x75be00
REFCNT = 1
FLAGS = (IOK,pIOK)
IV = 7
Elt No. 3
SV = IV(0x746d38) at 0x7799d0
REFCNT = 1
FLAGS = (IOK,pIOK)
IV = 8
Elt "3" HASH = 0xa400c7f3
SV = IV(0x746fd0) at 0x7200e0
REFCNT = 1
FLAGS = (IOK,pIOK)
IV = 4INTERNALS
DDump () uses an XS wrapper around Perl_sv_dump () where the STDERR is temporarily caught to a pipe. The internal XS helper functions are not meant for user space
DDump_XS (SV *sv)
Base interface to internals for DDump ().
BUGS
Not all types of references are supported.
It might crash.
No idea how far back this goes in perl support.
SEE ALSO
Devel::Peek(3), Data::Dumper(3), Data::Dump(3), Data::Dump::Streamer(3)
AUTHOR
H.Merijn Brand <h.m.brand@xs4all.nl>
COPYRIGHT AND LICENSE
Copyright (C) 2008-2008 H.Merijn Brand
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.