File Coverage

blib/lib/Catmandu/Exporter.pm

Criterion	Covered	Total	%
statement	13	13	100.0
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod	1	1	100.0
total	19	19	100.0

use Catmandu::Sane;

our $VERSION = '1.2018';

use Catmandu::Util qw(io);
use Moo::Role;
use namespace::clean;

with 'Catmandu::Logger';
with 'Catmandu::Addable';
with 'Catmandu::Counter';

has file => (is => 'ro', lazy => 1, default => sub {\*STDOUT},);

has fh => (
    is      => 'ro',
    lazy    => 1,
    default => sub {io($_[0]->file, mode => 'w', binmode => $_[0]->encoding)},
);

after add => sub {
    $_[0]->inc_count;
};


1;


=pod

=head1 NAME

Catmandu::Exporter - Namespace for packages that can export

=head1 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

=head1 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 C<file>
or C<fh> parameter to write to a file, string, or handle.

Every Catmandu::Exporter is a L<Catmandu::Fixable> thus provides a C<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 L<Catmandu::Addable> thus inherits the methods
C<add> and C<add_many>.

=head1 CONFIGURATION

=over

=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.

=item fh

Write the output to an L<IO::Handle>. If not specified,
L<Catmandu::Util::io|Catmandu::Util/IO-functions> is used to create the output
handle from the C<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.

=item encoding

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

=item fix

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

=back

=head1 METHODS

=head2 add

Adds one item to be exported.

=head2 add_many

Adds many items to be exported. This can be either an ARRAY-ref or
an L<Catmandu::Iterator>. Returns a true value when the export was
successful or undef on error.

=head2 count

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

=head2 log

Returns the current logger.

=head2 commit

Commit all buffers to the output handle.

=head1 CODING

Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace
that implements C<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);

=head1 SEE ALSO

See function L<export_to_string|Catmandu/export_to_string> in module
L<Catmandu>.

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

See L<Catmandu::Importer> for the opposite action.

=cut