local-lib5/man/man3/Capture::Tiny.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Capture::Tiny 3"
 132 .TH Capture::Tiny 3 "2009-05-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Capture::Tiny \- Capture STDOUT and STDERR from Perl, XS or external programs
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 This documentation describes version 0.06.
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \&     use Capture::Tiny qw/capture tee capture_merged tee_merged/;
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \&     ($stdout, $stderr) = capture {
 146 \&       # your code here
 147 \&     };
 148 .Ve
 149 .PP
 150 .Vb 3
 151 \&     ($stdout, $stderr) = tee {
 152 \&       # your code here
 153 \&     };
 154 .Ve
 155 .PP
 156 .Vb 3
 157 \&     $merged = capture_merged {
 158 \&       # your code here
 159 \&     };
 160 .Ve
 161 .PP
 162 .Vb 3
 163 \&     $merged = tee_merged {
 164 \&       # your code here
 165 \&     };
 166 .Ve
 167 .SH "DESCRIPTION"
 168 .IX Header "DESCRIPTION"
 169 Capture::Tiny provides a simple, portable way to capture anything sent to
 170 \&\s-1STDOUT\s0 or \s-1STDERR\s0, regardless of whether it comes from Perl, from \s-1XS\s0 code or
 171 from an external program.  Optionally, output can be teed so that it is
 172 captured while being passed through to the original handles.  Yes, it even
 173 works on Windows.  Stop guessing which of a dozen capturing modules to use in
 174 any particular situation and just use this one.
 175 .PP
 176 This module was heavily inspired by IO::CaptureOutput, which provides
 177 similar functionality without the ability to tee output and with more
 178 complicated code and \s-1API\s0.
 179 .SH "USAGE"
 180 .IX Header "USAGE"
 181 The following functions are available.  None are exported by default.
 182 .Sh "capture"
 183 .IX Subsection "capture"
 184 .Vb 2
 185 \&   ($stdout, $stderr) = capture \e&code;
 186 \&   $stdout = capture \e&code;
 187 .Ve
 188 .PP
 189 The \f(CW\*(C`capture\*(C'\fR function takes a code reference and returns what is sent to
 190 \&\s-1STDOUT\s0 and \s-1STDERR\s0.  In scalar context, it returns only \s-1STDOUT\s0.  If no output
 191 was received, returns an empty string.  Regardless of context, all output is
 192 captured \*(-- nothing is passed to the existing handles.
 193 .PP
 194 It is prototyped to take a subroutine reference as an argument. Thus, it
 195 can be called in block form:
 196 .PP
 197 .Vb 3
 198 \&   ($stdout, $stderr) = capture {
 199 \&     # your code here ...
 200 \&   };
 201 .Ve
 202 .Sh "capture_merged"
 203 .IX Subsection "capture_merged"
 204 .Vb 1
 205 \&   $merged = capture_merged \e&code;
 206 .Ve
 207 .PP
 208 The \f(CW\*(C`capture_merged\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR except \s-1STDOUT\s0 and
 209 \&\s-1STDERR\s0 are merged. (Technically, \s-1STDERR\s0 is redirected to \s-1STDOUT\s0 before
 210 executing the function.)  If no output was received, returns an empty string.
 211 As with \f(CW\*(C`capture\*(C'\fR it may be called in block form.
 212 .PP
 213 Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be
 214 properly ordered due to buffering.
 215 .Sh "tee"
 216 .IX Subsection "tee"
 217 .Vb 2
 218 \&   ($stdout, $stderr) = tee \e&code;
 219 \&   $stdout = tee \e&code;
 220 .Ve
 221 .PP
 222 The \f(CW\*(C`tee\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR, except that output is captured
 223 as well as passed on to the original \s-1STDOUT\s0 and \s-1STDERR\s0.  As with \f(CW\*(C`capture\*(C'\fR it
 224 may be called in block form.
 225 .Sh "tee_merged"
 226 .IX Subsection "tee_merged"
 227 .Vb 1
 228 \&   $merged = tee_merged \e&code;
 229 .Ve
 230 .PP
 231 The \f(CW\*(C`tee_merged\*(C'\fR function works just like \f(CW\*(C`capture_merged\*(C'\fR except that output
 232 is captured as well as passed on to \s-1STDOUT\s0.  As with \f(CW\*(C`capture\*(C'\fR it may be called
 233 in block form.
 234 .PP
 235 Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be
 236 properly ordered due to buffering.
 237 .SH "LIMITATIONS"
 238 .IX Header "LIMITATIONS"
 239 .Sh "Portability"
 240 .IX Subsection "Portability"
 241 Portability is a goal, not a guarantee.  \f(CW\*(C`tee\*(C'\fR requires fork, except on
 242 Windows where \f(CW\*(C`system(1, @cmd)\*(C'\fR is used instead.  Not tested on any
 243 particularly esoteric platforms yet.
 244 .Sh "PerlIO layers"
 245 .IX Subsection "PerlIO layers"
 246 Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8' or
 247 \&':crlf' when capturing.   Layers should be applied to \s-1STDOUT\s0 or \s-1STDERR\s0 \fIbefore\fR
 248 the call to \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR.
 249 .Sh "Closed \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
 250 .IX Subsection "Closed STDIN, STDOUT or STDERR"
 251 Capture::Tiny will work even if \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0 have been previously
 252 closed.  However, since they may be reopened to capture or tee output, any code
 253 within the captured block that depends on finding them closed will, of course,
 254 not find them to be closed.  If they started closed, Capture::Tiny will reclose
 255 them again when the capture block finishes.
 256 .Sh "Scalar filehandles and \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
 257 .IX Subsection "Scalar filehandles and STDIN, STDOUT or STDERR"
 258 If \s-1STDOUT\s0 or \s-1STDERR\s0 are reopened to scalar filehandles prior to the call to
 259 \&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR, then Capture::Tiny will override the output handle for the
 260 duration of the \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then send captured output to the
 261 output handle after the capture is complete.  (Requires Perl 5.8)
 262 .PP
 263 Capture::Tiny attempts to preserve the semantics of \s-1STDIN\s0 opened to a scalar
 264 reference.
 265 .Sh "Tied \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
 266 .IX Subsection "Tied STDIN, STDOUT or STDERR"
 267 If \s-1STDOUT\s0 or \s-1STDERR\s0 are tied prior to the call to \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR, then
 268 Capture::Tiny will attempt to override the tie for the duration of the
 269 \&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then send captured output to the tied handle after
 270 the capture is complete.  (Requires Perl 5.8)
 271 .PP
 272 Capture::Tiny does not (yet) support resending utf8 encoded data to a tied
 273 \&\s-1STDOUT\s0 or \s-1STDERR\s0 handle.  Characters will appear as bytes.
 274 .PP
 275 Capture::Tiny attempts to preserve the semantics of tied \s-1STDIN\s0, but capturing
 276 or teeing when \s-1STDIN\s0 is tied is currently broken on Windows.
 277 .Sh "Modifiying \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0 during a capture"
 278 .IX Subsection "Modifiying STDIN, STDOUT or STDERR during a capture"
 279 Attempting to modify \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0 \fIduring\fR \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR is
 280 almost certainly going to cause problems.  Don't do that.
 281 .SH "BUGS"
 282 .IX Header "BUGS"
 283 Please report any bugs or feature requests using the \s-1CPAN\s0 Request Tracker.
 284 Bugs can be submitted through the web interface at
 285 <http://rt.cpan.org/Dist/Display.html?Queue=Capture\-Tiny>
 286 .PP
 287 When submitting a bug or request, please include a test-file or a patch to an
 288 existing test-file that illustrates the bug or desired feature.
 289 .SH "SEE ALSO"
 290 .IX Header "SEE ALSO"
 291 This is a selection of \s-1CPAN\s0 modules that provide some sort of output capture,
 292 albeit with various limitations that make them appropriate only in particular
 293 circumstances.  I'm probably missing some.  The long list is provided to show
 294 why I felt Capture::Tiny was necessary.
 295 .IP "\(bu" 4
 296 IO::Capture
 297 .IP "\(bu" 4
 298 IO::Capture::Extended
 299 .IP "\(bu" 4
 300 IO::CaptureOutput
 301 .IP "\(bu" 4
 302 IPC::Capture
 303 .IP "\(bu" 4
 304 IPC::Cmd
 305 .IP "\(bu" 4
 306 IPC::Open2
 307 .IP "\(bu" 4
 308 IPC::Open3
 309 .IP "\(bu" 4
 310 IPC::Open3::Simple
 311 .IP "\(bu" 4
 312 IPC::Open3::Utils
 313 .IP "\(bu" 4
 314 IPC::Run
 315 .IP "\(bu" 4
 316 IPC::Run::SafeHandles
 317 .IP "\(bu" 4
 318 IPC::Run::Simple
 319 .IP "\(bu" 4
 320 IPC::Run3
 321 .IP "\(bu" 4
 322 IPC::System::Simple
 323 .IP "\(bu" 4
 324 Tee
 325 .IP "\(bu" 4
 326 IO::Tee
 327 .IP "\(bu" 4
 328 File::Tee
 329 .IP "\(bu" 4
 330 Filter::Handle
 331 .IP "\(bu" 4
 332 Tie::STDERR
 333 .IP "\(bu" 4
 334 Tie::STDOUT
 335 .IP "\(bu" 4
 336 Test::Output
 337 .SH "AUTHOR"
 338 .IX Header "AUTHOR"
 339 David A. Golden (\s-1DAGOLDEN\s0)
 340 .SH "COPYRIGHT AND LICENSE"
 341 .IX Header "COPYRIGHT AND LICENSE"
 342 Copyright (c) 2009 by David A. Golden. All rights reserved.
 343 .PP
 344 Licensed under Apache License, Version 2.0 (the \*(L"License\*(R").  You may not use
 345 this file except in compliance with the License.  A copy of the License was
 346 distributed with this file or you may obtain a copy of the License from
 347 http://www.apache.org/licenses/\s-1LICENSE\-2\s0.0
 348 .PP
 349 Files produced as output though the use of this software, shall not be
 350 considered Derivative Works, but shall be considered the original work of the
 351 Licensor.
 352 .PP
 353 Unless required by applicable law or agreed to in writing, software
 354 distributed under the License is distributed on an \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1BASIS\s0,
 355 \&\s-1WITHOUT\s0 \s-1WARRANTIES\s0 \s-1OR\s0 \s-1CONDITIONS\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, either express or implied.
 356 See the License for the specific language governing permissions and
 357 limitations under the License.