.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Shell::Perl::Dumper 3pm"
.TH Shell::Perl::Dumper 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Shell::Perl::Dumper \- Dumpers for Shell::Perl
.SH "SYNOPSYS"
.IX Header "SYNOPSYS"
.Vb 4
\&    use Shell::Perl::Dumper;
\&    $dumper = Shell::Perl::Dumper::Plain\->new;
\&    print $dumper\->dump_scalar($scalar);
\&    print $dumper\->dump_list(@list);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In \f(CW\*(C`pirl\*(C'\fR, the result of the evaluation is transformed
into a string to be printed. As this result may be a pretty
complex data structure, the shell provides a hook
for you to pretty-print these answers just the way you want.
.PP
By default, \f(CW\*(C`pirl\*(C'\fR will try to convert the results
via \f(CW\*(C`Data::Dump\*(C'\fR. That means the output will be Perl
code that may be run to get the data structure again.
Alternatively, the shell may use \f(CW\*(C`Data::Dumper\*(C'\fR
or \f(CW\*(C`Data::Dump::Streamer\*(C'\fR
with almost the same result with respect to the
representation as Perl code. (But the output of the
modules differ enough for sufficiently complex data.)
.PP
Other options are to set the output to produce \s-1YAML\s0
or a plain simple-minded solution which basically
turns the result to string via simple interpolation.
.PP
All of these are implemented via \fIdumper objects\fR.
Dumpers are meant to be used like that:
.PP
.Vb 1
\&   $dumper = Some::Dumper::Class\->new; # build a dumper
\&
\&   $s = $dumper\->dump_scalar($scalar); # from scalar to string
\&
\&   $s = $dumper\->dump_list(@list); # from list to string
.Ve
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
The following methods compose the expected \s-1API\s0
of a dumper, as used by Shell::Perl.
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 1
\&    $dumper = $class\->new(@args);
.Ve
.Sp
Constructs a dumper.
.IP "\fBdump_scalar\fR" 4
.IX Item "dump_scalar"
.Vb 1
\&    $s = $dumper\->dump_scalar($scalar);
.Ve
.Sp
Turns a scalar into a string representation.
.IP "\fBdump_list\fR" 4
.IX Item "dump_list"
.Vb 1
\&    $s = $dumper\->dump_list(@list);
.Ve
.Sp
Turns a list into a string representation.
.IP "\fBis_available\fR" 4
.IX Item "is_available"
.Vb 1
\&    $ok = $class\->is_available
.Ve
.Sp
This is an \fIoptional\fR class method. If it exists, it
means that the class has external dependencies (like
\&\f(CW\*(C`Shell::Perl::Data::Dump\*(C'\fR depends on \f(CW\*(C`Data::Dump\*(C'\fR)
and whether these may be loaded when needed. If they can,
this method returns true. Otherwise, returning false
means that a dumper instance of this class probably
cannot work. This is typically because the dependency
is not installed or cannot be loaded due to
an installation problem.
.Sp
This is the algorithm used by Shell::Perl \s-1XXX
XXX XXX\s0
.Sp
.Vb 1
\&    1.
.Ve
.SH "THE STANDARD DUMPERS"
.IX Header "THE STANDARD DUMPERS"
Shell::Perl provides four standard dumpers:
.PP
.Vb 5
\&    * Shell::Perl::Data::Dump
\&    * Shell::Perl::Data::Dumper
\&    * Shell::Perl::Data::Dump::Streamer
\&    * Shell::Perl::Dumper::YAML
\&    * Shell::Perl::Dumper::Plain
.Ve
.PP
which corresponds to the four options of the
command \f(CW\*(C` :set out \*(C'\fR: \*(L"D\*(R", \*(L"\s-1DD\*(R", \*(L"DDS\*(R", \*(L"Y\*(R",\s0 and \*(L"P\*(R"
respectively.
.SS "Data::Dump"
.IX Subsection "Data::Dump"
The package \f(CW\*(C`Shell::Perl::Data::Dump\*(C'\fR implements a dumper
which uses Data::Dump to turn Perl variables into
a string representation.
.PP
It is used like this:
.PP
.Vb 1
\&    use Shell::Perl::Dumper;
\&
\&    if (!Shell::Perl::Data::Dump\->is_available) {
\&        die "the dumper cannot be loaded correctly"
\&    }
\&    $dumper = Shell::Perl::Data::Dump\->new;
\&    print $dumper\->dump_scalar($scalar);
\&    print $dumper\->dump_list(@list);
.Ve
.PP
Examples of its output:
.PP
.Vb 1
\&    pirl > :set out D
\&
\&    pirl > { a => 3 } #scalar
\&    { a => 3 }
\&
\&    pirl > (1, 2, "a") #list
\&    (1, 2, "a")
.Ve
.SS "Data::Dumper"
.IX Subsection "Data::Dumper"
The package \f(CW\*(C`Shell::Perl::Data::Dumper\*(C'\fR implements a dumper
which uses Data::Dumper to turn Perl variables into
a string representation.
.PP
It is used like this:
.PP
.Vb 1
\&    use Shell::Perl::Dumper;
\&
\&    if (!Shell::Perl::Data::Dumper\->is_available) {
\&        die "the dumper cannot be loaded correctly"
\&    }
\&    $dumper = Shell::Perl::Data::Dumper\->new;
\&    print $dumper\->dump_scalar($scalar);
\&    print $dumper\->dump_list(@list);
.Ve
.PP
Examples of its output:
.PP
.Vb 1
\&    pirl > :set out DD
\&
\&    pirl > { a => 3 } #scalar
\&    @var = (
\&             {
\&               \*(Aqa\*(Aq => 3
\&             }
\&           );
\&
\&    pirl > (1, 2, "a") #list
\&    @var = (
\&             1,
\&             2,
\&             \*(Aqa\*(Aq
\&           );
.Ve
.SS "\s-1YAML\s0"
.IX Subsection "YAML"
The package \f(CW\*(C`Shell::Perl::Dumper::YAML\*(C'\fR implements a dumper
which uses YAML::Syck or \s-1YAML\s0 to turn Perl variables into
a string representation.
.PP
It is used like this:
.PP
.Vb 1
\&    use Shell::Perl::Dumper;
\&
\&    if (!Shell::Perl::Dumper::YAML\->is_available) {
\&        die "the dumper cannot be loaded correctly"
\&    }
\&    $dumper = Shell::Perl::Dumper::YAML\->new;
\&    print $dumper\->dump_scalar($scalar);
\&    print $dumper\->dump_list(@list);
.Ve
.PP
Examples of its output:
.PP
.Vb 1
\&    pirl > :set out Y
\&
\&    pirl @> { a => 3 } #scalar
\&    \-\-\-
\&    a: 3
\&
\&    pirl @> (1, 2, "a") #list
\&    \-\-\- 1
\&    \-\-\- 2
\&    \-\-\- a
.Ve
.PP
When loading, \f(CW\*(C`YAML::Syck\*(C'\fR is preferred to \f(CW\*(C`YAML\*(C'\fR. If it
is not available, the \f(CW\*(C`YAML\*(C'\fR module is the second option.
.SS "Data::Dump::Streamer"
.IX Subsection "Data::Dump::Streamer"
The documentation is yet to be written.
.SS "Plain Dumper"
.IX Subsection "Plain Dumper"
The package \f(CW\*(C`Shell::Perl::Dumper::Plain\*(C'\fR implements a dumper
which uses string interpolation to turn Perl variables into
strings.
.PP
It is used like this:
.PP
.Vb 1
\&    use Shell::Perl::Dumper;
\&
\&    $dumper = Shell::Perl::Dumper::Plain\->new;
\&    print $dumper\->dump_scalar($scalar);
\&    print $dumper\->dump_list(@list);
.Ve
.PP
Examples of its output:
.PP
.Vb 1
\&    pirl > :set out P
\&
\&    pirl > { a => 3 } #scalar
\&    HASH(0x1094d2c0)
\&
\&    pirl > (1, 2, "a") #list
\&    1       2       a
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Shell::Perl for more documentation.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007–2017 by Adriano R. Ferreira
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.