1Peek(3)               User Contributed Perl Documentation              Peek(3)
2
3
4

NAME

6       Data::Peek - A collection of low-level debug facilities
7

SYNOPSIS

9        use Data::Peek;
10
11        print DDumper \%hash;    # Same syntax as Data::Dumper
12        DTidy { ref => $ref };
13
14        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
20        my $dump = DDump $var;
21        my %hash = DDump \@list;
22        DDump \%hash;
23
24        my %hash = DDump (\%hash, 5);  # dig 5 levels deep
25
26        my $dump;
27        open my $fh, ">", \$dump;
28        DDump_IO ($fh, \%hash, 6);
29        close $fh;
30        print $dump;
31
32        # 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

DESCRIPTION

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
45   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
51           $Data::Dumper::Sortkeys = 1;
52           $Data::Dumper::Indent   = 1;
53
54       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
58         * 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
63       In void context, "DDumper" "warn"'s.
64
65       Example
66
67         $ perl -MDP \
68           -e'DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};'
69
70         {   ape              => 1,
71             bar              => [
72                 2,
73                 'baz',
74                 undef
75                 ],
76             foo              => 'egg'
77             };
78
79   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
85         $ 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
92       If "Data::Peek" is "use"d with import argument ":tidy", this is the
93       default output method for "DDumper".
94
95       If Perl::Tidy is not available, "DTidy" will fallback to "DDumper".
96
97       This idea was shamelessly copied from John McNamara's
98       Data::Dumper::Perltidy.
99
100   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
104         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
112       These can also be passed to import:
113
114         $ 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
129   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
134       Example
135
136         print DPeek "abc\x{0a}de\x{20ac}fg";
137
138         PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
139
140       In void context, "DPeek" prints to "STDERR" plus a newline.
141
142   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
150       Example
151
152         print DDisplay "abc\x{0a}de\x{20ac}fg";
153
154         "abc\nde\x{20ac}fg"
155
156       In void context, "DDisplay" uses "warn" to display the result.
157
158   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
166       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
170       Example
171
172         print DHexDump "abc\x{0a}de\x{20ac}fg";
173
174         0000  61 62 63 0a 64 65 e2 82  ac 66 67                 abc.de...fg
175
176   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
186       Example
187
188         print DPeek for DDual ($!, 1);
189
190       In void context, DDual does the equivalent of
191
192         { 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
201   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
206        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
212                  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
217   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
225       "triplevar" is not exported by default.
226
227       Example:
228
229         print DPeek for DDual
230             Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
231
232         PV("\317\200"\0) [UTF8 "\x{3c0}"]
233         IV(3)
234         NV(3.1415)
235         SV_UNDEF
236         IV(0)
237
238   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
243       Perl itself has "sv_dump", which does something similar, but still
244       prints to STDERR, and only one level deep.
245
246       "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
249       In void context, it behaves exactly like "Perl_sv_dump".
250
251       In scalar context, it returns what "Perl_sv_dump" would have printed.
252
253       The default for the first argument is $_.
254
255       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
259       Example
260
261         print scalar DDump "abc\x{0a}de\x{20ac}fg"
262
263         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
270         my %h = DDump "abc\x{0a}de\x{20ac}fg";
271         print DDumper \%h;
272
273         {   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
287         my %h = DDump {
288             ape => 1,
289             foo => "egg",
290             bar => [ 2, "baz", undef ],
291             }, 1;
292         print DDumper \%h;
293
294         {   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
344   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
348       Example
349
350         my $dump;
351         open my $eh, ">", \$dump;
352         DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
353         close $eh;
354         print $dump;
355
356         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

INTERNALS

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
418   DDump_XS (SV *sv)
419       Base interface to internals for "DDump".
420

BUGS

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
426       Not all types of references are supported.
427
428       No idea how far back this goes in perl support, but Devel::PPPort has
429       proven to be a big help.
430

SEE ALSO

432       Devel::Peek, Data::Dumper, Data::Dump, Devel::Dumpvar,
433       Data::Dump::Streamer, Data::Dumper::Perltidy, Perl::Tidy.
434

AUTHOR

436       H.Merijn Brand <h.m.brand@xs4all.nl>
437
439       Copyright (C) 2008-2018 H.Merijn Brand
440
441       This library is free software; you can redistribute it and/or modify it
442       under the same terms as Perl itself.
443
444
445
446perl v5.30.0                      2019-07-26                           Peek(3)
Impressum