NAME

       Catmandu::Exporter - Namespace for packages that can export

SYNOPSIS

           # 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('JSON', file => 'data.json');
           my $exporter = Catmandu->exporter('YAML');

           $exporter->add({ record => "one"});
           $exporter->add_many([ { record => "one" } , { record => "two" } ]);
           $exporter->add_many($importer);

           $exporter->commit;

           undef($exporter); # Clean up memory

DESCRIPTION

       A Catmandu::Exporter is a Perl package that can export data into JSON, YAML, XML or many
       other formats. By default, data is to STDOUT. Optionally provide a "file" or "fh"
       parameter to write to a file, string, or handle.

       Every Catmandu::Exporter is a Catmandu::Fixable thus provides a "fix" parameter and method
       to apply fixes to exported items:

           my $exporter = Catmandu->exporter('JSON', fix => ['upcase(title)']);

           # This will be printed to STDOUT like: {"title":"MY TITLE"}
           $exporter->add({ title => "my title"});

       Every Catmandu::Exporter is a Catmandu::Addable thus inherits the methods "add" and
       "add_many".

CONFIGURATION

       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.

       fh  Write the output to an IO::Handle. If not specified, Catmandu::Util::io is used to
           create the output handle from the "file" argument or by using STDOUT.

           It is the task of the Perl programmer to close any opened IO::Handles.  Catmandu will
           not do this by itself.

       encoding
           Binmode of the output stream "fh". Set to "":utf8"" by default.

       fix An ARRAY of one or more fixes or file scripts to be applied to exported items.

METHODS

   add
       Adds one item to be exported.

   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.

   count
       Returns the number of items exported by this Catmandu::Exporter.

   log
       Returns the current logger.

   commit
       Commit all buffers to the output handle.

CODING

       Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace
       that implements "Catmandu::Exporter". Basically, you need to create a method add which
       writes a Perl hash to a file handle:

           package Catmandu::Exporter::Foo;

           use Catmandu::Sane;
           use Moo;

           with 'Catmandu::Exporter'

           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;

       This exporter can be called from the command line as:

           $ catmandu convert JSON to Foo < data.json

       Or, via Perl

           use Catmandu;

           my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt");

           $exporter->add({test => 123});

           $exporter->commit;

           undef($exporter);

SEE ALSO

       See function export_to_string in module Catmandu.

       The exporters Catmandu::Exporter::JSON, Catmandu::Exporter::YAML, Catmandu::Exporter::CSV,
       and Catmandu::Exporter::Text are included in Catmandu core.

       See Catmandu::Importer for the opposite action.