NAME

Data::Dumper::Interp - interpolate Data::Dumper output into strings for human consumption

SYNOPSIS

  use open IO => ':locale';
  use Data::Dumper::Interp;
  @ARGV = ('-i', '/file/path');
  my %hash = (abc => [1,2,3,4,5], def => undef);
  my $href = \%hash;
  my $coderef = \&mysub;
  my $obj = bless {}, "Foo::Bar";
  # Interpolate variables in strings with Data::Dumper output
  say ivis 'FYI ref is $href\nThat hash is: %hash\nArgs are @ARGV';
    # -->FYI ref is {abc => [1,2,3,4,5], def => undef}
    #    That hash is: (abc => [1,2,3,4,5], def => undef)
    #    Args are ("-i","/file/path")
  # Label interpolated values with "expr="
  say dvis '$coderef  $href\nand @ARGV';
    #-->coderef=\&main::mysub  href={abc => [1,2,3,4,5], def => undef}
    #   and @ARGV=("-i","/file/path")
  # Functions to format one thing
  say vis $href;     # {abc => [1,2,3,4,5], def => undef}
  say vis \@ARGV;    # ["-i", "/file/path"]  # any scalar
  say avis @ARGV;    # ("-i", "/file/path")
  say hvis %hash;    # (abc => [1,2,3,4,5], def => undef)
  # Format a reference with abbreviated referent address
  say visr $href;     # HASH<457:1c9>{abc => [1,2,3,4,5], ...}
  # Just abbreviate a referent address or arbitrary number
  say addrvis refaddr($href);  # 457:1c9
  say addrvis $href;           # HASH<457:1c9>
  say addrvis $obj;            # Foo::Bar<984:ef8>
  # Stringify objects
  { use bigint;
    my $struct = { debt => 999_999_999_999_999_999.02 };
    say vis $struct;
      # --> {debt => (Math::BigFloat)999999999999999999.02}
    # But if you do want to see object internals...
    #
    say visnew->viso($struct);
      # --> {debt => bless({...lots of stuff...},'Math::BigInt')}
    # These do the same thing
    say visnew->Objects(0)->vis($struct);
    { local $Data::Dumper::Interp::Objects=0; say vis $struct; }
    say viso $struct;   # 'viso' is not exported by default
  }
  # Wide characters are readable
  use utf8;
  my $h = {msg => "My language is not ASCII ☻ ☺ 😊 \N{U+2757}!"};
  say dvis '$h' ;
    # --> h={msg => "My language is not ASCII ☻ ☺ 😊 ❗!"}
  #-------- OO API --------
  say visnew->MaxStringwidth(50)->Maxdepth($levels)->vis($datum);
  say Data::Dumper::Interp->new()
            ->MaxStringwidth(50)->Maxdepth($levels)->vis($datum);
  #-------- UTILITY FUNCTIONS --------
  say u($might_be_undef);  # $_[0] // "undef"
  say quotekey($string);   # quote if not a valid bareword
  say qsh($string);        # quote if needed for /bin/sh
  say qshpath($pathname);  # shell quote excepting ~ prefix
  say "Runing this: ", qshlist(@command_and_args);
  system "ls -ld ".join(" ",map{ qshpath }
                            ("/tmp", "~sally/My Documents", "~"));

DESCRIPTION

This Data::Dumper wrapper optimizes output for human consumption and avoids side-effects which interfere with debugging.

The namesake feature is interpolating Data::Dumper output into strings. Simple functions are also provided to format a scalar, array, or hash.

Internally, Data::Dumper is called to visualize (i.e. format) data with pre- and post-processing to "improve" the results:

• One line if possible, else folded to terminal width, WITHOUT newline.
• Safely printable Unicode characters appear as themselves.
• Code refs show the name of the referenced sub.
• Objects like Math:BigInt etc. are stringified (by default).
• "Virtual" values behind overloaded deref operators are shown.
• Data::Dumper bugs^H^H^H^Hquirks are circumvented.

See "DIFFERENCES FROM Data::Dumper".

Utilities are also provided to quote strings for /bin/sh.

FUNCTIONS

  use Spreadsheet::Edit::Interp qw/visnew/;
  ...
  say visnew->vis($struct);
  say visnew->visrq($my_object);
  say visnew->avis(@ARGV);
  say visnew->avis2lrq(@ARGV);
  etc.

 ivis  dvis    vis  avis  hvis
 ivisq dvisq   visq avisq hvisq rvis rvisq
 visnew
 addrvis addrvisl
 u quotekey qsh qshlist qshpath

