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 makes DDumper behave like 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 | N | NR | 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         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
114       These can also be passed to import:
115
116         $ 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
131   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
136       Example
137
138         print DPeek "abc\x{0a}de\x{20ac}fg";
139
140         PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
141
142       In void context, "DPeek" prints to "STDERR" plus a newline.
143
144   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
152       Example
153
154         print DDisplay "abc\x{0a}de\x{20ac}fg";
155
156         "abc\nde\x{20ac}fg"
157
158       In void context, "DDisplay" uses "warn" to display the result.
159
160   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
168       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
172       Example
173
174         print DHexDump "abc\x{0a}de\x{20ac}fg";
175
176         0000  61 62 63 0a 64 65 e2 82  ac 66 67                 abc.de...fg
177
178   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
188       Example
189
190         print DPeek for DDual ($!, 1);
191
192       In void context, DDual does the equivalent of
193
194         { 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
203   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
208        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
214                  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
219   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
227       "triplevar" is not exported by default.
228
229       Example:
230
231         DDual Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
232
233         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
239   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
244       Perl itself has "sv_dump", which does something similar, but still
245       prints to STDERR, and only one level deep.
246
247       "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
250       In void context, it behaves exactly like "Perl_sv_dump".
251
252       In scalar context, it returns what "Perl_sv_dump" would have printed.
253
254       The default for the first argument is $_.
255
256       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
260       Example
261
262         print scalar DDump "abc\x{0a}de\x{20ac}fg"
263
264         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
271         my %h = DDump "abc\x{0a}de\x{20ac}fg";
272         print DDumper \%h;
273
274         {   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
288         my %h = DDump {
289             ape => 1,
290             foo => "egg",
291             bar => [ 2, "baz", undef ],
292             }, 1;
293         print DDumper \%h;
294
295         {   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
345   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
349       Example
350
351         my $dump;
352         open my $eh, ">", \$dump;
353         DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
354         close $eh;
355         print $dump;
356
357         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

INTERNALS

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

BUGS

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

SEE ALSO

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

AUTHOR

437       H.Merijn Brand <hmbrand@cpan.org>
438
440       Copyright (C) 2008-2023 H.Merijn Brand
441
442       This library is free software; you can redistribute it and/or modify it
443       under the same terms as Perl itself.
444
445
446
447perl v5.38.0                      2023-07-20                           Peek(3)
Impressum