289 lines
7.3 KiB
HTML
289 lines
7.3 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Data::Dump</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Data::Dump</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2015-06-09<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Data::Dump - Pretty printing of data structures
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use Data::Dump qw(dump);
|
|
|
|
$str = dump(@list);
|
|
@copy_of_list = eval $str;
|
|
|
|
# or use it for easy debug printout
|
|
use Data::Dump; dd localtime;
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This module provide a few functions that traverse their
|
|
argument and produces a string as its result. The string contains
|
|
Perl code that, when <TT>"eval"</TT>ed, produces a deep copy of the original
|
|
arguments.
|
|
<P>
|
|
|
|
The main feature of the module is that it strives to produce output
|
|
that is easy to read. Example:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
@a = (1, [2, 3], {4 => 5});
|
|
dump(@a);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Produces:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
"(1, [2, 3], { 4 => 5 })"
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
If you dump just a little data, it is output on a single line. If
|
|
you dump data that is more complex or there is a lot of it, line breaks
|
|
are automatically added to keep it easy to read.
|
|
<P>
|
|
|
|
The following functions are provided (only the dd* functions are exported by default):
|
|
<DL COMPACT>
|
|
<DT id="1">dump( ... )<DD>
|
|
|
|
|
|
|
|
<DT id="2">pp( ... )<DD>
|
|
|
|
|
|
|
|
Returns a string containing a Perl expression. If you pass this
|
|
string to Perl's built-in <I>eval()</I> function it should return a copy of
|
|
the arguments you passed to <I>dump()</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you call the function with multiple arguments then the output will
|
|
be wrapped in parenthesis ``( ..., ... )''. If you call the function with a
|
|
single argument the output will not have the wrapping. If you call the function with
|
|
a single scalar (non-reference) argument it will just return the
|
|
scalar quoted if needed, but never break it into multiple lines. If you
|
|
pass multiple arguments or references to arrays of hashes then the
|
|
return value might contain line breaks to format it for easier
|
|
reading. The returned string will never be ``\n'' terminated, even if
|
|
contains multiple lines. This allows code like this to place the
|
|
semicolon in the expected place:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
print '$obj = ', dump($obj), ";\n";
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <I>dump()</I> is called in void context, then the dump is printed on
|
|
<FONT SIZE="-1">STDERR</FONT> and then ``\n'' terminated. You might find this useful for quick
|
|
debug printouts, but the dd*() functions might be better alternatives
|
|
for this.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
There is no difference between <I>dump()</I> and <I>pp()</I>, except that <I>dump()</I>
|
|
shares its name with a not-so-useful perl builtin. Because of this
|
|
some might want to avoid using that name.
|
|
<DT id="3">quote( $string )<DD>
|
|
|
|
|
|
|
|
|
|
Returns a quoted version of the provided string.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It differs from <TT>"dump($string)"</TT> in that it will quote even numbers and
|
|
not try to come up with clever expressions that might shorten the
|
|
output. If a non-scalar argument is provided then it's just stringified
|
|
instead of traversed.
|
|
<DT id="4">dd( ... )<DD>
|
|
|
|
|
|
|
|
<DT id="5">ddx( ... )<DD>
|
|
|
|
|
|
|
|
These functions will call <I>dump()</I> on their argument and print the
|
|
result to <FONT SIZE="-1">STDOUT </FONT>(actually, it's the currently selected output handle, but
|
|
<FONT SIZE="-1">STDOUT</FONT> is the default for that).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The difference between them is only that <I>ddx()</I> will prefix the lines
|
|
it prints with ``# '' and mark the first line with the file and line
|
|
number where it was called. This is meant to be useful for debug
|
|
printouts of state within programs.
|
|
<DT id="6">dumpf( ..., \&filter )<DD>
|
|
|
|
|
|
Short hand for calling the <I>dump_filtered()</I> function of Data::Dump::Filtered.
|
|
This works like <I>dump()</I>, but the last argument should be a filter callback
|
|
function. As objects are visited the filter callback is invoked and it
|
|
can modify how the objects are dumped.
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>CONFIGURATION</H2>
|
|
|
|
|
|
|
|
There are a few global variables that can be set to modify the output
|
|
generated by the dump functions. It's wise to localize the setting of
|
|
these.
|
|
<DL COMPACT>
|
|
<DT id="7">$Data::Dump::INDENT<DD>
|
|
|
|
|
|
|
|
|
|
This holds the string that's used for indenting multiline data structures.
|
|
It's default value is `` '' (two spaces). Set it to "`` to suppress indentation.
|
|
Setting it to ''| " makes for nice visuals even if the dump output then fails to
|
|
be valid Perl.
|
|
<DT id="8">$Data::Dump::TRY_BASE64<DD>
|
|
|
|
|
|
|
|
|
|
How long must a binary string be before we try to use the base64 encoding
|
|
for the dump output. The default is 50. Set it to 0 to disable base64 dumps.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>LIMITATIONS</H2>
|
|
|
|
|
|
|
|
Code references will be dumped as <TT>"sub { ... }"</TT>. Thus, <TT>"eval"</TT>ing them will
|
|
not reproduce the original routine. The <TT>"..."</TT>-operator used will also require
|
|
perl-5.12 or better to be evaled.
|
|
<P>
|
|
|
|
If you forget to explicitly import the <TT>"dump"</TT> function, your code will
|
|
core dump. That's because you just called the builtin <TT>"dump"</TT> function
|
|
by accident, which intentionally dumps core. Because of this you can
|
|
also import the same function as <TT>"pp"</TT>, mnemonic for ``pretty-print''.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>HISTORY</H2>
|
|
|
|
|
|
|
|
The <TT>"Data::Dump"</TT> module grew out of frustration with Sarathy's
|
|
in-most-cases-excellent <TT>"Data::Dumper"</TT>. Basic ideas and some code
|
|
are shared with Sarathy's module.
|
|
<P>
|
|
|
|
The <TT>"Data::Dump"</TT> module provides a much simpler interface than
|
|
<TT>"Data::Dumper"</TT>. No <FONT SIZE="-1">OO</FONT> interface is available and there are fewer
|
|
configuration options to worry about. The other benefit is
|
|
that the dump produced does not try to set any variables. It only
|
|
returns what is needed to produce a copy of the arguments. This means
|
|
that <TT>"dump("foo")"</TT> simply returns <TT>'"foo"'</TT>, and <TT>"dump(1..3)"</TT> simply
|
|
returns <TT>'(1, 2, 3)'</TT>.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Data::Dump::Filtered, Data::Dump::Trace, Data::Dumper, <FONT SIZE="-1">JSON</FONT>,
|
|
Storable
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
|
|
The <TT>"Data::Dump"</TT> module is written by Gisle Aas <<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>>, based
|
|
on <TT>"Data::Dumper"</TT> by Gurusamy Sarathy <<A HREF="mailto:gsar@umich.edu">gsar@umich.edu</A>>.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Copyright 1998-2010 Gisle Aas.
|
|
Copyright 1996-1998 Gurusamy Sarathy.
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="9"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="10"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="11"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="12"><A HREF="#lbAE">CONFIGURATION</A><DD>
|
|
<DT id="13"><A HREF="#lbAF">LIMITATIONS</A><DD>
|
|
<DT id="14"><A HREF="#lbAG">HISTORY</A><DD>
|
|
<DT id="15"><A HREF="#lbAH">SEE ALSO</A><DD>
|
|
<DT id="16"><A HREF="#lbAI">AUTHORS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:38 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|