IO::Capture(3) User Contributed Perl Documentation IO::Capture(3)NAME
"IO::Capture" - Abstract Base Class to build modules to capture output.
DESCRIPTION
The "IO::Capture" Module defines an abstract base class that can be
used to build modules that capture output being sent on a filehandle
such as STDOUT or STDERR.
Several modules that come with the distribution do just that. I.e.,
Capture STDOUT and STDERR. Also see James Keenan's
"IO::Capture::Stdout::Extended" on CPAN.
See IO::Capture::Overview for a discussion of these modules and
examples of how to build a module to sub-class from "IO::Capture"
yourself. If after reading the overview, you would like to build a
class from "IO::Capture", look here for details on the internals.
METHODS
These are the methods defined in the "IO::Capture" Module. This page
will be discussing the module from the point of view of someone who
wants to build a sub-class of "IO::Capture".
Each method defined in the "IO::Capture" Module defines a public
method, that then calls one or more private methods. (Names starting
with an underscore) This allows you to override methods at a finer
level of granularity, re-using as much of the functionality provided in
the module as possible.
Of these internal methods, three are abstract methods that your will
have to override if you want your module to do anything. The three are
"_start()", "_retrieve_captured_text()". and "_stop()".
Below are the public methods with the private methods that each uses
immediately following.
new
The "new" method creates a new "IO::Capture" object, and returns it to
its caller. The object is implemented with a hash. Each key used by
"IO::Capture" is named with the class name. I.e.,
'IO::Capture::<key_name>'. This is to prevent name clashes with keys
added by sub-class authors. Attributes can be set in the object by
passing a hash reference as a single argument to new().
my $capture = IO::Capture->new( { Key => 'value' } );
All elements from this hash will be added to the object, and will be
available for use by children of IO::Capture.
my $key = $self->{'Key'};
The internal methods used are:
"_initialize()"
"_initialize" is called as soon as the empty object has been
blessed. It adds the structure to the object that it will need.
The "IO::Capture" module adds the following
IO::Capture::messages => []
IO::Capture::line_pointer => 1
IO::Capture::status => 'Ready', # Busy when capturing
start
The "start" method is responsible for saving the current state of the
filehandle and or signal hander, and starting the data capture.
Start cannot be called if there is already a capture in progress. The
"stop" must be called first.
These internal methods are called in this order.
"_check_pre_conditions"
"_check_pre_conditions" is used to make sure all the preconditions
are met before starting a capture. The only precondition checked in
"IO::Capture", is to insure the "Ready" flag is "on". I.e., There
is not already a capture in progress.
If your module needs to make some checks, and you override this
method, make sure you call the parent class "_check_pre_conditions"
and check the results.
sub _check_pre_conditions {
my $self = shift;
return unless $self->SUPER::_check_pre_conditions;
An example of something you might want to check would be, to make
sure STDERR is not already tied if you are going to be using "tie"
on it.
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function, and an remaining private methods for "start" will not be
run.
"_save_current_configuration()"
"_save_current_configuration" in "IO::Capture" will save the state
of "STDERR", "STDOUT", and $SIG{__WARN__}. They are saved in the
hash keys 'IO::Capture::stderr_save', 'IO::Capture::stdout_save',
and 'IO::Capture::handler_save'.
# Save WARN handler
$self->{'IO::Capture::handler_save'} = $SIG{__WARN__};
# Dup stdout
open STDOUT_SAVE, ">&STDOUT";
# Save ref to dup
$self->{'IO::Capture::stdout_save'} = *STDOUT_SAVE;
# Dup stderr
open STDERR_SAVE, ">&STDOUT";
# Save ref to dup
$self->{'IO::Capture::stderr_save'} = *STDERR_SAVE;
These saved values can be used in the "_stop" method to restore the
original value to any you changed.
$SIG{__WARN__} = $self->{'IO::Capture::handler_save'};
STDOUT = $self->{'IO::Capture::stdout_save'};
STDERR = $self->{'IO::Capture::stderr_save'};
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function.
"_start"
Start the capture! This is only an abstract method in
"IO::Capture". It will print a warning if called. Which should
not happen, as the author of the sub-class will always be sure to
override it with her/his own. :-)
This is the first of the three you need to define. You will likely
use tie here. The included module "IO::Capture:STDx" (see
IO::Capture::STDx or other module of your own or from CPAN. You
will read it from the tied module and put it into the object in
"_retrieve_captured_text". See _retrieve_captured_text
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function.
stop
Stop capturing and return any filehandles and interrupt handlers that
were changed, to their pre-start state. This must be called before
calling "read()". If you are looking for a way to interact with the
process on the other side of the filehandle, take a look at the "Other
Modules on CPAN".
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function.
"_retrieve_captured_text()"
Copy any text captured into the object here. For example, The
modules in this package tie the filehandle to the (included)
"IO::Capture::STDx" to collect the text. The data needs to be read
out of the tied object before the filehandle is untied, so that is
done here. In short, if you need to do any work before "_stop" is
called, do it here. The "_retrieve_capture_text" in this base
class just returns true without doing anything.
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function. The "_stop" internal method will be called first.
"_stop"
Do what needs to be done to put things back. Such as untie
filehandles and put interrupt handlers back to what they were. The
default "_stop" method defined in <IO::Capture> won't do anything,
so you should.
Must return a boolean true for success, or false for failure. If a
failure is indicated, an "undef" will be returned to the calling
function.
read
The "read" method is responsible for returning the data captured in the
object. These internal methods will be run, in this order.
"_read()"
The internal method used to return the captured text. If called in
list context, an array will be returned. (Could be a lot if you
captured a lot) or called in scalar context, the line pointed to by
the line_pointer will be returned and the line_pointer incremented.
Other Modules on CPAN
If this module is not exactly what you were looking for, take a look at
these. Maybe one of them will fit the bill.
· IO::Filter - Generic input/output filters for Perl IO handles
· Expect - Expect for Perl
· Tie::Syslog - Tie a filehandle to Syslog. If you Tie STDERR, then
all STDERR errors are automatically caught, or you can debug by
Carp'ing to STDERR, etc. (Good for CGI error logging.)
· FileHandle::Rollback - FileHandle with commit and rollback
See Also
IO::Capture::Overview
IO::Capture::Stdout
IO::Capture::Stderr
AUTHORS
Mark Reynolds reynolds<at>sgi.com
Jon Morgan jmorgan<at>sgi.com
MAINTAINED
Maintained by Mark Reynolds. reynolds<at>sgi.com
COPYRIGHT
Copyright (c) 2003 Mark Reynolds and Jon Morgan Copyright (c)
2004-2005 Mark Reynolds All Rights Reserved. This module is free
software. It may be used, redistributed and/or modified under the same
terms as Perl itself.
perl v5.14.0 2005-04-30 IO::Capture(3)
