IO::Capture - Abstract Base Class to build modules to capture output.
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 the IO::Capture::Overview manpage 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.
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.
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
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
the IO::Capture::STDx manpage 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 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.
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.
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
the IO::Capture::Overview manpage
the IO::Capture::Stdout manpage
the IO::Capture::Stderr manpage
Mark Reynolds reynolds<at>sgi.com
Jon Morgan jmorgan<at>sgi.com
Maintained by Mark Reynolds. reynolds<at>sgi.com
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.