package Catmandu::Exporter;

use Catmandu::Sane;

our $VERSION = '0.9505';

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

sub encoding { ':utf8' }

1;

__END__

=pod

=head1 NAME

Catmandu::Exporter - Namespace for packages that can export

=head1 SYNOPSIS

    package Catmandu::Exporter::Foo;

    use Catmandu::Sane;
    use Moo;

    with 'Catmandu::Exporter'

    sub add {
        my ($self, $data) = @_;
        my $fh = $self->fh;
        $fh->print( ... );
    }

    package main;

    use Catmandu;

    my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt");
    
    # Or on the command line
    $ catmandu convert JSON to Foo < /tmp/something.txt >/tmp/output.txt

=head1 DESCRIPTION

A Catmandu::Exporter is a Perl package that can export data. By default, data
items are written to STDOUT. Optionally provide a C<file> or C<fh> parameter to
write to a file, string, or handle. New exporter modules are expected to use the 
C<print> method of C<fh>.

Every Catmandu::Exporter is a L<Catmandu::Fixable> thus provides a C<fix>
parameter and method to apply fixes to exported items.

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.

=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 object to be exported. 

=head2 add_many

Adds many objects 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.

=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::RIS> are included in
Catmandu core.

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

=cut