.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "IO::Capture 3pm" .TH IO::Capture 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "IO::Capture" \- Abstract Base Class to build modules to capture output. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`IO::Capture\*(C'\fR Module defines an abstract base class that can be used to build modules that capture output being sent on a filehandle such as \s-1STDOUT\s0 or \s-1STDERR.\s0 .PP Several modules that come with the distribution do just that. I.e., Capture \s-1STDOUT\s0 and \s-1STDERR.\s0 Also see James Keenan's \&\f(CW\*(C`IO::Capture::Stdout::Extended\*(C'\fR on \s-1CPAN.\s0 .PP See IO::Capture::Overview for a discussion of these modules and examples of how to build a module to sub-class from \f(CW\*(C`IO::Capture\*(C'\fR yourself. If after reading the overview, you would like to build a class from \f(CW\*(C`IO::Capture\*(C'\fR, look here for details on the internals. .SH "METHODS" .IX Header "METHODS" These are the methods defined in the \f(CW\*(C`IO::Capture\*(C'\fR Module. This page will be discussing the module from the point of view of someone who wants to build a sub-class of \f(CW\*(C`IO::Capture\*(C'\fR. .PP Each method defined in the \f(CW\*(C`IO::Capture\*(C'\fR Module defines a public method, that then calls one or more private methods. \fI(Names starting with an underscore)\fR 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. .PP Of these internal methods, three are abstract methods that your will \&\fBhave to\fR override if you want your module to \fBdo\fR anything. The three are \f(CW\*(C`_start()\*(C'\fR, \f(CW\*(C`_retrieve_captured_text()\*(C'\fR. and \f(CW\*(C`_stop()\*(C'\fR. .PP Below are the public methods with the private methods that each uses immediately following. .SS "new" .IX Subsection "new" The \f(CW\*(C`new\*(C'\fR method creates a new \f(CW\*(C`IO::Capture\*(C'\fR object, and returns it to its caller. The object is implemented with a hash. Each key used by \&\f(CW\*(C`IO::Capture\*(C'\fR is named with the class name. I.e., 'IO::Capture::'. 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 \fBnew()\fR. .PP .Vb 1 \& my $capture = IO::Capture\->new( { Key => \*(Aqvalue\*(Aq } ); .Ve .PP All elements from this hash will be added to the object, and will be available for use by children of IO::Capture. .PP .Vb 1 \& my $key = $self\->{\*(AqKey\*(Aq}; .Ve .PP The internal methods used are: .ie n .IP """_initialize()""" 4 .el .IP "\f(CW_initialize()\fR" 4 .IX Item "_initialize()" \&\f(CW\*(C`_initialize\*(C'\fR is called as soon as the empty object has been blessed. It adds the structure to the object that it will need. The \f(CW\*(C`IO::Capture\*(C'\fR module adds the following .Sp .Vb 3 \& IO::Capture::messages => [] \& IO::Capture::line_pointer => 1 \& IO::Capture::status => \*(AqReady\*(Aq, # Busy when capturing .Ve .SS "start" .IX Subsection "start" The \f(CW\*(C`start\*(C'\fR method is responsible for saving the current state of the filehandle and or signal hander, and starting the data capture. .PP Start cannot be called if there is already a capture in progress. The \&\f(CW\*(C`stop\*(C'\fR must be called first. .PP These internal methods are called in this order. .ie n .IP """_check_pre_conditions""" 4 .el .IP "\f(CW_check_pre_conditions\fR" 4 .IX Item "_check_pre_conditions" \&\f(CW\*(C`_check_pre_conditions\*(C'\fR is used to make sure all the preconditions are met before starting a capture. The only precondition checked in \&\f(CW\*(C`IO::Capture\*(C'\fR, is to insure the \*(L"Ready\*(R" flag is \*(L"on\*(R". I.e., There is not already a capture in progress. .Sp If your module needs to make some checks, and you override this method, make sure you call the parent class \f(CW\*(C`_check_pre_conditions\*(C'\fR and check the results. .Sp .Vb 2 \& sub _check_pre_conditions { \& my $self = shift; \& \& return unless $self\->SUPER::_check_pre_conditions; .Ve .Sp An example of something you might want to check would be, to make sure \s-1STDERR\s0 is not already \fItied\fR if you are going to be using \f(CW\*(C`tie\*(C'\fR on it. .Sp \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function, and an remaining private methods for \f(CW\*(C`start\*(C'\fR will \&\fBnot\fR be run. .ie n .IP """_save_current_configuration()""" 4 .el .IP "\f(CW_save_current_configuration()\fR" 4 .IX Item "_save_current_configuration()" \&\f(CW\*(C`_save_current_configuration\*(C'\fR in \f(CW\*(C`IO::Capture\*(C'\fR will save the state of \&\f(CW\*(C`STDERR\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, and \f(CW$SIG\fR{_\|_WARN_\|_}. They are saved in the hash keys 'IO::Capture::stderr_save', 'IO::Capture::stdout_save', and \&'IO::Capture::handler_save'. .Sp .Vb 10 \& # Save WARN handler \& $self\->{\*(AqIO::Capture::handler_save\*(Aq} = $SIG{_\|_WARN_\|_}; \& # Dup stdout \& open STDOUT_SAVE, ">&STDOUT"; \& # Save ref to dup \& $self\->{\*(AqIO::Capture::stdout_save\*(Aq} = *STDOUT_SAVE; \& # Dup stderr \& open STDERR_SAVE, ">&STDOUT"; \& # Save ref to dup \& $self\->{\*(AqIO::Capture::stderr_save\*(Aq} = *STDERR_SAVE; .Ve .Sp These saved values can be used in the \f(CW\*(C`_stop\*(C'\fR method to restore the original value to any you changed. .Sp .Vb 3 \& $SIG{_\|_WARN_\|_} = $self\->{\*(AqIO::Capture::handler_save\*(Aq}; \& STDOUT = $self\->{\*(AqIO::Capture::stdout_save\*(Aq}; \& STDERR = $self\->{\*(AqIO::Capture::stderr_save\*(Aq}; .Ve .Sp \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function. .ie n .IP """_start""" 4 .el .IP "\f(CW_start\fR" 4 .IX Item "_start" \&\fBStart the capture!\fR This is only an abstract method in \f(CW\*(C`IO::Capture\*(C'\fR. 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. :\-) .Sp This is the first of the three you need to define. You will likely use tie here. The included module \f(CW\*(C`IO::Capture:STDx\*(C'\fR (see IO::Capture::STDx or other module of your own or from \s-1CPAN.\s0 You will read it from the tied module and put it into the object in \f(CW\*(C`_retrieve_captured_text\*(C'\fR. See _retrieve_captured_text .Sp \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function. .SS "stop" .IX Subsection "stop" Stop capturing and return any filehandles and interrupt handlers that were changed, to their pre-start state. This \fBmust\fR be called \fBbefore\fR calling \&\f(CW\*(C`read()\*(C'\fR. If you are looking for a way to interact with the process on the other side of the filehandle, take a look at the \*(L"Other Modules on \s-1CPAN\*(R"\s0. .PP \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function. .ie n .IP """_retrieve_captured_text()""" 4 .el .IP "\f(CW_retrieve_captured_text()\fR" 4 .IX Item "_retrieve_captured_text()" Copy any text captured into the object here. For example, The modules in this package tie the filehandle to the (included) \f(CW\*(C`IO::Capture::STDx\*(C'\fR 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 \&\f(CW\*(C`_stop\*(C'\fR is called, do it here. The \f(CW\*(C`_retrieve_capture_text\*(C'\fR in this base class just returns true without doing anything. .Sp \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function. The \f(CW\*(C`_stop\*(C'\fR internal method will be called first. .ie n .IP """_stop""" 4 .el .IP "\f(CW_stop\fR" 4 .IX Item "_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 \f(CW\*(C`_stop\*(C'\fR method defined in won't do anything, so you should. .Sp \&\fBMust\fR return a boolean true for success, or false for failure. If a failure is indicated, an \f(CW\*(C`undef\*(C'\fR will be returned to the calling function. .SS "read" .IX Subsection "read" The \f(CW\*(C`read\*(C'\fR method is responsible for returning the data captured in the object. These internal methods will be run, in this order. .ie n .IP """_read()""" 4 .el .IP "\f(CW_read()\fR" 4 .IX Item "_read()" The internal method used to return the captured text. If called in \fIlist context\fR, an array will be returned. (Could be a lot if you captured a lot) or called in \fIscalar context\fR, the line pointed to by the \fIline_pointer\fR will be returned and the \fIline_pointer\fR incremented. .SH "Other Modules on CPAN" .IX Header "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. .IP "\(bu" 4 IO::Filter \- Generic input/output filters for Perl \s-1IO\s0 handles .IP "\(bu" 4 Expect \- Expect for Perl .IP "\(bu" 4 Tie::Syslog \- Tie a filehandle to Syslog. If you Tie \s-1STDERR,\s0 then all \&\s-1STDERR\s0 errors are automatically caught, or you can debug by Carp'ing to \&\s-1STDERR,\s0 etc. (Good for \s-1CGI\s0 error logging.) .IP "\(bu" 4 FileHandle::Rollback \- FileHandle with commit and rollback .SH "See Also" .IX Header "See Also" IO::Capture::Overview .PP IO::Capture::Stdout .PP IO::Capture::Stderr .SH "AUTHORS" .IX Header "AUTHORS" Mark Reynolds reynoldssgi.com .PP Jon Morgan jmorgansgi.com .SH "MAINTAINED" .IX Header "MAINTAINED" Maintained by Mark Reynolds. reynoldssgi.com .SH "COPYRIGHT" .IX Header "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.