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