Showing Abbreviated Addresses

OBJECT-ORIENTED API

   $msg = visnew->Foldwidth(40)->avis(@ARGV);

   local $Data::Dumper::Interp::Foldwidth = 40;
   $msg = avis @ARGV;

   $msg = visnew->Foldwidth(40)->vis_r2($x); # show addresses; Maxdepth 2

Configuration Variables / Methods

These work the same way as variables/methods in Data::Dumper.

Each config method has a corresponding global variable in package "Data::Dumper::Interp" which provides the default value.

When a config method is called without arguments the current value is returned, and when called with an argument the value is changed and the object is returned so that calls can be chained.

UTILITY FUNCTIONS

LIMITATIONS

Interpolated Strings

"ivis" and "dvis" evaluate expressions in the user's context using Perl's debugger support ('eval' in package DB -- see perlfunc). This mechanism has some limitations:

@_ may show incorrect values except immediately after sub entry. For example after "shift" @_ will appear to still have the original arguments.

A lexical ("my") sub creates a closure, and variables in visible scopes which are not actually referenced by your code may not exist in the closure; an attempt to display them with "ivis" will fail. For example:

    our $global;
    sub outerfunc {
      my sub inner {
        say dvis '$global'; # croaks with "Error interpolating '$global'"
        # my $x = $global;  # ... unless this is un-commented
      }
      &inner();
    }
    &outerfunc;
    

Multiply-referenced items

If a structure contains several refs to the same item, the first ref will be visualized by showing the referenced item as you might expect.

However subsequent refs will look like "$VAR1->place" where "place" is the location of the first ref in the overall structure. This is how Data::Dumper indicates that the ref is a copy of the first ref and thus points to the same datum. "$VAR1" is an artifact of how Data::Dumper would generate code using its "Purity" feature. Data::Dumper::Interp simply passed through these annotations.

However with Refaddr(true), multiple references to the same thing will all show the address of the referenced thing.

The special "_" stat filehandle may not be preserved

Data::Dumper::Interp queries the operating system for the window size to initialize $Foldwidth, if it is not already defined; this may change the "_" filehandle. After the first call (or if you pre-set $Foldwidth), the "_" filehandle will not change across calls.

DIFFERENCES FROM Data::Dumper

Results differ from plain "Data::Dumper" output in the following ways (most of these can be controlled via Config options):

• Punctuation variables such as $@, $!, and $?, are preserved over calls.
• A final newline is never included.

  Everything is shown on a single line if possible, otherwise wrapped to your terminal width (or $Foldwidth), with indented structure levels.

• Printable Unicode characters appear as themselves instead of \x{ABCD}.

  Note: If your data contains 'wide characters', you should "use open IO => ':locale';" or otherwise arrange to encode the output for your terminal. You'll also want "use utf8;" if your Perl source contains characters outside the ASCII range.

  Undecoded binary octets (e.g. data read from a 'binmode' file) will still be escaped as individual bytes.

• Depending on options, spaces·may·be·shown·visibly and '␤' may be shown for newline (and similarly for other ASCII controls).

  "White space" characters in qr/compiled regex/ are shown as \t, \n etc.

• Unless Deparse is enabled, CODE refs show the name of the referenced sub using Sub::Identify instead of "sub{ "DUMMY" }". If the sub is anonymous, the file:lineno where it was defined is shown.
• The internals of objects are not shown by default.

  If stringifcation is overloaded it is used to obtain the object's representation. For example, "bignum" and "bigrat" numbers are shown as easily readable values rather than "bless( {...}, 'Math::...')".

  Stingified objects are prefixed with "(classname)" to make clear what happened.

  The "virtual" value of objects which overload a dereference operator ("@{}" or "%{}") is displayed instead of the object's internals.

• Hash keys are sorted treating numeric "components" numerically. For example "A.20" sorts before "A.100".
• Numbers and strings which look like numbers are kept distinct when displayed, i.e. "0" does not become 0 or vice-versa. Floating-point values are shown as numbers not 'quoted strings' and similarly for stringified objects.

  Although such differences might be immaterial to Perl during execution, they may be important when communicating to a human.

SEE ALSO

Data::Dumper

AUTHOR

Jim Avera (jim.avera AT gmail)

LICENSE

Public Domain or CC0.