local-lib5/lib/perl5/Capture/Tiny.pod

   1 # Generated by Pod::WikiDoc version 0.18
   2
   3 =pod
   4
   5 =head1 NAME
   6
   7 Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external programs
   8
   9 =head1 VERSION
  10
  11 This documentation describes version 0.06.
  12
  13 =head1 SYNOPSIS
  14
  15      use Capture::Tiny qw/capture tee capture_merged tee_merged/;
  16
  17      ($stdout, $stderr) = capture {
  18        # your code here
  19      };
  20
  21      ($stdout, $stderr) = tee {
  22        # your code here
  23      };
  24
  25      $merged = capture_merged {
  26        # your code here
  27      };
  28
  29      $merged = tee_merged {
  30        # your code here
  31      };
  32
  33 =head1 DESCRIPTION
  34
  35 Capture::Tiny provides a simple, portable way to capture anything sent to
  36 STDOUT or STDERR, regardless of whether it comes from Perl, from XS code or
  37 from an external program.  Optionally, output can be teed so that it is
  38 captured while being passed through to the original handles.  Yes, it even
  39 works on Windows.  Stop guessing which of a dozen capturing modules to use in
  40 any particular situation and just use this one.
  41
  42 This module was heavily inspired by L<IO::CaptureOutput>, which provides
  43 similar functionality without the ability to tee output and with more
  44 complicated code and API.
  45
  46 =head1 USAGE
  47
  48 The following functions are available.  None are exported by default.
  49
  50 =head2 capture
  51
  52    ($stdout, $stderr) = capture \&code;
  53    $stdout = capture \&code;
  54
  55 The C<<< capture >>> function takes a code reference and returns what is sent to
  56 STDOUT and STDERR.  In scalar context, it returns only STDOUT.  If no output
  57 was received, returns an empty string.  Regardless of context, all output is
  58 captured -- nothing is passed to the existing handles.
  59
  60 It is prototyped to take a subroutine reference as an argument. Thus, it
  61 can be called in block form:
  62
  63    ($stdout, $stderr) = capture {
  64      # your code here ...
  65    };
  66
  67 =head2 capture_merged
  68
  69    $merged = capture_merged \&code;
  70
  71 The C<<< capture_merged >>> function works just like C<<< capture >>> except STDOUT and
  72 STDERR are merged. (Technically, STDERR is redirected to STDOUT before
  73 executing the function.)  If no output was received, returns an empty string.
  74 As with C<<< capture >>> it may be called in block form.
  75
  76 Caution: STDOUT and STDERR output in the merged result are not guaranteed to be
  77 properly ordered due to buffering.
  78
  79 =head2 tee
  80
  81    ($stdout, $stderr) = tee \&code;
  82    $stdout = tee \&code;
  83
  84 The C<<< tee >>> function works just like C<<< capture >>>, except that output is captured
  85 as well as passed on to the original STDOUT and STDERR.  As with C<<< capture >>> it
  86 may be called in block form.
  87
  88 =head2 tee_merged
  89
  90    $merged = tee_merged \&code;
  91
  92 The C<<< tee_merged >>> function works just like C<<< capture_merged >>> except that output
  93 is captured as well as passed on to STDOUT.  As with C<<< capture >>> it may be called
  94 in block form.
  95
  96 Caution: STDOUT and STDERR output in the merged result are not guaranteed to be
  97 properly ordered due to buffering.
  98
  99 =head1 LIMITATIONS
 100
 101 =head2 Portability
 102
 103 Portability is a goal, not a guarantee.  C<<< tee >>> requires fork, except on
 104 Windows where C<<< system(1, @cmd) >>> is used instead.  Not tested on any
 105 particularly esoteric platforms yet.
 106
 107 =head2 PerlIO layers
 108
 109 Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8' or
 110 ':crlf' when capturing.   Layers should be applied to STDOUT or STDERR I<before>
 111 the call to C<<< capture >>> or C<<< tee >>>.
 112
 113 =head2 Closed STDIN, STDOUT or STDERR
 114
 115 Capture::Tiny will work even if STDIN, STDOUT or STDERR have been previously
 116 closed.  However, since they may be reopened to capture or tee output, any code
 117 within the captured block that depends on finding them closed will, of course,
 118 not find them to be closed.  If they started closed, Capture::Tiny will reclose
 119 them again when the capture block finishes.
 120
 121 =head2 Scalar filehandles and STDIN, STDOUT or STDERR
 122
 123 If STDOUT or STDERR are reopened to scalar filehandles prior to the call to
 124 C<<< capture >>> or C<<< tee >>>, then Capture::Tiny will override the output handle for the
 125 duration of the C<<< capture >>> or C<<< tee >>> call and then send captured output to the
 126 output handle after the capture is complete.  (Requires Perl 5.8)
 127
 128 Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar
 129 reference.
 130
 131 =head2 Tied STDIN, STDOUT or STDERR
 132
 133 If STDOUT or STDERR are tied prior to the call to C<<< capture >>> or C<<< tee >>>, then
 134 Capture::Tiny will attempt to override the tie for the duration of the
 135 C<<< capture >>> or C<<< tee >>> call and then send captured output to the tied handle after
 136 the capture is complete.  (Requires Perl 5.8)
 137
 138 Capture::Tiny does not (yet) support resending utf8 encoded data to a tied
 139 STDOUT or STDERR handle.  Characters will appear as bytes.
 140
 141 Capture::Tiny attempts to preserve the semantics of tied STDIN, but capturing
 142 or teeing when STDIN is tied is currently broken on Windows.
 143
 144 =head2 Modifiying STDIN, STDOUT or STDERR during a capture
 145
 146 Attempting to modify STDIN, STDOUT or STDERR I<during> C<<< capture >>> or C<<< tee >>> is
 147 almost certainly going to cause problems.  Don't do that.
 148
 149 =head1 BUGS
 150
 151 Please report any bugs or feature requests using the CPAN Request Tracker.
 152 Bugs can be submitted through the web interface at
 153 L<http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny>
 154
 155 When submitting a bug or request, please include a test-file or a patch to an
 156 existing test-file that illustrates the bug or desired feature.
 157
 158 =head1 SEE ALSO
 159
 160 This is a selection of CPAN modules that provide some sort of output capture,
 161 albeit with various limitations that make them appropriate only in particular
 162 circumstances.  I'm probably missing some.  The long list is provided to show
 163 why I felt Capture::Tiny was necessary.
 164
 165 =over
 166
 167 =item *
 168
 169 L<IO::Capture>
 170
 171 =item *
 172
 173 L<IO::Capture::Extended>
 174
 175 =item *
 176
 177 L<IO::CaptureOutput>
 178
 179 =item *
 180
 181 L<IPC::Capture>
 182
 183 =item *
 184
 185 L<IPC::Cmd>
 186
 187 =item *
 188
 189 L<IPC::Open2>
 190
 191 =item *
 192
 193 L<IPC::Open3>
 194
 195 =item *
 196
 197 L<IPC::Open3::Simple>
 198
 199 =item *
 200
 201 L<IPC::Open3::Utils>
 202
 203 =item *
 204
 205 L<IPC::Run>
 206
 207 =item *
 208
 209 L<IPC::Run::SafeHandles>
 210
 211 =item *
 212
 213 L<IPC::Run::Simple>
 214
 215 =item *
 216
 217 L<IPC::Run3>
 218
 219 =item *
 220
 221 L<IPC::System::Simple>
 222
 223 =item *
 224
 225 L<Tee>
 226
 227 =item *
 228
 229 L<IO::Tee>
 230
 231 =item *
 232
 233 L<File::Tee>
 234
 235 =item *
 236
 237 L<Filter::Handle>
 238
 239 =item *
 240
 241 L<Tie::STDERR>
 242
 243 =item *
 244
 245 L<Tie::STDOUT>
 246
 247 =item *
 248
 249 L<Test::Output>
 250
 251 =back
 252
 253 =head1 AUTHOR
 254
 255 David A. Golden (DAGOLDEN)
 256
 257 =head1 COPYRIGHT AND LICENSE
 258
 259 Copyright (c) 2009 by David A. Golden. All rights reserved.
 260
 261 Licensed under Apache License, Version 2.0 (the "License").  You may not use
 262 this file except in compliance with the License.  A copy of the License was
 263 distributed with this file or you may obtain a copy of the License from
 264 http:E<sol>E<sol>www.apache.orgE<sol>licensesE<sol>LICENSE-2.0
 265
 266 Files produced as output though the use of this software, shall not be
 267 considered Derivative Works, but shall be considered the original work of the
 268 Licensor.
 269
 270 Unless required by applicable law or agreed to in writing, software
 271 distributed under the License is distributed on an "AS IS" BASIS,
 272 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 273 See the License for the specific language governing permissions and
 274 limitations under the License.
 275
 276