The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

METHODS

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:

output

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

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

input

Optional parameters, where to get initial data:

  • if not present, no previous input will be considered.

  • if equal to the string -, the standard input will be considered

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

  • if a reference to a scalar, it will be open()ed

  • otherwise it will be considered a filehandle

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

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:

data

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

input

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

  • the string -, in which case standard input is assumed

  • 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)

  • otherwise, the input is assumed to be a filehandle

inputs

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

name

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

filename

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

fh

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

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

This method does not return anything.

add_file

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

Takes two positional parameters:

  • name of the section (set to the empty string if undefined)

  • filename or reference to the data

Returns nothing.

add_data

Add one section from a scalar holding the data.

Takes two positional parameters:

  • name of the section (set to the empty string if undefined)

  • scalar holding the data to be added

Returns nothing.

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:

  • name of the section (set to the empty string if undefined)

  • filehandle

Returns nothing.

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.

AUTHOR

Flavio Poletti <polettix@cpan.org>

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.