Debian Codegraph @

README

raw
1 NAME
2 Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external
3 programs
4
5 VERSION
6 version 0.50
7
8 SYNOPSIS
9 use Capture::Tiny ':all';
10
11 # capture from external command
12
13 ($stdout, $stderr, $exit) = capture {
14 system( $cmd, @args );
15 };
16
17 # capture from arbitrary code (Perl or external)
18
19 ($stdout, $stderr, @result) = capture {
20 # your code here
21 };
22
23 # capture partial or merged output
24
25 $stdout = capture_stdout { ... };
26 $stderr = capture_stderr { ... };
27 $merged = capture_merged { ... };
28
29 # tee output
30
31 ($stdout, $stderr) = tee {
32 # your code here
33 };
34
35 $stdout = tee_stdout { ... };
36 $stderr = tee_stderr { ... };
37 $merged = tee_merged { ... };
38
39 DESCRIPTION
40 Capture::Tiny provides a simple, portable way to capture almost anything
41 sent to STDOUT or STDERR, regardless of whether it comes from Perl, from
42 XS code or from an external program. Optionally, output can be teed so
43 that it is captured while being passed through to the original
44 filehandles. Yes, it even works on Windows (usually). Stop guessing
45 which of a dozen capturing modules to use in any particular situation
46 and just use this one.
47
48 USAGE
49 The following functions are available. None are exported by default.
50
51 capture
52 ($stdout, $stderr, @result) = capture \&code;
53 $stdout = capture \&code;
54
55 The "capture" function takes a code reference and returns what is sent
56 to STDOUT and STDERR as well as any return values from the code
57 reference. In scalar context, it returns only STDOUT. If no output was
58 received for a filehandle, it returns an empty string for that
59 filehandle. Regardless of calling context, all output is captured --
60 nothing is passed to the existing filehandles.
61
62 It is prototyped to take a subroutine reference as an argument. Thus, it
63 can be called in block form:
64
65 ($stdout, $stderr) = capture {
66 # your code here ...
67 };
68
69 Note that the coderef is evaluated in list context. If you wish to force
70 scalar context on the return value, you must use the "scalar" keyword.
71
72 ($stdout, $stderr, $count) = capture {
73 my @list = qw/one two three/;
74 return scalar @list; # $count will be 3
75 };
76
77 Also note that within the coderef, the @_ variable will be empty. So
78 don't use arguments from a surrounding subroutine without copying them
79 to an array first:
80
81 sub wont_work {
82 my ($stdout, $stderr) = capture { do_stuff( @_ ) }; # WRONG
83 ...
84 }
85
86 sub will_work {
87 my @args = @_;
88 my ($stdout, $stderr) = capture { do_stuff( @args ) }; # RIGHT
89 ...
90 }
91
92 Captures are normally done to an anonymous temporary filehandle. To
93 capture via a named file (e.g. to externally monitor a long-running
94 capture), provide custom filehandles as a trailing list of option pairs:
95
96 my $out_fh = IO::File->new("out.txt", "w+");
97 my $err_fh = IO::File->new("err.txt", "w+");
98 capture { ... } stdout => $out_fh, stderr => $err_fh;
99
100 The filehandles must be read/write and seekable. Modifying the files or
101 filehandles during a capture operation will give unpredictable results.
102 Existing IO layers on them may be changed by the capture.
103
104 When called in void context, "capture" saves memory and time by not
105 reading back from the capture handles.
106
107 capture_stdout
108 ($stdout, @result) = capture_stdout \&code;
109 $stdout = capture_stdout \&code;
110
111 The "capture_stdout" function works just like "capture" except only
112 STDOUT is captured. STDERR is not captured.
113
114 capture_stderr
115 ($stderr, @result) = capture_stderr \&code;
116 $stderr = capture_stderr \&code;
117
118 The "capture_stderr" function works just like "capture" except only
119 STDERR is captured. STDOUT is not captured.
120
121 capture_merged
122 ($merged, @result) = capture_merged \&code;
123 $merged = capture_merged \&code;
124
125 The "capture_merged" function works just like "capture" except STDOUT
126 and STDERR are merged. (Technically, STDERR is redirected to the same
127 capturing handle as STDOUT before executing the function.)
128
129 Caution: STDOUT and STDERR output in the merged result are not
130 guaranteed to be properly ordered due to buffering.
131
132 tee
133 ($stdout, $stderr, @result) = tee \&code;
134 $stdout = tee \&code;
135
136 The "tee" function works just like "capture", except that output is
137 captured as well as passed on to the original STDOUT and STDERR.
138
139 When called in void context, "tee" saves memory and time by not reading
140 back from the capture handles, except when the original STDOUT or STDERR
141 were tied or opened to a scalar handle.
142
143 tee_stdout
144 ($stdout, @result) = tee_stdout \&code;
145 $stdout = tee_stdout \&code;
146
147 The "tee_stdout" function works just like "tee" except only STDOUT is
148 teed. STDERR is not teed (output goes to STDERR as usual).
149
150 tee_stderr
151 ($stderr, @result) = tee_stderr \&code;
152 $stderr = tee_stderr \&code;
153
154 The "tee_stderr" function works just like "tee" except only STDERR is
155 teed. STDOUT is not teed (output goes to STDOUT as usual).
156
157 tee_merged
158 ($merged, @result) = tee_merged \&code;
159 $merged = tee_merged \&code;
160
161 The "tee_merged" function works just like "capture_merged" except that
162 output is captured as well as passed on to STDOUT.
163
164 Caution: STDOUT and STDERR output in the merged result are not
165 guaranteed to be properly ordered due to buffering.
166
167 LIMITATIONS
168 Portability
169 Portability is a goal, not a guarantee. "tee" requires fork, except on
170 Windows where "system(1, @cmd)" is used instead. Not tested on any
171 particularly esoteric platforms yet. See the CPAN Testers Matrix
172 <http://matrix.cpantesters.org/?dist=Capture-Tiny> for test result by
173 platform.
174
175 PerlIO layers
176 Capture::Tiny does its best to preserve PerlIO layers such as ':utf8' or
177 ':crlf' when capturing (only for Perl 5.8.1+) . Layers should be applied
178 to STDOUT or STDERR *before* the call to "capture" or "tee". This may
179 not work for tied filehandles (see below).
180
181 Modifying filehandles before capturing
182 Generally speaking, you should do little or no manipulation of the
183 standard IO filehandles prior to using Capture::Tiny. In particular,
184 closing, reopening, localizing or tying standard filehandles prior to
185 capture may cause a variety of unexpected, undesirable and/or unreliable
186 behaviors, as described below. Capture::Tiny does its best to compensate
187 for these situations, but the results may not be what you desire.
188
189 Closed filehandles
190 Capture::Tiny will work even if STDIN, STDOUT or STDERR have been
191 previously closed. However, since they will be reopened to capture or
192 tee output, any code within the captured block that depends on finding
193 them closed will, of course, not find them to be closed. If they started
194 closed, Capture::Tiny will close them again when the capture block
195 finishes.
196
197 Note that this reopening will happen even for STDIN or a filehandle not
198 being captured to ensure that the filehandle used for capture is not
199 opened to file descriptor 0, as this causes problems on various
200 platforms.
201
202 Prior to Perl 5.12, closed STDIN combined with PERL_UNICODE=D leaks
203 filehandles and also breaks tee() for undiagnosed reasons. So don't do
204 that.
205
206 Localized filehandles
207 If code localizes any of Perl's standard filehandles before capturing,
208 the capture will affect the localized filehandles and not the original
209 ones. External system calls are not affected by localizing a filehandle
210 in Perl and will continue to send output to the original filehandles
211 (which will thus not be captured).
212
213 Scalar filehandles
214 If STDOUT or STDERR are reopened to scalar filehandles prior to the call
215 to "capture" or "tee", then Capture::Tiny will override the output
216 filehandle for the duration of the "capture" or "tee" call and then, for
217 "tee", send captured output to the output filehandle after the capture
218 is complete. (Requires Perl 5.8)
219
220 Capture::Tiny attempts to preserve the semantics of STDIN opened to a
221 scalar reference, but note that external processes will not be able to
222 read from such a handle. Capture::Tiny tries to ensure that external
223 processes will read from the null device instead, but this is not
224 guaranteed.
225
226 Tied output filehandles
227 If STDOUT or STDERR are tied prior to the call to "capture" or "tee",
228 then Capture::Tiny will attempt to override the tie for the duration of
229 the "capture" or "tee" call and then send captured output to the tied
230 filehandle after the capture is complete. (Requires Perl 5.8)
231
232 Capture::Tiny may not succeed resending UTF-8 encoded data to a tied
233 STDOUT or STDERR filehandle. Characters may appear as bytes. If the tied
234 filehandle is based on Tie::StdHandle, then Capture::Tiny will attempt
235 to determine appropriate layers like ":utf8" from the underlying
236 filehandle and do the right thing.
237
238 Tied input filehandle
239 Capture::Tiny attempts to preserve the semantics of tied STDIN, but this
240 requires Perl 5.8 and is not entirely predictable. External processes
241 will not be able to read from such a handle.
242
243 Unless having STDIN tied is crucial, it may be safest to localize STDIN
244 when capturing:
245
246 my ($out, $err) = do { local *STDIN; capture { ... } };
247
248 Modifying filehandles during a capture
249 Attempting to modify STDIN, STDOUT or STDERR *during* "capture" or "tee"
250 is almost certainly going to cause problems. Don't do that.
251
252 Forking inside a capture
253 Forks aren't portable. The behavior of filehandles during a fork is even
254 less so. If Capture::Tiny detects that a fork has occurred within a
255 capture, it will shortcut in the child process and return empty strings
256 for captures. Other problems may occur in the child or parent, as well.
257 Forking in a capture block is not recommended.
258
259 Using threads
260 Filehandles are global. Mixing up I/O and captures in different threads
261 without coordination is going to cause problems. Besides, threads are
262 officially discouraged.
263
264 Dropping privileges during a capture
265 If you drop privileges during a capture, temporary files created to
266 facilitate the capture may not be cleaned up afterwards.
267
268 No support for Perl 5.8.0
269 It's just too buggy when it comes to layers and UTF-8. Perl 5.8.1 or
270 later is recommended.
271
272 Limited support for Perl 5.6
273 Perl 5.6 predates PerlIO. UTF-8 data may not be captured correctly.
274
275 ENVIRONMENT
276 PERL_CAPTURE_TINY_TIMEOUT
277 Capture::Tiny uses subprocesses internally for "tee". By default,
278 Capture::Tiny will timeout with an error if such subprocesses are not
279 ready to receive data within 30 seconds (or whatever is the value of
280 $Capture::Tiny::TIMEOUT). An alternate timeout may be specified by
281 setting the "PERL_CAPTURE_TINY_TIMEOUT" environment variable. Setting it
282 to zero will disable timeouts. NOTE, this does not timeout the code
283 reference being captured -- this only prevents Capture::Tiny itself from
284 hanging your process waiting for its child processes to be ready to
285 proceed.
286
287 SEE ALSO
288 This module was inspired by IO::CaptureOutput, which provides similar
289 functionality without the ability to tee output and with more
290 complicated code and API. IO::CaptureOutput does not handle layers or
291 most of the unusual cases described in the "LIMITATIONS" section and I
292 no longer recommend it.
293
294 There are many other CPAN modules that provide some sort of output
295 capture, albeit with various limitations that make them appropriate only
296 in particular circumstances. I'm probably missing some. The long list is
297 provided to show why I felt Capture::Tiny was necessary.
298
299 * IO::Capture
300
301 * IO::Capture::Extended
302
303 * IO::CaptureOutput
304
305 * IPC::Capture
306
307 * IPC::Cmd
308
309 * IPC::Open2
310
311 * IPC::Open3
312
313 * IPC::Open3::Simple
314
315 * IPC::Open3::Utils
316
317 * IPC::Run
318
319 * IPC::Run::SafeHandles
320
321 * IPC::Run::Simple
322
323 * IPC::Run3
324
325 * IPC::System::Simple
326
327 * Tee
328
329 * IO::Tee
330
331 * File::Tee
332
333 * Filter::Handle
334
335 * Tie::STDERR
336
337 * Tie::STDOUT
338
339 * Test::Output
340
341 SUPPORT
342 Bugs / Feature Requests
343 Please report any bugs or feature requests through the issue tracker at
344 <https://github.com/dagolden/Capture-Tiny/issues>. You will be notified
345 automatically of any progress on your issue.
346
347 Source Code
348 This is open source software. The code repository is available for
349 public review and contribution under the terms of the license.
350
351 <https://github.com/dagolden/Capture-Tiny>
352
353 git clone https://github.com/dagolden/Capture-Tiny.git
354
355 AUTHOR
356 David Golden <[email protected]>
357
358 CONTRIBUTORS
359 * Dagfinn Ilmari MannsÃ¥ker <[email protected]>
360
361 * David E. Wheeler <[email protected]>
362
363 * Ed Sabol <[email protected]>
364
365 * fecundf <[email protected]>
366
367 * Graham Knop <[email protected]>
368
369 * Karen Etheridge <[email protected]>
370
371 * Mohammad S Anwar <[email protected]>
372
373 * Peter Rabbitson <[email protected]>
374
375 * Sven Kirmess <[email protected]>
376
377 COPYRIGHT AND LICENSE
378 This software is Copyright (c) 2009 by David Golden.
379
380 This is free software, licensed under:
381
382 The Apache License, Version 2.0, January 2004
383