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