1Peek(3) User Contributed Perl Documentation Peek(3)
2
6 Data::Peek - A collection of low-level debug facilities
7
9 use Data::Peek;
10 print DDumper \%hash; # Same syntax as Data::Dumper
12 DTidy { ref => $ref };
13 print DPeek \$var;
15 my ($pv, $iv, $nv, $rv, $magic) = DDual ($var [, 1]);
16 print DPeek for DDual ($!, 1);
17 print DDisplay ("ab\nc\x{20ac}\rdef\n");
18 print DHexDump ("ab\nc\x{20ac}\rdef\n");
19 my $dump = DDump $var;
21 my %hash = DDump \@list;
22 DDump \%hash;
23 my %hash = DDump (\%hash, 5); # dig 5 levels deep
25 my $dump;
27 open my $fh, ">", \$dump;
28 DDump_IO ($fh, \%hash, 6);
29 close $fh;
30 print $dump;
31 # Imports
33 use Data::Peek qw( :tidy VNR DGrow triplevar );
34 my $x = ""; DGrow ($x, 10000);
35 my $tv = triplevar ("\N{GREEK SMALL LETTER PI}", 3, "3.1415");
36 DDsort ("R");
37 DDumper [ $x ]; # use of :tidy make DDumper behave as DTidy
38
40 Data::Peek started off as "DDumper" being a wrapper module over
41 Data::Dumper, but grew out to be a set of low-level data introspection
42 utilities that no other module provided yet, using the lowest level of
43 the perl internals API as possible.
44 DDumper ($var, ...)
46 Not liking the default output of Data::Dumper, and always feeling the
47 need to set "$Data::Dumper::Sortkeys = 1;", and not liking any of the
48 default layouts, this function is just a wrapper around
49 Data::Dumper::Dumper with everything set as I like it.
50 $Data::Dumper::Sortkeys = 1;
52 $Data::Dumper::Indent = 1;
53 If "Data::Peek" is "use"d with import argument ":tidy", the result is
55 formatted according to Perl::Tidy, see DTidy below, otherwise the
56 result is further beautified to meet my needs:
57 * quotation of hash keys has been removed (with the disadvantage
59 that the output might not be parseable again).
60 * arrows for hashes are aligned at 16 (longer keys don't align)
61 * closing braces and brackets are now correctly aligned
62 In void context, "DDumper" "warn"'s.
64 Example
66 $ perl -MDP \
68 -e'DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};'
69 { ape => 1,
71 bar => [
72 2,
73 'baz',
74 undef
75 ],
76 foo => 'egg'
77 };
78 DTidy ($var, ...)
80 "DTidy" is an alternative to "DDumper", where the output of "DDumper"
81 is formatted using "Perl::Tidy" (if available) according to your
82 ".perltidyrc" instead of the default behavior, maybe somewhat like
83 (YMMV):
84 $ perl -MDP=:tidy \
86 -we'DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};'
87 { 'ape' => 1,
88 'bar' => [2, 'baz', undef],
89 'foo' => 'egg'
90 }
91 If "Data::Peek" is "use"d with import argument ":tidy", this is the
93 default output method for "DDumper".
94 If Perl::Tidy is not available, "DTidy" will fallback to "DDumper".
96 This idea was shamelessly copied from John McNamara's
98 Data::Dumper::Perltidy.
99 DDsort ( 0 | 1 | R | V | VR | VN | VNR )
101 Set the hash sort algorithm for DDumper. The default is to sort by key
102 value.
103 0 - Do not sort
105 1 - Sort by key
106 R - Reverse sort by key
107 V - Sort by value
108 VR - Reverse sort by value
109 VN - Sort by value numerical
110 VNR - Reverse sort by value numerical
111 These can also be passed to import:
113 $ perl -MDP=VNR \
115 -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
116 { gum => 13,
117 zap => 3,
118 bar => 2,
119 foo => 1
120 };
121 $ perl -MDP=V \
122 -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
123 { foo => 1,
124 gum => 13,
125 bar => 2,
126 zap => 3
127 };
128 DPeek
130 DPeek ($var)
131 Playing with "sv_dump", I found "Perl_sv_peek", and it might be very
132 useful for simple checks. If $var is omitted, uses $_.
133 Example
135 print DPeek "abc\x{0a}de\x{20ac}fg";
137 PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
139 In void context, "DPeek" prints to "STDERR" plus a newline.
141 DDisplay
143 DDisplay ($var)
144 Show the PV content of a scalar the way perl debugging would have done.
145 UTF-8 detection is on, so this is effectively the same as returning the
146 first part the "DPeek" returns for non-UTF8 PV's or the second part for
147 UTF-8 PV's. "DDisplay" returns the empty string for scalars that no
148 have a valid PV.
149 Example
151 print DDisplay "abc\x{0a}de\x{20ac}fg";
153 "abc\nde\x{20ac}fg"
155 In void context, "DDisplay" uses "warn" to display the result.
157 DHexDump
159 DHexDump ($var)
160 DHexDump ($var, $length)
161 Show the (stringified) content of a scalar as a hex-dump. If $var is
162 omitted, $_ is dumped. Returns "undef" or an empty list if $var (or $_)
163 is undefined. If $length is given and is lower than the length of the
164 stringified $var, only <$length> bytes are dumped.
165 In void context, the dump is done to STDERR. In scalar context, the
167 complete dump is returned as a single string. In list context, the dump
168 is returned as lines.
169 Example
171 print DHexDump "abc\x{0a}de\x{20ac}fg";
173 0000 61 62 63 0a 64 65 e2 82 ac 66 67 abc.de...fg
175 my ($pv, $iv, $nv, $rv, $hm) = DDual ($var [, $getmagic])
177 DDual will return the basic elements in a variable, guaranteeing that
178 no conversion takes place. This is very useful for dual-var variables,
179 or when checking is a variable has defined entries for a certain type
180 of scalar. For each String (PV), Integer (IV), Double (NV), and
181 Reference (RV), the current value of $var is returned or undef if it is
182 not set (yet). The 5th element is an indicator if $var has magic,
183 which is not invoked in the returned values, unless explicitly asked
184 for with a true optional second argument.
185 Example
187 print DPeek for DDual ($!, 1);
189 In void context, DDual does the equivalent of
191 { my @d = DDual ($!, 1);
193 print STDERR
194 DPeek ($!), "\n",
195 " PV: ", DPeek ($d[0]), "\n",
196 " IV: ", DPeek ($d[1]), "\n",
197 " NV: ", DPeek ($d[2]), "\n",
198 " RV: ", DPeek ($d[3]), "\n";
199 }
200 my $len = DGrow ($pv, $size)
202 Fastest way to preallocate space for a PV scalar. Returns the allocated
203 length. If $size is smaller than the already allocated space, it will
204 not shrink.
205 cmpthese (-2, {
207 pack => q{my $x = ""; $x = pack "x20000"; $x = "";},
208 op_x => q{my $x = ""; $x = "x" x 20000; $x = "";},
209 grow => q{my $x = ""; DGrow ($x, 20000); $x = "";},
210 });
211 Rate op_x pack grow 5.8.9 5.10.1 5.12.4 5.14.2
213 op_x 62127/s -- -59% -96% 118606/s 119730/s 352255/s 362605/s
214 pack 152046/s 145% -- -91% 380075/s 355666/s 347247/s 387349/s
215 grow 1622943/s 2512% 967% -- 2818380/s 2918783/s 2672340/s 2886787/s
216 my $tp = triplevar ($pv, $iv, $nv)
218 When making "DDual" I wondered if it were possible to create triple-val
219 scalar variables. Scalar::Util already gives us "dualvar", that creates
220 you a scalar with different numeric and string values that return
221 different values in different context. Not that "triplevar" would be
222 very useful, compared to "dualvar", but at least this shows that it is
223 possible.
224 "triplevar" is not exported by default.
226 Example:
228 print DPeek for DDual
230 Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
231 PV("\317\200"\0) [UTF8 "\x{3c0}"]
233 IV(3)
234 NV(3.1415)
235 SV_UNDEF
236 IV(0)
237 DDump ([$var [, $dig_level]])
239 A very useful module when debugging is "Devel::Peek", but is has one
240 big disadvantage: it only prints to STDERR, which is not very handy
241 when your code wants to inspect variables at a low level.
242 Perl itself has "sv_dump", which does something similar, but still
244 prints to STDERR, and only one level deep.
245 "DDump" is an attempt to make the innards available to the script level
247 with a reasonable level of compatibility. "DDump" is context sensitive.
248 In void context, it behaves exactly like "Perl_sv_dump".
250 In scalar context, it returns what "Perl_sv_dump" would have printed.
252 The default for the first argument is $_.
254 In list context, it returns a hash of the variable's properties. In
256 this mode you can pass an optional second argument that determines the
257 depth of digging.
258 Example
260 print scalar DDump "abc\x{0a}de\x{20ac}fg"
262 SV = PV(0x723250) at 0x8432b0
264 REFCNT = 1
265 FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
266 PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
267 CUR = 11
268 LEN = 16
269 my %h = DDump "abc\x{0a}de\x{20ac}fg";
271 print DDumper \%h;
272 { CUR => '11',
274 FLAGS => {
275 PADBUSY => 1,
276 PADMY => 1,
277 POK => 1,
278 UTF8 => 1,
279 pPOK => 1
280 },
281 LEN => '16',
282 PV => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
283 REFCNT => '1',
284 sv => 'PV(0x723250) at 0x8432c0'
285 };
286 my %h = DDump {
288 ape => 1,
289 foo => "egg",
290 bar => [ 2, "baz", undef ],
291 }, 1;
292 print DDumper \%h;
293 { FLAGS => {
295 PADBUSY => 1,
296 PADMY => 1,
297 ROK => 1
298 },
299 REFCNT => '1',
300 RV => {
301 PVIV("ape") => {
302 FLAGS => {
303 IOK => 1,
304 PADBUSY => 1,
305 PADMY => 1,
306 pIOK => 1
307 },
308 IV => '1',
309 REFCNT => '1',
310 sv => 'IV(0x747020) at 0x843a10'
311 },
312 PVIV("bar") => {
313 CUR => '0',
314 FLAGS => {
315 PADBUSY => 1,
316 PADMY => 1,
317 ROK => 1
318 },
319 IV => '1',
320 LEN => '0',
321 PV => '0x720210 ""',
322 REFCNT => '1',
323 RV => '0x720210',
324 sv => 'PVIV(0x7223e0) at 0x843a10'
325 },
326 PVIV("foo") => {
327 CUR => '3',
328 FLAGS => {
329 PADBUSY => 1,
330 PADMY => 1,
331 POK => 1,
332 pPOK => 1
333 },
334 IV => '1',
335 LEN => '8',
336 PV => '0x7496c0 "egg"\\0',
337 REFCNT => '1',
338 sv => 'PVIV(0x7223e0) at 0x843a10'
339 }
340 },
341 sv => 'RV(0x79d058) at 0x843310'
342 };
343 DDump_IO ($io, $var [, $dig_level])
345 A wrapper function around perl's internal "Perl_do_sv_dump", which
346 makes "Devel::Peek" completely superfluous.
347 Example
349 my $dump;
351 open my $eh, ">", \$dump;
352 DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
353 close $eh;
354 print $dump;
355 SV = RV(0x79d9e0) at 0x843f00
357 REFCNT = 1
358 FLAGS = (TEMP,ROK)
359 RV = 0x741090
360 SV = PVHV(0x79c948) at 0x741090
361 REFCNT = 1
362 FLAGS = (SHAREKEYS)
363 IV = 2
364 NV = 0
365 ARRAY = 0x748ff0 (0:7, 2:1)
366 hash quality = 62.5%
367 KEYS = 2
368 FILL = 1
369 MAX = 7
370 RITER = -1
371 EITER = 0x0
372 Elt "ape" HASH = 0x97623e03
373 SV = RV(0x79d9d8) at 0x8440e0
374 REFCNT = 1
375 FLAGS = (ROK)
376 RV = 0x741470
377 SV = PVAV(0x7264b0) at 0x741470
378 REFCNT = 2
379 FLAGS = ()
380 IV = 0
381 NV = 0
382 ARRAY = 0x822f70
383 FILL = 3
384 MAX = 3
385 ARYLEN = 0x0
386 FLAGS = (REAL)
387 Elt No. 0
388 SV = IV(0x7467c8) at 0x7c1aa0
389 REFCNT = 1
390 FLAGS = (IOK,pIOK)
391 IV = 5
392 Elt No. 1
393 SV = IV(0x7467b0) at 0x8440f0
394 REFCNT = 1
395 FLAGS = (IOK,pIOK)
396 IV = 6
397 Elt No. 2
398 SV = IV(0x746810) at 0x75be00
399 REFCNT = 1
400 FLAGS = (IOK,pIOK)
401 IV = 7
402 Elt No. 3
403 SV = IV(0x746d38) at 0x7799d0
404 REFCNT = 1
405 FLAGS = (IOK,pIOK)
406 IV = 8
407 Elt "3" HASH = 0xa400c7f3
408 SV = IV(0x746fd0) at 0x7200e0
409 REFCNT = 1
410 FLAGS = (IOK,pIOK)
411 IV = 4
412
414 "DDump" uses an XS wrapper around "Perl_sv_dump" where the STDERR is
415 temporarily caught to a pipe. The internal XS helper functions are not
416 meant for user space
417 DDump_XS (SV *sv)
419 Base interface to internals for "DDump".
420
422 Windows and AIX might be using a build where not all symbols that were
423 supposed to be exported in the public API are not. "Perl_pv_peek" is
424 one of them.
425 Not all types of references are supported.
427 No idea how far back this goes in perl support, but Devel::PPPort has
429 proven to be a big help.
430
432 Devel::Peek, Data::Dumper, Data::Dump, Devel::Dumpvar,
433 Data::Dump::Streamer, Data::Dumper::Perltidy, Perl::Tidy.
434
436 H.Merijn Brand <h.m.brand@xs4all.nl>
437
439 Copyright (C) 2008-2018 H.Merijn Brand
440 This library is free software; you can redistribute it and/or modify it
442 under the same terms as Perl itself.
443perl v5.28.0 2018-02-26 Peek(3)