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.

cpanm Catmandu

perl -MCPAN -e shell
install Catmandu