.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catmandu::Exporter 3pm"
.TH Catmandu::Exporter 3pm "2019-01-29" "perl v5.28.1" "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"
Catmandu::Exporter \- Namespace for packages that can export
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # From the command line
\&
\&    # JSON is an importer and YAML an exporter
\&    $ catmandu convert JSON to YAML < data.json
\&
\&    # OAI is an importer and JSON an exporter
\&    $ catmandu convert OAI \-\-url http://biblio.ugent.be/oai to JSON
\&
\&    # From Perl
\&    use Catmandu;
\&
\&    my $importer = Catmandu\->importer(\*(AqJSON\*(Aq, file => \*(Aqdata.json\*(Aq);
\&    my $exporter = Catmandu\->exporter(\*(AqYAML\*(Aq);
\&
\&    $exporter\->add({ record => "one"});
\&    $exporter\->add_many([ { record => "one" } , { record => "two" } ]);
\&    $exporter\->add_many($importer);
\&
\&    $exporter\->commit;
\&
\&    undef($exporter); # Clean up memory
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Catmandu::Exporter is a Perl package that can export data into \s-1JSON, YAML, XML\s0
or many other formats. By default, data is to \s-1STDOUT.\s0 Optionally provide a \f(CW\*(C`file\*(C'\fR
or \f(CW\*(C`fh\*(C'\fR parameter to write to a file, string, or handle.
.PP
Every Catmandu::Exporter is a Catmandu::Fixable thus provides a \f(CW\*(C`fix\*(C'\fR
parameter and method to apply fixes to exported items:
.PP
.Vb 1
\&    my $exporter = Catmandu\->exporter(\*(AqJSON\*(Aq, fix => [\*(Aqupcase(title)\*(Aq]);
\&
\&    # This will be printed to STDOUT like: {"title":"MY TITLE"}
\&    $exporter\->add({ title => "my title"});
.Ve
.PP
Every Catmandu::Exporter is a Catmandu::Addable thus inherits the methods
\&\f(CW\*(C`add\*(C'\fR and \f(CW\*(C`add_many\*(C'\fR.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.IP "file" 4
.IX Item "file"
Write output to a local file given by its path or file handle.  Alternatively a
scalar reference can be passed to write to a string and a code reference can be
used to write to a callback function.
.IP "fh" 4
.IX Item "fh"
Write the output to an IO::Handle. If not specified,
Catmandu::Util::io is used to create the output
handle from the \f(CW\*(C`file\*(C'\fR argument or by using \s-1STDOUT.\s0
.Sp
It is the task of the Perl programmer to close any opened IO::Handles.
Catmandu will not do this by itself.
.IP "encoding" 4
.IX Item "encoding"
Binmode of the output stream \f(CW\*(C`fh\*(C'\fR. Set to "\f(CW\*(C`:utf8\*(C'\fR" by default.
.IP "fix" 4
.IX Item "fix"
An \s-1ARRAY\s0 of one or more fixes or file scripts to be applied to exported items.
.SH "METHODS"
.IX Header "METHODS"
.SS "add"
.IX Subsection "add"
Adds one item to be exported.
.SS "add_many"
.IX Subsection "add_many"
Adds many items to be exported. This can be either an ARRAY-ref or
an Catmandu::Iterator. Returns a true value when the export was
successful or undef on error.
.SS "count"
.IX Subsection "count"
Returns the number of items exported by this Catmandu::Exporter.
.SS "log"
.IX Subsection "log"
Returns the current logger.
.SS "commit"
.IX Subsection "commit"
Commit all buffers to the output handle.
.SH "CODING"
.IX Header "CODING"
Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace
that implements \f(CW\*(C`Catmandu::Exporter\*(C'\fR. Basically, you need to create a method add which
writes a Perl hash to a file handle:
.PP
.Vb 1
\&    package Catmandu::Exporter::Foo;
\&
\&    use Catmandu::Sane;
\&    use Moo;
\&
\&    with \*(AqCatmandu::Exporter\*(Aq
\&
\&    sub add {
\&        my ($self, $data) = @_;
\&        my $fh = $self\->fh;
\&        $fh\->print( "Hello, World!");
\&    }
\&
\&    sub commit {
\&        my ($self) = @_;
\&        # this will be called at the end of the record stream
\&    }
\&
\&    1;
.Ve
.PP
This exporter can be called from the command line as:
.PP
.Vb 1
\&    $ catmandu convert JSON to Foo < data.json
.Ve
.PP
Or, via Perl
.PP
.Vb 1
\&    use Catmandu;
\&
\&    my $exporter = Catmandu\->exporter(\*(AqFoo\*(Aq, file => "/tmp/output.txt");
\&
\&    $exporter\->add({test => 123});
\&
\&    $exporter\->commit;
\&
\&    undef($exporter);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See function export_to_string in module
Catmandu.
.PP
The exporters Catmandu::Exporter::JSON, Catmandu::Exporter::YAML,
Catmandu::Exporter::CSV, and Catmandu::Exporter::Text are included in
Catmandu core.
.PP
See Catmandu::Importer for the opposite action.