++ed by:

3 PAUSE users
9 non-PAUSE users.

Nicolas Steenlant
and 17 contributors


Catmandu::Exporter - Namespace for packages that can export


    # 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" } ]);


    undef($exporter); # Clean up memory


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.



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.


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.


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


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



Adds one item to be exported.


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.


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


Returns the current logger.


Commit all buffers to the output handle.


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


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});




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.