Data::Dumper::Interp - interpolate Data::Dumper output into strings for human consumption
use open IO => ':locale'; use Data::Dumper::Interp; @ARGV = ('-i', '/file/path'); my %hash = (abc => [1,2,3,4,5], def => undef); my $ref = \%hash; # Interpolate variables in strings with Data::Dumper output say ivis 'FYI ref is $ref\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 '$ref\nand @ARGV'; # -->ref={abc => [1,2,3,4,5], def => undef} # and @ARGV=("-i","/file/path") # Functions to format one thing say vis $ref; #-->{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) # 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->Objects(0)->vis($struct); { local $Data::Dumper::Interp::Objects=0; say vis $struct; } #another way # --> {debt => bless({...lots of stuff...},'Math::BigInt')} } # 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 Data::Dumper::Interp->new() ->MaxStringwidth(50)->Maxdepth($levels)->vis($datum); say visnew->MaxStringwidth(50)->Maxdepth($levels)->vis($datum); #-------- UTILITY FUNCTIONS -------- say u($might_be_undef); # $_[0] // "undef" say quotekey($string); # quote hash key if not a valid bareword say qsh($string); # quote if needed for /bin/sh say qshpath($pathname); # shell quote excepting ~ or ~username prefix system "ls -ld ".join(" ",map{ qshpath } ("/tmp", "~sally/My Documents", "~"));
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, but simple functions are also provided to visualize 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:
Output is compact (1 line if possibe, otherwise folded at your terminal width), WITHOUT a trailing newline.
Printable Unicode characters appear as themselves.
Object internals are not shown; Math:BigInt etc. are stringified.
"virtual" values behind overloaded array/hash-deref operators are shown
Data::Dumper bugs^H^H^H^Hquirks are circumvented.
See "DIFFERENCES FROM Data::Dumper".
Finally, a few utilities are provided to quote strings for /bin/sh.
Returns the argument with variable references and escapes interpolated as in in Perl double-quotish strings, but using Data::Dumper to format variable values.
$var is replaced by its value, @var is replaced by "(comma, sparated, list)", and %hash by "(key => value, ...)" . More complex expressions with indexing, dereferences, slices and method calls are also recognized, e.g.
$var
@var
%hash
'The answer is $foo->[$bar->{$somekey}]->frobnicate(42) for Pete's sake'
Expressions are evaluated in the caller's context using Perl's debugger hooks, and may refer to almost any lexical or global visible at the point of call (see "LIMITATIONS").
IMPORTANT: The argument string must be single-quoted to prevent Perl from interpolating it beforehand.
Like ivis with the addition that interpolated expressions are prefixed with a "exprtext=" label.
ivis
The 'd' in 'dvis' stands for debugging messages, a frequent use case where brevity of typing is more highly prized than beautiful output.
vis formats a single scalar ($_ if no argument is given) and returns the resulting string.
vis
avis formats an array (or any list) as comma-separated values in parenthesis.
avis
hvis formats key => value pairs in parenthesis.
hvis
The "l" variants return a bare list without the enclosing parenthesis.
The 'q' variants display strings in 'single quoted' form if possible.
Internally, Data::Dumper is called with Useqq(0), but depending on the version of Data::Dumper the result may be "double quoted" anyway if wide characters are present.
Useqq(0)
Creates an object initialized from the global configuration variables listed below (the function visnew is simply a shorthand wrapper function).
visnew
No arguments are permitted.
The functions described above may then be called as methods on the object (when not called as a method the functions create a new object internally).
For example:
$msg = visnew->Foldwidth(40)->avis(@ARGV); or $msg = Data::Dumper::Interp->new()->Foldwidth(40)->avis(@ARGV);
return the same string as
local $Data::Dumper::Interp::Foldwidth = 40; $msg = avis(@ARGV);
These work the same way as variables/methods in Data::Dumper.
Each configuration method has a corresponding global variable in package Data::Dumper::Interp which provides the default.
Data::Dumper::Interp
When a method is called without arguments the current value is returned.
When a method is called with an argument to set a value, the object is returned so that method calls can be chained.
Longer strings are truncated and Truncsuffix appended. MaxStringwidth=0 (the default) means no limit.
Defaults to the terminal width at the time of first use.
A false value disables special handling of objects and internals are shown as with Data::Dumper.
A "1" (the default) enables for all objects, otherwise only for the specified class name(s) [or derived classes].
When enabled, object internals are never shown. If the stringification ('""') operator, or array-, hash-, scalar-, or glob- deref operators are overloaded, then the first overloaded operator found will be evaluated and the object replaced by the result, and the check repeated; otherwise the ref is stringified in the usual way, so something like "Foo::Bar=HASH(0xabcd1234)" appears.
Beginning with version 5.000 the deprecated Overloads method is an alias for Objects.
Overloads
Objects
The default sorts numeric substrings in keys by numerical value, e.g. "A.20" sorts before "A.100". See Data::Dumper documentation.
Data::Dumper
The default is "unicode:controlpic" except for functions/methods with 'q' in their name, which force Useqq(0).
0 means generate 'single quoted' strings when possible.
1 means generate "double quoted" strings, as-is from Data::Dumper. Non-ASCII charcters will be shown as hex escapes.
Otherwise generate "double quoted" strings enhanced according to option keywords given as a :-separated list, e.g. Useqq("unicode:controlpic"). The avilable options are:
All printable characters are shown as themselves rather than hex escapes, and '\n', '\t', etc. are shown for common ASCII control codes.
Show ASCII control characters using single "control picture" characters, for example '' is shown for newline instead of '\n'. Similarly for \0 \a \b \e \f \r and \t.
This way every character occupies the same space with a fixed-width font. However the commonly-used "Last Resort" font for these characters can be hard to read on modern high-res displays. You can set Useqq to just "unicode" to see traditional \n etc. backslash escapes while still seeing wide characters as themselves.
Useqq
Show using Perl's qq{...} syntax, or qqX...Y if deliters are specified, rather than "...".
See Data::Dumper documentation.
Returns the argument ($_ by default) if it is defined, otherwise the string "undef".
Returns the argument ($_ by default) if it is a valid bareword, otherwise a "quoted string".
The string ($_ by default) is quoted if necessary for parsing by /bin/sh, which has different quoting rules than Perl.
If the string contains only "shell-safe" ASCII characters it is returned as-is, without quotes.
If the argument is a ref but is not an object which stringifies, then vis() is called and the resulting string quoted. An undefined value is shown as undef without quotes; as a special case to avoid ambiguity the string 'undef' is always "quoted".
undef
Similar to qsh except that an initial ~ or ~username is left unquoted. Useful for paths given to bash or csh.
qsh
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:
dvis
@_ will appear to have the original arguments to a sub even if "shift" has been executed. However if @_ is entirely replaced, the correct values will be displayed.
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;
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 does nothing special and simply passes through these annotations.
$VAR1->place
place
Data::Dumper::Interp queries the operating system to obtain 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.
$Foldwidth
Results differ from plain Data::Dumper output in the following ways (most substitutions can be disabled via Config options):
A final newline is never included.
Everything is shown on a single line if possible, otherwise wrapped to your terminal width (or $Foldwidth) with indentation appropriate to 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.
use open IO => ':locale';
use utf8;
Undecoded binary octets (e.g. data read from a 'binmode' file) will still be escaped as individual bytes when necessary.
'' and similar "control picture" characters are shown for ASCII controls.
The internals of objects are not shown.
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::...')".
bignum
bigrat
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".
Punctuation variables, including $@ and $?, are preserved over calls.
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.
Jim Avera (jim.avera AT gmail)
To install Data::Dumper::Interp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Dumper::Interp
CPAN shell
perl -MCPAN -e shell install Data::Dumper::Interp
For more information on module installation, please visit the detailed CPAN module installation guide.