| 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 |
|