1IO::Capture(3) User Contributed Perl Documentation IO::Capture(3)
2
6 "IO::Capture" - Abstract Base Class to build modules to capture output.
7
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 Several modules that come with the distribution do just that. I.e.,
14 Capture STDOUT and STDERR. Also see James Keenan's "IO::Capture::Std‐
15 out::Extended" on CPAN.
16 See IO::Capture::Overview for a discussion of these modules and exam‐
18 ples of how to build a module to sub-class from "IO::Capture" yourself.
19 If after reading the overview, you would like to build a class from
20 "IO::Capture", look here for details on the internals.
21
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 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 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 Below are the public methods with the private methods that each uses
38 immediately following.
39 new
41 The "new" method creates a new "IO::Capture" object, and returns it to
43 its caller. The object is implemented with a hash. Each key used by
44 "IO::Capture" is named with the class name. I.e., 'IO::Cap‐
45 ture::<key_name>'. This is to prevent name clashes with keys added by
46 sub-class authors. Attributes can be set in the object by passing a
47 hash reference as a single argument to new().
48 my $capture = IO::Capture->new( { Key => 'value' } );
50 All elements from this hash will be added to the object, and will be
52 available for use by children of IO::Capture.
53 my $key = $self->{'Key'};
55 The internal methods used are:
57 "_initialize()"
59 "_initialize" is called as soon as the empty object has been
60 blessed. It adds the structure to the object that it will need.
61 The "IO::Capture" module adds the following
62 IO::Capture::messages => []
64 IO::Capture::line_pointer => 1
65 IO::Capture::status => 'Ready', # Busy when capturing
66 start
68 The "start" method is responsible for saving the current state of the
70 filehandle and or signal hander, and starting the data capture.
71 Start cannot be called if there is already a capture in progress. The
73 "stop" must be called first.
74 These internal methods are called in this order.
76 "_check_pre_conditions"
78 "_check_pre_conditions" is used to make sure all the preconditions
79 are met before starting a capture. The only precondition checked in
80 "IO::Capture", is to insure the "Ready" flag is "on". I.e., There
81 is not already a capture in progress.
82 If your module needs to make some checks, and you override this
84 method, make sure you call the parent class "_check_pre_conditions"
85 and check the results.
86 sub _check_pre_conditions {
88 my $self = shift;
89 return unless $self->SUPER::_check_pre_conditions;
91 An example of something you might want to check would be, to make
93 sure STDERR is not already tied if you are going to be using "tie"
94 on it.
95 Must return a boolean true for success, or false for failure. If a
97 failure is indicated, an "undef" will be returned to the calling
98 function, and an remaining private methods for "start" will not be
99 run.
100 "_save_current_configuration()"
102 "_save_current_configuration" in "IO::Capture" will save the state
103 of "STDERR", "STDOUT", and $SIG{__WARN__}. They are saved in the
104 hash keys 'IO::Capture::stderr_save', 'IO::Capture::stdout_save',
105 and 'IO::Capture::handler_save'.
106 # Save WARN handler
108 $self->{'IO::Capture::handler_save'} = $SIG{__WARN__};
109 # Dup stdout
110 open STDOUT_SAVE, ">&STDOUT";
111 # Save ref to dup
112 $self->{'IO::Capture::stdout_save'} = *STDOUT_SAVE;
113 # Dup stderr
114 open STDERR_SAVE, ">&STDOUT";
115 # Save ref to dup
116 $self->{'IO::Capture::stderr_save'} = *STDERR_SAVE;
117 These saved values can be used in the "_stop" method to restore the
119 original value to any you changed.
120 $SIG{__WARN__} = $self->{'IO::Capture::handler_save'};
122 STDOUT = $self->{'IO::Capture::stdout_save'};
123 STDERR = $self->{'IO::Capture::stderr_save'};
124 Must return a boolean true for success, or false for failure. If a
126 failure is indicated, an "undef" will be returned to the calling
127 function.
128 "_start"
130 Start the capture! This is only an abstract method in "IO::Cap‐
131 ture". It will print a warning if called. Which should not hap‐
132 pen, as the author of the sub-class will always be sure to override
133 it with her/his own. :-)
134 This is the first of the three you need to define. You will likely
136 use tie here. The included module "IO::Capture:STDx" (see IO::Cap‐
137 ture::STDx or other module of your own or from CPAN. You will read
138 it from the tied module and put it into the object in
139 "_retrieve_captured_text". See _retrieve_captured_text
140 Must return a boolean true for success, or false for failure. If a
142 failure is indicated, an "undef" will be returned to the calling
143 function.
144 stop
146 Stop capturing and return any filehandles and interrupt handlers that
148 were changed, to their pre-start state. This must be called before
149 calling "read()". If you are looking for a way to interact with the
150 process on the other side of the filehandle, take a look at the "Other
151 Modules on CPAN".
152 Must return a boolean true for success, or false for failure. If a
154 failure is indicated, an "undef" will be returned to the calling func‐
155 tion.
156 "_retrieve_captured_text()"
158 Copy any text captured into the object here. For example, The mod‐
159 ules in this package tie the filehandle to the (included) "IO::Cap‐
160 ture::STDx" to collect the text. The data needs to be read out of
161 the tied object before the filehandle is untied, so that is done
162 here. In short, if you need to do any work before "_stop" is
163 called, do it here. The "_retrieve_capture_text" in this base
164 class just returns true without doing anything.
165 Must return a boolean true for success, or false for failure. If a
167 failure is indicated, an "undef" will be returned to the calling
168 function. The "_stop" internal method will be called first.
169 "_stop"
171 Do what needs to be done to put things back. Such as untie file‐
172 handles and put interrupt handlers back to what they were. The
173 default "_stop" method defined in <IO::Capture> won't do anything,
174 so you should.
175 Must return a boolean true for success, or false for failure. If a
177 failure is indicated, an "undef" will be returned to the calling
178 function.
179 read
181 The "read" method is responsible for returning the data captured in the
183 object. These internal methods will be run, in this order.
184 "_read()"
186 The internal method used to return the captured text. If called in
187 list context, an array will be returned. (Could be a lot if you
188 captured a lot) or called in scalar context, the line pointed to by
189 the line_pointer will be returned and the line_pointer incremented.
190
192 If this module is not exactly what you were looking for, take a look at
193 these. Maybe one of them will fit the bill.
194 · IO::Filter - Generic input/output filters for Perl IO handles
196 · Expect - Expect for Perl
198 · Tie::Syslog - Tie a filehandle to Syslog. If you Tie STDERR, then
200 all STDERR errors are automatically caught, or you can debug by
201 Carp'ing to STDERR, etc. (Good for CGI error logging.)
202 · FileHandle::Rollback - FileHandle with commit and rollback
204
206 IO::Capture::Overview
207 IO::Capture::Stdout
209 IO::Capture::Stderr
211
213 Mark Reynolds reynolds<at>sgi.com
214 Jon Morgan jmorgan<at>sgi.com
216
218 Maintained by Mark Reynolds. reynolds<at>sgi.com
219
221 Copyright (c) 2003 Mark Reynolds and Jon Morgan Copyright (c)
222 2004-2005 Mark Reynolds All Rights Reserved. This module is free soft‐
223 ware. It may be used, redistributed and/or modified under the same
224 terms as Perl itself.
225perl v5.8.8 2005-04-29 IO::Capture(3)