Codebase list libcapture-tiny-perl / 0462406
Documentation fixes Clarified some limitations; added a link to CPAN Testers Matrix; removed redundant BUGS section; standardized terminology David Golden 12 years ago
3 changed file(s) with 51 addition(s) and 60 deletion(s). Raw diff Collapse all Expand all
+5
-0
Changes less more
55
66 - Added a workaround for failing t/08-stdin-closed.t under blead
77 perl / 5.15.8 [rt.perl.org #111070]
8
9 Documented:
10
11 - Clarified some limitations; added a link to CPAN Testers Matrix;
12 removed redundant BUGS section; standardized terminology
813
914 Tested:
1015
+23
-30
README.pod less more
3232 Capture::Tiny provides a simple, portable way to capture almost anything sent
3333 to STDOUT or STDERR, regardless of whether it comes from Perl, from XS code or
3434 from an external program. Optionally, output can be teed so that it is
35 captured while being passed through to the original handles. Yes, it even
35 captured while being passed through to the original filehandles. Yes, it even
3636 works on Windows (usually). Stop guessing which of a dozen capturing modules
3737 to use in any particular situation and just use this one.
3838
4848 The C<<< capture >>> function takes a code reference and returns what is sent to
4949 STDOUT and STDERR as well as any return values from the code reference. In
5050 scalar context, it returns only STDOUT. If no output was received for a
51 handle, it returns an empty string for that handle. Regardless of calling
52 context, all output is captured -- nothing is passed to the existing handles.
51 filehandle, it returns an empty string for that filehandle. Regardless of calling
52 context, all output is captured -- nothing is passed to the existing filehandles.
5353
5454 It is prototyped to take a subroutine reference as an argument. Thus, it
5555 can be called in block form:
147147
148148 Portability is a goal, not a guarantee. C<<< tee >>> requires fork, except on
149149 Windows where C<<< system(1, @cmd) >>> is used instead. Not tested on any
150 particularly esoteric platforms yet.
150 particularly esoteric platforms yet. See the
151 L<CPAN Testers Matrix|http://matrix.cpantesters.org/?dist=Capture-Tiny>
152 for test result by platform.
151153
152154 =head2 PerlIO layers
153155
154156 Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8' or
155157 ':crlf' when capturing. Layers should be applied to STDOUT or STDERR I<before>
156 the call to C<<< capture >>> or C<<< tee >>>. This may not work for tied handles (see below).
158 the call to C<<< capture >>> or C<<< tee >>>. This may not work for tied filehandles (see below).
157159
158160 =head2 Modifying filehandles before capturing
159161
160162 Generally speaking, you should do little or no manipulation of the standard IO
161 handles prior to using Capture::Tiny. In particular, closing, reopening,
162 localizing or tying standard handles prior to capture may cause a variety of
163 filehandles prior to using Capture::Tiny. In particular, closing, reopening,
164 localizing or tying standard filehandles prior to capture may cause a variety of
163165 unexpected, undesirable andE<sol>or unreliable behaviors, as described below.
164166 Capture::Tiny does its best to compensate for these situations, but the
165167 results may not be what you desire.
172174 course, not find them to be closed. If they started closed, Capture::Tiny will
173175 close them again when the capture block finishes.
174176
175 Note that this reopening will happen even for STDIN or a handle not being
177 Note that this reopening will happen even for STDIN or a filehandle not being
176178 captured to ensure that the filehandle used for capture is not opened to file
177179 descriptor 0, as this causes problems on various platforms.
178180
179181 B<Localized filehandles>
180182
181 If code localizes any of Perl's standard handles before capturing, the capture
182 will affect the localized handles and not the original ones. External system
183 calls are not affected by localizing a handle in Perl and will continue
184 to send output to the original handles (which will thus not be captured).
183 If code localizes any of Perl's standard filehandles before capturing, the capture
184 will affect the localized filehandles and not the original ones. External system
185 calls are not affected by localizing a filehandle in Perl and will continue
186 to send output to the original filehandles (which will thus not be captured).
185187
186188 B<Scalar filehandles>
187189
188190 If STDOUT or STDERR are reopened to scalar filehandles prior to the call to
189 C<<< capture >>> or C<<< tee >>>, then Capture::Tiny will override the output handle for the
191 C<<< capture >>> or C<<< tee >>>, then Capture::Tiny will override the output filehandle for the
190192 duration of the C<<< capture >>> or C<<< tee >>> call and then send captured output to the
191 output handle after the capture is complete. (Requires Perl 5.8)
193 output filehandle after the capture is complete. (Requires Perl 5.8)
192194
193195 Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar
194196 reference.
195197
196 B<Tied output handles>
198 B<Tied output filehandles>
197199
198200 If STDOUT or STDERR are tied prior to the call to C<<< capture >>> or C<<< tee >>>, then
199201 Capture::Tiny will attempt to override the tie for the duration of the
200 C<<< capture >>> or C<<< tee >>> call and then send captured output to the tied handle after
202 C<<< capture >>> or C<<< tee >>> call and then send captured output to the tied filehandle after
201203 the capture is complete. (Requires Perl 5.8)
202204
203205 Capture::Tiny may not succeed resending UTF-8 encoded data to a tied
204 STDOUT or STDERR handle. Characters may appear as bytes. If the tied handle
206 STDOUT or STDERR filehandle. Characters may appear as bytes. If the tied filehandle
205207 is based on L<Tie::StdHandle>, then Capture::Tiny will attempt to determine
206 appropriate layers like C<<< :utf8 >>> from the underlying handle and do the right
208 appropriate layers like C<<< :utf8 >>> from the underlying filehandle and do the right
207209 thing.
208210
209 B<Tied input handle>
211 B<Tied input filehandle>
210212
211213 Capture::Tiny attempts to preserve the semantics of tied STDIN, but this is not
212214 entirely stable or portable. For example:
219221
220222 =item *
221223
222 L<FCGI> has been reported as having a pathological tied handle implementation
224 L<FCGI> has been reported as having a pathological tied filehandle implementation
223225 that causes fatal (and hard to diagnose) errors
224226
225227 =back
229231
230232 my ($out, $err) = do { local *STDIN; capture { ... } };
231233
232 =head2 Modifying handles during a capture
234 =head2 Modifying filehandles during a capture
233235
234236 Attempting to modify STDIN, STDOUT or STDERR I<during> C<<< capture >>> or C<<< tee >>> is
235237 almost certainly going to cause problems. Don't do that.
248250 alternate timeout may be specified by setting the C<<< PERL_CAPTURE_TINY_TIMEOUT >>>
249251 environment variable. Setting it to zero will disable timeouts.
250252
251 =head1 BUGS
252
253 Please report any bugs or feature requests using the CPAN Request Tracker.
254 Bugs can be submitted through the web interface at
255 L<http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny>
256
257 When submitting a bug or request, please include a test-file or a patch to an
258 existing test-file that illustrates the bug or desired feature.
259
260253 =head1 SEE ALSO
261254
262255 This module was, inspired by L<IO::CaptureOutput>, which provides
+23
-30
lib/Capture/Tiny.pm less more
422422 Capture::Tiny provides a simple, portable way to capture almost anything sent
423423 to STDOUT or STDERR, regardless of whether it comes from Perl, from XS code or
424424 from an external program. Optionally, output can be teed so that it is
425 captured while being passed through to the original handles. Yes, it even
425 captured while being passed through to the original filehandles. Yes, it even
426426 works on Windows (usually). Stop guessing which of a dozen capturing modules
427427 to use in any particular situation and just use this one.
428428
438438 The {capture} function takes a code reference and returns what is sent to
439439 STDOUT and STDERR as well as any return values from the code reference. In
440440 scalar context, it returns only STDOUT. If no output was received for a
441 handle, it returns an empty string for that handle. Regardless of calling
442 context, all output is captured -- nothing is passed to the existing handles.
441 filehandle, it returns an empty string for that filehandle. Regardless of calling
442 context, all output is captured -- nothing is passed to the existing filehandles.
443443
444444 It is prototyped to take a subroutine reference as an argument. Thus, it
445445 can be called in block form:
537537
538538 Portability is a goal, not a guarantee. {tee} requires fork, except on
539539 Windows where {system(1, @cmd)} is used instead. Not tested on any
540 particularly esoteric platforms yet.
540 particularly esoteric platforms yet. See the
541 [CPAN Testers Matrix|http://matrix.cpantesters.org/?dist=Capture-Tiny]
542 for test result by platform.
541543
542544 == PerlIO layers
543545
544546 Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8' or
545547 ':crlf' when capturing. Layers should be applied to STDOUT or STDERR ~before~
546 the call to {capture} or {tee}. This may not work for tied handles (see below).
548 the call to {capture} or {tee}. This may not work for tied filehandles (see below).
547549
548550 == Modifying filehandles before capturing
549551
550552 Generally speaking, you should do little or no manipulation of the standard IO
551 handles prior to using Capture::Tiny. In particular, closing, reopening,
552 localizing or tying standard handles prior to capture may cause a variety of
553 filehandles prior to using Capture::Tiny. In particular, closing, reopening,
554 localizing or tying standard filehandles prior to capture may cause a variety of
553555 unexpected, undesirable and/or unreliable behaviors, as described below.
554556 Capture::Tiny does its best to compensate for these situations, but the
555557 results may not be what you desire.
562564 course, not find them to be closed. If they started closed, Capture::Tiny will
563565 close them again when the capture block finishes.
564566
565 Note that this reopening will happen even for STDIN or a handle not being
567 Note that this reopening will happen even for STDIN or a filehandle not being
566568 captured to ensure that the filehandle used for capture is not opened to file
567569 descriptor 0, as this causes problems on various platforms.
568570
569571 *Localized filehandles*
570572
571 If code localizes any of Perl's standard handles before capturing, the capture
572 will affect the localized handles and not the original ones. External system
573 calls are not affected by localizing a handle in Perl and will continue
574 to send output to the original handles (which will thus not be captured).
573 If code localizes any of Perl's standard filehandles before capturing, the capture
574 will affect the localized filehandles and not the original ones. External system
575 calls are not affected by localizing a filehandle in Perl and will continue
576 to send output to the original filehandles (which will thus not be captured).
575577
576578 *Scalar filehandles*
577579
578580 If STDOUT or STDERR are reopened to scalar filehandles prior to the call to
579 {capture} or {tee}, then Capture::Tiny will override the output handle for the
581 {capture} or {tee}, then Capture::Tiny will override the output filehandle for the
580582 duration of the {capture} or {tee} call and then send captured output to the
581 output handle after the capture is complete. (Requires Perl 5.8)
583 output filehandle after the capture is complete. (Requires Perl 5.8)
582584
583585 Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar
584586 reference.
585587
586 *Tied output handles*
588 *Tied output filehandles*
587589
588590 If STDOUT or STDERR are tied prior to the call to {capture} or {tee}, then
589591 Capture::Tiny will attempt to override the tie for the duration of the
590 {capture} or {tee} call and then send captured output to the tied handle after
592 {capture} or {tee} call and then send captured output to the tied filehandle after
591593 the capture is complete. (Requires Perl 5.8)
592594
593595 Capture::Tiny may not succeed resending UTF-8 encoded data to a tied
594 STDOUT or STDERR handle. Characters may appear as bytes. If the tied handle
596 STDOUT or STDERR filehandle. Characters may appear as bytes. If the tied filehandle
595597 is based on [Tie::StdHandle], then Capture::Tiny will attempt to determine
596 appropriate layers like {:utf8} from the underlying handle and do the right
598 appropriate layers like {:utf8} from the underlying filehandle and do the right
597599 thing.
598600
599 *Tied input handle*
601 *Tied input filehandle*
600602
601603 Capture::Tiny attempts to preserve the semantics of tied STDIN, but this is not
602604 entirely stable or portable. For example:
603605
604606 * Capturing or teeing with STDIN tied is broken on Windows
605 * [FCGI] has been reported as having a pathological tied handle implementation
607 * [FCGI] has been reported as having a pathological tied filehandle implementation
606608 that causes fatal (and hard to diagnose) errors
607609
608610 Unless having STDIN tied is crucial, it may be safest to localize STDIN when
610612
611613 my ($out, $err) = do { local *STDIN; capture { ... } };
612614
613 == Modifying handles during a capture
615 == Modifying filehandles during a capture
614616
615617 Attempting to modify STDIN, STDOUT or STDERR ~during~ {capture} or {tee} is
616618 almost certainly going to cause problems. Don't do that.
628630 30 seconds (or whatever is the value of {$Capture::Tiny::TIMEOUT}). An
629631 alternate timeout may be specified by setting the {PERL_CAPTURE_TINY_TIMEOUT}
630632 environment variable. Setting it to zero will disable timeouts.
631
632 = BUGS
633
634 Please report any bugs or feature requests using the CPAN Request Tracker.
635 Bugs can be submitted through the web interface at
636 [http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny]
637
638 When submitting a bug or request, please include a test-file or a patch to an
639 existing test-file that illustrates the bug or desired feature.
640633
641634 = SEE ALSO
642635