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
132 very 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
147 for UTF-8 PV's. "DDisplay ()" returns the empty string for scalars that
148 no have a valid PV.
149 Example
151 print DDisplay "abc\x{0a}de\x{20ac}fg";
153 "abc\nde\x{20ac}fg"
155 DHexDump
157 DHexDump ($var)
158 DHexDump ($var, $length)
159 Show the (stringified) content of a scalar as a hex-dump. If $var is
160 omitted, $_ is dumped. Returns "undef" or an empty list if $var (or $_)
161 is undefined. If $length is given and is lower than the length of the
162 stringified $var, only <$length> bytes are dumped.
163 In void context, the dump is done to STDERR. In scalar context, the
165 complete dump is returned as a single string. In list context, the dump
166 is returned as lines.
167 Example
169 print DHexDump "abc\x{0a}de\x{20ac}fg";
171 0000 61 62 63 0a 64 65 e2 82 ac 66 67 abc.de...fg
173 my ($pv, $iv, $nv, $rv, $hm) = DDual ($var [, $getmagic])
175 DDual will return the basic elements in a variable, guaranteeing that
176 no conversion takes place. This is very useful for dual-var variables,
177 or when checking is a variable has defined entries for a certain type
178 of scalar. For each String (PV), Integer (IV), Double (NV), and
179 Reference (RV), the current value of $var is returned or undef if it is
180 not set (yet). The 5th element is an indicator if $var has magic,
181 which is not invoked in the returned values, unless explicitly asked
182 for with a true optional second argument.
183 Example
185 print DPeek for DDual ($!, 1);
187 In void context, DDual does the equivalent of
189 { my @d = DDual ($!, 1);
191 print STDERR
192 DPeek ($!), "\n",
193 " PV: ", DPeek ($d[0]), "\n",
194 " IV: ", DPeek ($d[1]), "\n",
195 " NV: ", DPeek ($d[2]), "\n",
196 " RV: ", DPeek ($d[3]), "\n";
197 }
198 my $len = DGrow ($pv, $size)
200 Fastest way to preallocate space for a PV scalar. Returns the allocated
201 length. If $size is smaller than the already allocated space, it will
202 not shrink.
203 cmpthese (-2, {
205 pack => q{my $x = ""; $x = pack "x20000"; $x = "";},
206 op_x => q{my $x = ""; $x = "x" x 20000; $x = "";},
207 grow => q{my $x = ""; DGrow ($x, 20000); $x = "";},
208 });
209 Rate op_x pack grow 5.8.9 5.10.1 5.12.4 5.14.2
211 op_x 62127/s -- -59% -96% 118606/s 119730/s 352255/s 362605/s
212 pack 152046/s 145% -- -91% 380075/s 355666/s 347247/s 387349/s
213 grow 1622943/s 2512% 967% -- 2818380/s 2918783/s 2672340/s 2886787/s
214 my $tp = triplevar ($pv, $iv, $nv)
216 When making "DDual ()" I wondered if it were possible to create triple-
217 val scalar variables. Scalar::Util already gives us "dualvar ()", that
218 creates you a scalar with different numeric and string values that
219 return different values in different context. Not that "triplevar ()"
220 would be very useful, compared to "dualvar ()", but at least this shows
221 that it is possible.
222 "triplevar ()" is not exported by default.
224 Example:
226 print DPeek for DDual
228 Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
229 PV("\317\200"\0) [UTF8 "\x{3c0}"]
231 IV(3)
232 NV(3.1415)
233 SV_UNDEF
234 IV(0)
235 DDump ($var [, $dig_level])
237 A very useful module when debugging is "Devel::Peek", but is has one
238 big disadvantage: it only prints to STDERR, which is not very handy
239 when your code wants to inspect variables at a low level.
240 Perl itself has "sv_dump ()", which does something similar, but still
242 prints to STDERR, and only one level deep.
243 "DDump ()" is an attempt to make the innards available to the script
245 level with a reasonable level of compatibility. "DDump ()" is context
246 sensitive.
247 In void context, it behaves exactly like "Perl_sv_dump ()".
249 In scalar context, it returns what "Perl_sv_dump ()" would have
251 printed.
252 In list context, it returns a hash of the variable's properties. In
254 this mode you can pass an optional second argument that determines the
255 depth of digging.
256 Example
258 print scalar DDump "abc\x{0a}de\x{20ac}fg"
260 SV = PV(0x723250) at 0x8432b0
262 REFCNT = 1
263 FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
264 PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
265 CUR = 11
266 LEN = 16
267 my %h = DDump "abc\x{0a}de\x{20ac}fg";
269 print DDumper \%h;
270 { CUR => '11',
272 FLAGS => {
273 PADBUSY => 1,
274 PADMY => 1,
275 POK => 1,
276 UTF8 => 1,
277 pPOK => 1
278 },
279 LEN => '16',
280 PV => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
281 REFCNT => '1',
282 sv => 'PV(0x723250) at 0x8432c0'
283 };
284 my %h = DDump {
286 ape => 1,
287 foo => "egg",
288 bar => [ 2, "baz", undef ],
289 }, 1;
290 print DDumper \%h;
291 { FLAGS => {
293 PADBUSY => 1,
294 PADMY => 1,
295 ROK => 1
296 },
297 REFCNT => '1',
298 RV => {
299 PVIV("ape") => {
300 FLAGS => {
301 IOK => 1,
302 PADBUSY => 1,
303 PADMY => 1,
304 pIOK => 1
305 },
306 IV => '1',
307 REFCNT => '1',
308 sv => 'IV(0x747020) at 0x843a10'
309 },
310 PVIV("bar") => {
311 CUR => '0',
312 FLAGS => {
313 PADBUSY => 1,
314 PADMY => 1,
315 ROK => 1
316 },
317 IV => '1',
318 LEN => '0',
319 PV => '0x720210 ""',
320 REFCNT => '1',
321 RV => '0x720210',
322 sv => 'PVIV(0x7223e0) at 0x843a10'
323 },
324 PVIV("foo") => {
325 CUR => '3',
326 FLAGS => {
327 PADBUSY => 1,
328 PADMY => 1,
329 POK => 1,
330 pPOK => 1
331 },
332 IV => '1',
333 LEN => '8',
334 PV => '0x7496c0 "egg"\\0',
335 REFCNT => '1',
336 sv => 'PVIV(0x7223e0) at 0x843a10'
337 }
338 },
339 sv => 'RV(0x79d058) at 0x843310'
340 };
341 DDump_IO ($io, $var [, $dig_level])
343 A wrapper function around perl's internal "Perl_do_sv_dump ()", which
344 makes "Devel::Peek" completely superfluous.
345 Example
347 my $dump;
349 open my $eh, ">", \$dump;
350 DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
351 close $eh;
352 print $dump;
353 SV = RV(0x79d9e0) at 0x843f00
355 REFCNT = 1
356 FLAGS = (TEMP,ROK)
357 RV = 0x741090
358 SV = PVHV(0x79c948) at 0x741090
359 REFCNT = 1
360 FLAGS = (SHAREKEYS)
361 IV = 2
362 NV = 0
363 ARRAY = 0x748ff0 (0:7, 2:1)
364 hash quality = 62.5%
365 KEYS = 2
366 FILL = 1
367 MAX = 7
368 RITER = -1
369 EITER = 0x0
370 Elt "ape" HASH = 0x97623e03
371 SV = RV(0x79d9d8) at 0x8440e0
372 REFCNT = 1
373 FLAGS = (ROK)
374 RV = 0x741470
375 SV = PVAV(0x7264b0) at 0x741470
376 REFCNT = 2
377 FLAGS = ()
378 IV = 0
379 NV = 0
380 ARRAY = 0x822f70
381 FILL = 3
382 MAX = 3
383 ARYLEN = 0x0
384 FLAGS = (REAL)
385 Elt No. 0
386 SV = IV(0x7467c8) at 0x7c1aa0
387 REFCNT = 1
388 FLAGS = (IOK,pIOK)
389 IV = 5
390 Elt No. 1
391 SV = IV(0x7467b0) at 0x8440f0
392 REFCNT = 1
393 FLAGS = (IOK,pIOK)
394 IV = 6
395 Elt No. 2
396 SV = IV(0x746810) at 0x75be00
397 REFCNT = 1
398 FLAGS = (IOK,pIOK)
399 IV = 7
400 Elt No. 3
401 SV = IV(0x746d38) at 0x7799d0
402 REFCNT = 1
403 FLAGS = (IOK,pIOK)
404 IV = 8
405 Elt "3" HASH = 0xa400c7f3
406 SV = IV(0x746fd0) at 0x7200e0
407 REFCNT = 1
408 FLAGS = (IOK,pIOK)
409 IV = 4
410
412 "DDump ()" uses an XS wrapper around "Perl_sv_dump ()" where the STDERR
413 is temporarily caught to a pipe. The internal XS helper functions are
414 not meant for user space
415 DDump_XS (SV *sv)
417 Base interface to internals for "DDump ()".
418
420 Windows and AIX might be using a build where not all symbols that were
421 supposed to be exported in the public API are not. Perl_pv_peek () is
422 one of them.
423 Not all types of references are supported.
425 No idea how far back this goes in perl support, but Devel::PPPort has
427 proven to be a big help.
428
430 Devel::Peek, Data::Dumper, Data::Dump, Devel::Dumpvar,
431 Data::Dump::Streamer, Data::Dumper::Perltidy, Perl::Tidy.
432
434 H.Merijn Brand <h.m.brand@xs4all.nl>
435
437 Copyright (C) 2008-2012 H.Merijn Brand
438 This library is free software; you can redistribute it and/or modify it
440 under the same terms as Perl itself.
441perl v5.16.3 2012-04-16 Peek(3)