NAME

Data::Tubes::Util::Output

DESCRIPTION

Class for automatic handling of output files, with tracking capabilies for written records/characters and automatic generation of file names in a sequence. It is also possible to set a header that will be automatically written when a file is opened, and a footer for when the file is closed. This automatic handling is the main reason why this module is object-oriented (as the DESTROY method takes care to print out the footer in case it has not been written yet, but the file is open).

The class is realized via Mo. You can extend it, to a certain degree.

CLASS METHODS

new

   my oh = Data::Tubes::Util::Output->new(%args);

constructor for the class.

writer

   my oh = Data::Tubes::Util::Output->writer(%args);

shorthand to create a Data::Tubes::Util::Output object (via "new", passing %args) and return a sub reference that will delegate to "print" at each call.

ACCESSOR METHODS

binmode

value used for calling binmode after a file is opened;

footer

a footer that will be written at the end of a file, just before it is closed;

header

a header that will be written in every newly opened file, just after it has been opened;

interlude

a string that will be written between two successive prints;

output

whatever is set as an output channel. It might be multiple things:

factory

i.e. a subroutine reference, that will be used every time a new file will be needed. It is supposed to return either a filehandle or a filename; in case a filehandle is returned, it will not be passed through binmode but it will be closed eventually;

filehandle

this will be used as the output channel. It will not be closed automatically;

filename

this will be opened and then binmode will be called on the resulting filehandle. This handle will be eventually closed.

A valid filename (either set as output or returned by the factory) can be whatever is good for plain old open, i.e. a real filename or a reference to a string.

policy

a policy is a hash containing rules associated to the handler, whatever it means. By default, it can contain either records_threshold or characters_threshold (or both), that will be used as thresholds for printint out records/characters. If you extend this class you can of course implement your own policies.

track

a hash reference that tracks the printing process. You should usually not need to fiddle with this... or you'd better take a look at the code.

BUSINESS LOGIC METHODS

checker

   my $checker = $o->checker();

returns a checking function to be used after every call to "print". The function will be called with the object, so a method is good as well. If the class contains a check method, it will be used.

In case check is not present, the "default_check" will be used if a "policy" is set, nothing otherwise (and this is the reason why we don't set a check method in this base class).

close

   $o->close($filehandle, $tracker);

print the footer, then "release_fh". If you just want to close... call "just_close".

default_check

a checker function that uses the policy as described in "policy". See "checker".

get_fh

   my ($fh, $releaser) = $o->get_fh($channel);

get a filehandle, whatever the $channel is. If $channel is not provided, then "output" will be used. See "output" to see what $channel should be.

Returns a filehandle and a releaser for the filehandle. This will be called when it's time to close the filehandle, so if you override this you have to provide both the opened handle and this releasing functionality.

just_close

close whatever is open, flushing the footer if needed.

open

   my $filehandle = $o->open($channel);

opens a handle based on the $channel or whatever "output" gives back. Resets a few counters in the tracking object, then calls "get_fh", prints the header on the new handle, and eventually returns the handle.

print

   $o->print($iterator); # OR
   $o->print(@records);

prints things out. Accepts as input either an iterator or a list of records, where an iterator is a reference to a sub that will emit a record at each call. In this context, a valid record is everything that is not undef (and that is possible to print, of course).

If "interlude" is set, each record that is printed is prefixed with its value, except for the very first one.

release_fh

   $o->release_fh($filehandle);

uses the filehandle releaser (see "open"), if present, then gets rid of the currently tracked filehandle.

SEE ALSO

Data::Tubes is a valid entry point of all of this.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 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.

cpanm Data::Tubes

perl -MCPAN -e shell
install Data::Tubes