Data::Peek.3pm

Langue: en

Autres versions - même langue

Version: 2010-02-14 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

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

SYNOPSIS

  use Data::Peek;
 
  print DDumper \%hash;    # Same syntax as Data::Dumper
 
  print DPeek \$var;
  my ($pv, $iv, $nv, $rv, $magic) = DDual ($var [, 1]);
  print DPeek for DDual ($!, 1);
  print DDisplay ("ab\nc\x{20ac}\rdef\n");
 
  my $dump = DDump $var;
  my %hash = DDump \@list;
  DDump \%hash;
 
  my %hash = DDump (\%hash, 5);  # dig 5 levels deep
 
  my $dump;
  open my $fh, ">", \$dump;
  DDump_IO ($fh, \%hash, 6);
  close $fh;
  print $dump;
 
  use Data::Peek qw( DGrow triplevar );
  my $x = ""; DGrow ($x, 10000);
  my $tv = triplevar ("\N{GREEK SMALL LETTER PI}", 3, "3.1415");
 
 

DESCRIPTION

Data::Peek started off as "DDumper" being a wrapper module over Data::Dumper, but grew out to be a set of low-level data introspection utilities that no other module provided yet, using the lowest level of the perl internals API as possible.

DDumper ($var, ...)

Not liking the default output of Data::Dumper, and always feeling the need to set "$Data::Dumper::Sortkeys = 1;", and not liking any of the default layouts, this function is just a wrapper around Data::Dumper::Dumper with everything set as I like it.
     $Data::Dumper::Sortkeys = 1;
     $Data::Dumper::Indent   = 1;
 
 

