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
15 "IO::Capture::Stdout::Extended" on CPAN.
16 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
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
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 my $capture = IO::Capture->new( { Key => 'value' } );
49 All elements from this hash will be added to the object, and will be
51 available for use by children of IO::Capture.
52 my $key = $self->{'Key'};
54 The internal methods used are:
56 _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 IO::Capture::messages => []
63 IO::Capture::line_pointer => 1
64 IO::Capture::status => 'Ready', # Busy when capturing
65 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 Start cannot be called if there is already a capture in progress. The
71 "stop" must be called first.
72 These internal methods are called in this order.
74 "_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 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 sub _check_pre_conditions {
86 my $self = shift;
87 return unless $self->SUPER::_check_pre_conditions;
89 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 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 _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 # 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 These saved values can be used in the "_stop" method to restore the
117 original value to any you changed.
118 $SIG{__WARN__} = $self->{'IO::Capture::handler_save'};
120 STDOUT = $self->{'IO::Capture::stdout_save'};
121 STDERR = $self->{'IO::Capture::stderr_save'};
122 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 "_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 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 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 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 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 _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 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 "_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 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 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 _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
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 • IO::Filter - Generic input/output filters for Perl IO handles
192 • Expect - Expect for Perl
194 • 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 • FileHandle::Rollback - FileHandle with commit and rollback
200
202 IO::Capture::Overview
203 IO::Capture::Stdout
205 IO::Capture::Stderr
207
209 Mark Reynolds reynolds<at>sgi.com
210 Jon Morgan jmorgan<at>sgi.com
212
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.
221perl v5.38.0 2023-07-20 IO::Capture(3)