1IO::Capture(3)        User Contributed Perl Documentation       IO::Capture(3)
2
3
4

NAME

6       "IO::Capture" - Abstract Base Class to build modules to capture output.
7

DESCRIPTION

9       The "IO::Capture" Module defines an abstract base class that can be
10       used to build modules that capture output being sent on a filehandle
11       such as STDOUT or STDERR.
12
13       Several modules that come with the distribution do just that.  I.e.,
14       Capture STDOUT and STDERR.   Also see James Keenan's
15       "IO::Capture::Stdout::Extended" on CPAN.
16
17       See IO::Capture::Overview for a discussion of these modules and
18       examples of how to build a module to sub-class from "IO::Capture"
19       yourself.   If after reading the overview, you would like to build a
20       class from "IO::Capture", look here for details on the internals.
21

METHODS

23       These are the methods defined in the "IO::Capture" Module.  This page
24       will be discussing the module from the point of view of someone who
25       wants to build a sub-class of "IO::Capture".
26
27       Each method defined in the "IO::Capture" Module defines a public
28       method, that then calls one or more private methods.  (Names starting
29       with an underscore)  This allows you to override methods at a finer
30       level of granularity, re-using as much of the functionality provided in
31       the module as possible.
32
33       Of these internal methods, three are abstract methods that your will
34       have to override if you want your module to do anything.  The three are
35       _start(),  _retrieve_captured_text().  and _stop().
36
37       Below are the public methods with the private methods that each uses
38       immediately following.
39
40   new
41       The "new" method creates a new "IO::Capture" object, and returns it to
42       its caller.  The object is implemented with a hash.  Each key used by
43       "IO::Capture" is named with the class name.  I.e.,
44       'IO::Capture::<key_name>'.  This is to prevent name clashes with keys
45       added by sub-class authors.  Attributes can be set in the object by
46       passing a hash reference as a single argument to new().
47
48           my $capture = IO::Capture->new( { Key => 'value' } );
49
50       All elements from this hash will be added to the object, and will be
51       available for use by children of IO::Capture.
52
53           my $key = $self->{'Key'};
54
55       The internal methods used are:
56
57       _initialize()
58           "_initialize" is called as soon as the empty object has been
59           blessed.  It adds the structure to the object that it will need.
60           The "IO::Capture" module adds the following
61
62               IO::Capture::messages      => []
63               IO::Capture::line_pointer  =>  1
64               IO::Capture::status        =>  'Ready',  # Busy when capturing
65
66   start
67       The "start" method is responsible for saving the current state of the
68       filehandle and or signal hander, and starting the data capture.
69
70       Start cannot be called if there is already a capture in progress.  The
71       "stop" must be called first.
72
73       These internal methods are called in this order.
74
75       "_check_pre_conditions"
76           "_check_pre_conditions" is used to make sure all the preconditions
77           are met before starting a capture. The only precondition checked in
78           "IO::Capture", is to insure the "Ready" flag is "on".  I.e., There
79           is not already a capture in progress.
80
81           If your module needs to make some checks, and you override this
82           method, make sure you call the parent class "_check_pre_conditions"
83           and check the results.
84
85               sub _check_pre_conditions {
86                   my $self = shift;
87
88                   return unless $self->SUPER::_check_pre_conditions;
89
90           An example of something you might want to check would be, to make
91           sure STDERR is not already tied if you are going to be using "tie"
92           on it.
93
94           Must return a boolean true for success, or false for failure.  If a
95           failure is indicated, an "undef" will be returned to the calling
96           function, and an remaining private methods for "start" will not be
97           run.
98
99       _save_current_configuration()
100           "_save_current_configuration" in "IO::Capture" will save the state
101           of "STDERR", "STDOUT", and $SIG{__WARN__}.  They are saved in the
102           hash keys 'IO::Capture::stderr_save', 'IO::Capture::stdout_save',
103           and 'IO::Capture::handler_save'.
104
105               # Save WARN handler
106               $self->{'IO::Capture::handler_save'} = $SIG{__WARN__};
107               # Dup stdout
108               open STDOUT_SAVE, ">&STDOUT";
109               # Save ref to dup
110               $self->{'IO::Capture::stdout_save'} = *STDOUT_SAVE;
111               # Dup stderr
112               open STDERR_SAVE, ">&STDOUT";
113               # Save ref to dup
114               $self->{'IO::Capture::stderr_save'} = *STDERR_SAVE;
115
116           These saved values can be used in the "_stop" method to restore the
117           original value to any you changed.
118
119               $SIG{__WARN__} = $self->{'IO::Capture::handler_save'};
120               STDOUT = $self->{'IO::Capture::stdout_save'};
121               STDERR = $self->{'IO::Capture::stderr_save'};
122
123           Must return a boolean true for success, or false for failure.  If a
124           failure is indicated, an "undef" will be returned to the calling
125           function.
126
127       "_start"
128           Start the capture!  This is only an abstract method in
129           "IO::Capture".  It will print a warning if called.  Which should
130           not happen, as the author of the sub-class will always be sure to
131           override it with her/his own.  :-)
132
133           This is the first of the three you need to define.  You will likely
134           use tie here.  The included module "IO::Capture:STDx" (see
135           IO::Capture::STDx or other module of your own or from CPAN.  You
136           will read it from the tied module and put it into the object in
137           "_retrieve_captured_text".  See _retrieve_captured_text
138
139           Must return a boolean true for success, or false for failure.  If a
140           failure is indicated, an "undef" will be returned to the calling
141           function.
142
143   stop
144       Stop capturing and return any filehandles and interrupt handlers that
145       were changed, to their pre-start state.  This must be called before
146       calling read().  If you are looking for a way to interact with the
147       process on the other side of the filehandle, take a look at the "Other
148       Modules on CPAN".
149
150       Must return a boolean true for success, or false for failure.  If a
151       failure is indicated, an "undef" will be returned to the calling
152       function.
153
154       _retrieve_captured_text()
155           Copy any text captured into the object here.  For example, The
156           modules in this package tie the filehandle to the (included)
157           "IO::Capture::STDx" to collect the text.  The data needs to be read
158           out of the tied object before the filehandle is untied, so that is
159           done here.  In short, if you need to do any work before "_stop" is
160           called, do it here.  The "_retrieve_capture_text" in this base
161           class just returns true without doing anything.
162
163           Must return a boolean true for success, or false for failure.  If a
164           failure is indicated, an "undef" will be returned to the calling
165           function.  The "_stop" internal method will be called first.
166
167       "_stop"
168           Do what needs to be done to put things back.  Such as untie
169           filehandles and put interrupt handlers back to what they were.  The
170           default "_stop" method defined in <IO::Capture> won't do anything,
171           so you should.
172
173           Must return a boolean true for success, or false for failure.  If a
174           failure is indicated, an "undef" will be returned to the calling
175           function.
176
177   read
178       The "read" method is responsible for returning the data captured in the
179       object.  These internal methods will be run, in this order.
180
181       _read()
182           The internal method used to return the captured text.  If called in
183           list context, an array will be returned.  (Could be a lot if you
184           captured a lot) or called in scalar context, the line pointed to by
185           the line_pointer will be returned and the line_pointer incremented.
186

Other Modules on CPAN

188       If this module is not exactly what you were looking for, take a look at
189       these.  Maybe one of them will fit the bill.
190
191       •   IO::Filter - Generic input/output filters for Perl IO handles
192
193       •   Expect - Expect for Perl
194
195       •   Tie::Syslog - Tie a filehandle to Syslog.  If you Tie STDERR, then
196           all STDERR errors are automatically caught, or you can debug by
197           Carp'ing to STDERR, etc.  (Good for CGI error logging.)
198
199       •   FileHandle::Rollback - FileHandle with commit and rollback
200

See Also

202       IO::Capture::Overview
203
204       IO::Capture::Stdout
205
206       IO::Capture::Stderr
207

AUTHORS

209       Mark Reynolds reynolds<at>sgi.com
210
211       Jon Morgan jmorgan<at>sgi.com
212

MAINTAINED

214       Maintained by Mark Reynolds. reynolds<at>sgi.com
215
217       Copyright (c) 2003      Mark Reynolds and Jon Morgan Copyright (c)
218       2004-2005 Mark Reynolds All Rights Reserved.  This module is free
219       software.  It may be used, redistributed and/or modified under the same
220       terms as Perl itself.
221
222
223
224perl v5.38.0                      2023-07-20                    IO::Capture(3)
Impressum