And the result is further beautified to meet my needs:

   * quotation of hash keys has been removed (with the disadvantage
     that the output might not be parseable again).
   * arrows for hashes are aligned at 16 (longer keys don't align)
   * closing braces and brackets are now correctly aligned
 
 

In void context, "DDumper ()" warn ()'s.

Example

   print DDumper { ape => 1, foo => "egg", bar => [ 2, "baz", undef ]};
 
   {   ape              => 1,
       bar              => [
           2,
           'baz',
           undef
           ],
       foo              => 'egg'
       };
 
 

DDsort ( 0 | 1 | R | V | VR | VN | VNR )

Set the hash sort algorithm for DDumper. The default is to sort by key value.
   0   - Do not sort
   1   - Sort by key
   R   - Reverse sort by key
   V   - Sort by value
   VR  - Reverse sort by value
   VN  - Sort by value numerical
   VNR - Reverse sort by value numerical
 
 

These can also be passed to import:

   $ perl -MDP=VNR -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
   {   gum              => 13,
       zap              => 3,
       bar              => 2,
       foo              => 1
       };
   $ perl -MDP=V   -we'DDumper { foo => 1, bar => 2, zap => 3, gum => 13 }'
   {   foo              => 1,
       gum              => 13,
       bar              => 2,
       zap              => 3
       };
 
 

DPeek

DPeek ($var)

Playing with "sv_dump ()", I found "Perl_sv_peek ()", and it might be very useful for simple checks. If $var is omitted, uses $_.

Example

   print DPeek "abc\x{0a}de\x{20ac}fg";
 
   PV("abc\nde\342\202\254fg"\0) [UTF8 "abc\nde\x{20ac}fg"]
 
 

In void context, "DPeek ()" prints to "STDERR" plus a newline.

DDisplay

DDisplay ($var)

Show the PV content of a scalar the way perl debugging would have done. UTF-8 detection is on, so this is effectively the same as returning the first part the "DPeek ()" returns for non-UTF8 PV's or the second part for UTF-8 PV's. "DDisplay ()" returns the empty string for scalars that no have a valid PV.

Example

   print DDisplay "abc\x{0a}de\x{20ac}fg";
 
   "abc\nde\x{20ac}fg"
 
 

my ($pv, $iv, $nv, $rv, $hm) = DDual ($var [, $getmagic])

DDual will return the basic elements in a variable, guaranteeing that no conversion takes place. This is very useful for dual-var variables, or when checking is a variable has defined entries for a certain type of scalar. For each String (PV), Integer (IV), Double (NV), and Reference (RV), the current value of $var is returned or undef if it is not set (yet). The 5th element is an indicator if $var has magic, which is not invoked in the returned values, unless explicitly asked for with a true optional second argument.

Example

   print DPeek for DDual ($!, 1);
 
 

In void context, DDual does the equivalent of

   { my @d = DDual ($!, 1);
     print STDERR
       DPeek ($!), "\n",
       "  PV: ", DPeek ($d[0]), "\n",
       "  IV: ", DPeek ($d[1]), "\n",
       "  NV: ", DPeek ($d[2]), "\n",
       "  RV: ", DPeek ($d[3]), "\n";
     }
 
 

my $LEN = DGrow ($pv, $size)

Fastest way to preallocate space for a PV scalar. Returns the allocated length. If $size is smaller than the already allocated space, it will not shrink.
  cmpthese (-2, {
      pack => q{my $x = ""; $x = pack "x20000"; $x = "";},
      op_x => q{my $x = ""; $x = "x"  x 20000;  $x = "";},
      grow => q{my $x = ""; DGrow ($x,  20000); $x = "";},
      });
 
            Rate  op_x  pack  grow
  op_x   62127/s    --  -59%  -96%
  pack  152046/s  145%    --  -91%
  grow 1622943/s 2512%  967%    --
 
 

triplevar ($pv, $iv, $nv)

When making "DDual ()" I wondered if it were possible to create triple-val scalar variables. Scalar::Util already gives us "dualvar ()", that creates you a scalar with different numeric and string values that return different values in different context. Not that "triplevar ()" would be very useful, compared to "dualvar ()", but at least this shows that it is possible.

"triplevar ()" is not exported by default.

Example:

   print DPeek for DDual
       Data::Peek::triplevar ("\N{GREEK SMALL LETTER PI}", 3, 3.1415);
 
   PV("\317\200"\0) [UTF8 "\x{3c0}"]
   IV(3)
   NV(3.1415)
   SV_UNDEF
   IV(0)
 
 

DDump ($var [, $dig_level])

A very useful module when debugging is "Devel::Peek", but is has one big disadvantage: it only prints to STDERR, which is not very handy when your code wants to inspect variables al a low level.

Perl itself has "sv_dump ()", which does something similar, but still prints to STDERR, and only one level deep.

"DDump ()" is an attempt to make the innards available to the script level with a reasonable level of compatibility. "DDump ()" is context sensitive.

In void context, it behaves exactly like "Perl_sv_dump ()".

In scalar context, it returns what "Perl_sv_dump ()" would have printed.

In list context, it returns a hash of the variable's properties. In this mode you can pass an optional second argument that determines the depth of digging.

Example

   print scalar DDump "abc\x{0a}de\x{20ac}fg"
 
   SV = PV(0x723250) at 0x8432b0
     REFCNT = 1
     FLAGS = (PADBUSY,PADMY,POK,pPOK,UTF8)
     PV = 0x731ac0 "abc\nde\342\202\254fg"\0 [UTF8 "abc\nde\x{20ac}fg"]
     CUR = 11
     LEN = 16
 
   my %h = DDump "abc\x{0a}de\x{20ac}fg";
   print DDumper \%h;
 
   {   CUR              => '11',
       FLAGS            => {
           PADBUSY          => 1,
           PADMY            => 1,
           POK              => 1,
           UTF8             => 1,
           pPOK             => 1
           },
       LEN              => '16',
       PV               => '0x731ac0 "abc\\nde\\342\\202\\254fg"\\0 [UTF8 "abc\\nde\\x{20ac}fg"]',
       REFCNT           => '1',
       sv               => 'PV(0x723250) at 0x8432c0'
       };
 
   my %h = DDump {
       ape => 1,
       foo => "egg",
       bar => [ 2, "baz", undef ],
       }, 1;
   print DDumper \%h;
 
   {   FLAGS            => {
           PADBUSY          => 1,
           PADMY            => 1,
           ROK              => 1
           },
       REFCNT           => '1',
       RV               => {
           PVIV("ape")      => {
               FLAGS            => {
                   IOK              => 1,
                   PADBUSY          => 1,
                   PADMY            => 1,
                   pIOK             => 1
                   },
               IV               => '1',
               REFCNT           => '1',
               sv               => 'IV(0x747020) at 0x843a10'
               },
           PVIV("bar")      => {
               CUR              => '0',
               FLAGS            => {
                   PADBUSY          => 1,
                   PADMY            => 1,
                   ROK              => 1
                   },
               IV               => '1',
               LEN              => '0',
               PV               => '0x720210 ""',
               REFCNT           => '1',
               RV               => '0x720210',
               sv               => 'PVIV(0x7223e0) at 0x843a10'
               },
           PVIV("foo")      => {
               CUR              => '3',
               FLAGS            => {
                   PADBUSY          => 1,
                   PADMY            => 1,
                   POK              => 1,
                   pPOK             => 1
                   },
               IV               => '1',
               LEN              => '8',
               PV               => '0x7496c0 "egg"\\0',
               REFCNT           => '1',
               sv               => 'PVIV(0x7223e0) at 0x843a10'
               }
           },
       sv               => 'RV(0x79d058) at 0x843310'
       };
 
 

DDump_IO ($io, $var [, $dig_level])

A wrapper function around perl's internal "Perl_do_sv_dump ()", which makes "Devel::Peek" completely superfluous. As PerlIO is only available perl version 5.7.3 and up, this function is not available in older perls.

Example

   my $dump;
   open my $eh, ">", \$dump;
   DDump_IO ($eh, { 3 => 4, ape => [5..8]}, 6);
   close $eh;
   print $dump;
 
   SV = RV(0x79d9e0) at 0x843f00
     REFCNT = 1
     FLAGS = (TEMP,ROK)
     RV = 0x741090
       SV = PVHV(0x79c948) at 0x741090
         REFCNT = 1
         FLAGS = (SHAREKEYS)
         IV = 2
         NV = 0
         ARRAY = 0x748ff0  (0:7, 2:1)
         hash quality = 62.5%
         KEYS = 2
         FILL = 1
         MAX = 7
         RITER = -1
         EITER = 0x0
           Elt "ape" HASH = 0x97623e03
           SV = RV(0x79d9d8) at 0x8440e0
             REFCNT = 1
             FLAGS = (ROK)
             RV = 0x741470
               SV = PVAV(0x7264b0) at 0x741470
                 REFCNT = 2
                 FLAGS = ()
                 IV = 0
                 NV = 0
                 ARRAY = 0x822f70
                 FILL = 3
                 MAX = 3
                 ARYLEN = 0x0
                 FLAGS = (REAL)
                   Elt No. 0
                   SV = IV(0x7467c8) at 0x7c1aa0
                     REFCNT = 1
                     FLAGS = (IOK,pIOK)
                     IV = 5
                   Elt No. 1
                   SV = IV(0x7467b0) at 0x8440f0
                     REFCNT = 1
                     FLAGS = (IOK,pIOK)
                     IV = 6
                   Elt No. 2
                   SV = IV(0x746810) at 0x75be00
                     REFCNT = 1
                     FLAGS = (IOK,pIOK)
                     IV = 7
                   Elt No. 3
                   SV = IV(0x746d38) at 0x7799d0
                     REFCNT = 1
                     FLAGS = (IOK,pIOK)
                     IV = 8
           Elt "3" HASH = 0xa400c7f3
           SV = IV(0x746fd0) at 0x7200e0
             REFCNT = 1
             FLAGS = (IOK,pIOK)
             IV = 4
 
 

INTERNALS

"DDump ()" uses an XS wrapper around "Perl_sv_dump ()" where the STDERR is temporarily caught to a pipe. The internal XS helper functions are not meant for user space

DDump_XS (SV *sv)

Base interface to internals for "DDump ()".

BUGS

Windows and AIX might be using a build where not all symbols that were supposed to be exported in the public API are not. Perl_pv_peek () is one of them.

Not all types of references are supported.

No idea how far back this goes in perl support, but Devel::PPPort has proven to be a big help.

SEE ALSO

Devel::Peek(3), Data::Dumper(3), Data::Dump(3), Devel::Dumpvar, Data::Dump::Streamer(3)

AUTHOR

H.Merijn Brand <h.m.brand@xs4all.nl> Copyright (C) 2008-2010 H.Merijn Brand

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.