1Capture::Tiny(3) User Contributed Perl Documentation Capture::Tiny(3)
2
6 Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external
7 programs
8
10 This documentation describes version 0.08.
11
13 use Capture::Tiny qw/capture tee capture_merged tee_merged/;
14 ($stdout, $stderr) = capture {
16 # your code here
17 };
18 ($stdout, $stderr) = tee {
20 # your code here
21 };
22 $merged = capture_merged {
24 # your code here
25 };
26 $merged = tee_merged {
28 # your code here
29 };
30
32 Capture::Tiny provides a simple, portable way to capture anything sent
33 to STDOUT or STDERR, regardless of whether it comes from Perl, from XS
34 code or from an external program. Optionally, output can be teed so
35 that it is captured while being passed through to the original handles.
36 Yes, it even works on Windows. Stop guessing which of a dozen
37 capturing modules to use in any particular situation and just use this
38 one.
39 This module was heavily inspired by IO::CaptureOutput, which provides
41 similar functionality without the ability to tee output and with more
42 complicated code and API.
43
45 The following functions are available. None are exported by default.
46 capture
48 ($stdout, $stderr) = capture \&code;
49 $stdout = capture \&code;
50 The "capture" function takes a code reference and returns what is sent
52 to STDOUT and STDERR. In scalar context, it returns only STDOUT. If
53 no output was received, returns an empty string. Regardless of
54 context, all output is captured -- nothing is passed to the existing
55 handles.
56 It is prototyped to take a subroutine reference as an argument. Thus,
58 it can be called in block form:
59 ($stdout, $stderr) = capture {
61 # your code here ...
62 };
63 capture_merged
65 $merged = capture_merged \&code;
66 The "capture_merged" function works just like "capture" except STDOUT
68 and STDERR are merged. (Technically, STDERR is redirected to STDOUT
69 before executing the function.) If no output was received, returns an
70 empty string. As with "capture" it may be called in block form.
71 Caution: STDOUT and STDERR output in the merged result are not
73 guaranteed to be properly ordered due to buffering.
74 tee
76 ($stdout, $stderr) = tee \&code;
77 $stdout = tee \&code;
78 The "tee" function works just like "capture", except that output is
80 captured as well as passed on to the original STDOUT and STDERR. As
81 with "capture" it may be called in block form.
82 tee_merged
84 $merged = tee_merged \&code;
85 The "tee_merged" function works just like "capture_merged" except that
87 output is captured as well as passed on to STDOUT. As with "capture"
88 it may be called in block form.
89 Caution: STDOUT and STDERR output in the merged result are not
91 guaranteed to be properly ordered due to buffering.
92
94 Portability
95 Portability is a goal, not a guarantee. "tee" requires fork, except on
96 Windows where "system(1, @cmd)" is used instead. Not tested on any
97 particularly esoteric platforms yet.
98 PerlIO layers
100 Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8'
101 or ':crlf' when capturing. Layers should be applied to STDOUT or
102 STDERR before the call to "capture" or "tee".
103 Closed STDIN, STDOUT or STDERR
105 Capture::Tiny will work even if STDIN, STDOUT or STDERR have been
106 previously closed. However, since they may be reopened to capture or
107 tee output, any code within the captured block that depends on finding
108 them closed will, of course, not find them to be closed. If they
109 started closed, Capture::Tiny will reclose them again when the capture
110 block finishes.
111 Scalar filehandles and STDIN, STDOUT or STDERR
113 If STDOUT or STDERR are reopened to scalar filehandles prior to the
114 call to "capture" or "tee", then Capture::Tiny will override the output
115 handle for the duration of the "capture" or "tee" call and then send
116 captured output to the output handle after the capture is complete.
117 (Requires Perl 5.8)
118 Capture::Tiny attempts to preserve the semantics of STDIN opened to a
120 scalar reference.
121 Tied STDIN, STDOUT or STDERR
123 If STDOUT or STDERR are tied prior to the call to "capture" or "tee",
124 then Capture::Tiny will attempt to override the tie for the duration of
125 the "capture" or "tee" call and then send captured output to the tied
126 handle after the capture is complete. (Requires Perl 5.8)
127 Capture::Tiny does not (yet) support resending utf8 encoded data to a
129 tied STDOUT or STDERR handle. Characters will appear as bytes.
130 Capture::Tiny attempts to preserve the semantics of tied STDIN, but
132 capturing or teeing when STDIN is tied is currently broken on Windows.
133 Modifiying STDIN, STDOUT or STDERR during a capture
135 Attempting to modify STDIN, STDOUT or STDERR during "capture" or "tee"
136 is almost certainly going to cause problems. Don't do that.
137 No support for Perl 5.8.0
139 It's just too buggy when it comes to layers and UTF8.
140
142 Please report any bugs or feature requests using the CPAN Request
143 Tracker. Bugs can be submitted through the web interface at
144 http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny
145 <http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny>
146 When submitting a bug or request, please include a test-file or a patch
148 to an existing test-file that illustrates the bug or desired feature.
149
151 This is a selection of CPAN modules that provide some sort of output
152 capture, albeit with various limitations that make them appropriate
153 only in particular circumstances. I'm probably missing some. The long
154 list is provided to show why I felt Capture::Tiny was necessary.
155 · IO::Capture
157 · IO::Capture::Extended
159 · IO::CaptureOutput
161 · IPC::Capture
163 · IPC::Cmd
165 · IPC::Open2
167 · IPC::Open3
169 · IPC::Open3::Simple
171 · IPC::Open3::Utils
173 · IPC::Run
175 · IPC::Run::SafeHandles
177 · IPC::Run::Simple
179 · IPC::Run3
181 · IPC::System::Simple
183 · Tee
185 · IO::Tee
187 · File::Tee
189 · Filter::Handle
191 · Tie::STDERR
193 · Tie::STDOUT
195 · Test::Output
197
199 David A. Golden (DAGOLDEN)
200
202 Copyright (c) 2009 by David A. Golden. All rights reserved.
203 Licensed under Apache License, Version 2.0 (the "License"). You may
205 not use this file except in compliance with the License. A copy of the
206 License was distributed with this file or you may obtain a copy of the
207 License from http://www.apache.org/licenses/LICENSE-2.0
208 Files produced as output though the use of this software, shall not be
210 considered Derivative Works, but shall be considered the original work
211 of the Licensor.
212 Unless required by applicable law or agreed to in writing, software
214 distributed under the License is distributed on an "AS IS" BASIS,
215 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
216 implied. See the License for the specific language governing
217 permissions and limitations under the License.
218perl v5.12.1 2010-06-21 Capture::Tiny(3)