=pod

=encoding utf8

=head1 NAME

Data::Embed::Writer - embed arbitrary data in a file - writer class

=head1 METHODS

=head2 new

Constructor.

   my $w = Data::Embed::Writer->new(%args);
   my $w = Data::Embed::Writer->new(\%args);

The difference between the two forms is that you can
pass either key-value pairs, or a hash reference with key-value
pairs. Acceptable keys are:

=over

=item C<output>

Optional parameter, where to send output data. If not present, undefined,
empty or set to the string C<->, then standard output will be considered.

If a filehandle is provided, it is expected to be seekable and will also
be C<binmode>-d in C<:raw> mode.

=item C<input>

Optional parameters, where to get initial data:

=over

=item *

if not present, no previous input will be considered.

=item *

if equal to the string C<->, the standard input will be considered

=item *

if equal to some other string, it will be considered a filename

=item *

if a reference to a scalar, it will be C<open()>ed

=item *

otherwise it will be considered a filehandle

=back

=back

This method throws an exception in case of errors. Returns a new object
in case of success.

=head2 B<< add >>

Catchall method for adding a section into the target file.

Expects a list of key-value pairs or a hash reference in input. The
recognised keys are:

=over

=item C<data>

a scalar from where data will be read. If you have a huge amount of
data, it's better to use the C<filename> key above passing a reference
to the scalar holding the data.

=item C<input>

do-what-I-mean so that you can pass:

=over

=item *

the string C<->, in which case standard input is assumed

=item *

any other string, or a reference to a scalar, in which case it is
treated as a filename (for the reference, it is the way to "read" from
the scalar)

=item *

otherwise, the input is assumed to be a filehandle

=back

=item C<inputs>

a reference to an array containing hash references, each with fields as
in this list, except for C<inputs> itself (i.e. this options is not
recursive)

=item C<name>

the name to associate to the section, optionally. If missing it will
be set to the empty string

=item C<filename>

a filename or a reference to a scalar where data will be read from

=item C<fh>

the filehandle from where data should be taken. The filehandle will be
exausted starting from its current position

=back

Options C<fh>, C<filename> and C<data> are exclusive and will be considered
in the order above (first come, first served).

This method does not return anything.

=head2 B<< add_file >>

Add one section from either a file or a reference to a scalar holding the
data (whatever suits C<open> anyway).

Takes two positional parameters:

=over

=item * name of the section (set to the empty string if undefined)

=item * filename or reference to the data

=back

Returns nothing.

=head2 B<< add_data >>

Add one section from a scalar holding the data.

Takes two positional parameters:

=over

=item * name of the section (set to the empty string if undefined)

=item * scalar holding the data to be added

=back

Returns nothing.

=head2 B<< add_fh >>

Add one section from a filehandle holding the data. The filehandle
will be read from its current position up to the end.

Takes two positional parameters:

=over

=item * name of the section (set to the empty string if undefined)

=item * filehandle

=back

Returns nothing.

=head2 B<< write_index >>

Write the index of the contained sections out to the output channel.
Doing this invalidates the object, so you should not perform any
further action after.

This gets automatically called upon object destruction, if not previously
called.

=head1 AUTHOR

Flavio Poletti <polettix@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2014-2016 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it
under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=cut
