Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.

       o   IO::Filter -	Generic	input/output filters for Perl IO handles

       o   Expect - Expect for Perl

       o   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.)

       o   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.32.1			  2005-04-30			IO::Capture(3)

NAME | DESCRIPTION | METHODS | Other Modules on CPAN | See Also | AUTHORS | MAINTAINED | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Capture&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help