.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Trap 3pm"
.TH Test::Trap 3pm "2018-10-20" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Trap \- Trap exit codes, exceptions, output, etc.
.SH "VERSION"
.IX Header "VERSION"
Version 0.3.4
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Test::More;
\&  use Test::Trap;
\&
\&  my @r = trap { some_code(@some_parameters) };
\&  is ( $trap\->exit, 1, \*(AqExpecting &some_code to exit with 1\*(Aq );
\&  is ( $trap\->stdout, \*(Aq\*(Aq, \*(AqExpecting no STDOUT\*(Aq );
\&  like ( $trap\->stderr, qr/^Bad parameters; exiting\eb/, \*(AqExpecting warnings.\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Primarily (but not exclusively) for use in test scripts: A block eval
on steroids, configurable and extensible, but by default trapping
(Perl) \s-1STDOUT, STDERR,\s0 warnings, exceptions, would-be exit codes, and
return values from boxed blocks of test code.
.PP
The values collected by the latest trap can then be queried or tested
through a special trap object.
.SH "EXPORT"
.IX Header "EXPORT"
A function and a scalar may be exported by any name.  The function (by
default named \f(CW\*(C`trap\*(C'\fR) is an analogue to block \fIeval()\fR, and the scalar
(by default named \f(CW$trap\fR) is the corresponding analogue to \f(CW$@\fR.
.PP
Optionally, you may specify the layers of the exported trap.  Layers
may be specified by name, with a colon sigil.  Multiple layers may be
given in a list, or just stringed together like \f(CW\*(C`:flow:stderr:warn\*(C'\fR.
.PP
(For the advanced user, you may also specify anonymous layer
implementations \*(-- i.e. an appropriate subroutine.)
.PP
See below for a list of the built-in layers, most of which are enabled
by default.  Note, finally, that the ordering of the layers matter:
The :raw layer is always on the bottom (anything underneath it is
ignored), and any other \*(L"flow control\*(R" layers used should be right
down there with it.
.SH "FUNCTION"
.IX Header "FUNCTION"
.SS "trap \s-1BLOCK\s0"
.IX Subsection "trap BLOCK"
This function may be exported by any name, but defaults to \f(CW\*(C`trap\*(C'\fR.
.PP
By default, traps exceptions (like block eval), but also exits and
exit codes, returns and return values, context, and (Perl) output on
\&\s-1STDOUT\s0 or \s-1STDERR,\s0 and warnings.  All information trapped can be
queried through the trap object, which is by default exported as
\&\f(CW$trap\fR, but can be exported by any name.
.PP
The value returned from \f(CW\*(C`trap\*(C'\fR mimics that returned from \f(CW\*(C`eval\*(C'\fR:  If
the \fI\s-1BLOCK\s0\fR would die or exit, it returns an undefined value in
scalar context or an empty list in list context; otherwise it returns
whatever the \fI\s-1BLOCK\s0\fR would return in the given context (also
available as the trapped return values).
.SH "TRAP LAYERS"
.IX Header "TRAP LAYERS"
Exactly what the \f(CW\*(C`trap\*(C'\fR traps depends on the layers of the trap.  It
is possible to register more (see Test::Trap::Builder), but the
following layers are pre-defined by this module:
.SS ":raw"
.IX Subsection ":raw"
The only built-in terminating layer, at which the processing of the
layers stops, and the actual call to the user code is performed.  On
success, it collects the return value(s) in the appropriate context.
Pushing the :raw layer on a trap will for most purposes remove all
layers below.
.SS ":die"
.IX Subsection ":die"
The layer emulating block eval, trapping normal exceptions.
.SS ":exit"
.IX Subsection ":exit"
The third \*(L"flow control\*(R" layer, capturing exit codes if anything used
in the dynamic scope of the trap calls \fICORE::GLOBAL::exit()\fR.  (See
\&\s-1CAVEATS\s0 below for more.)
.SS ":flow"
.IX Subsection ":flow"
A shortcut for :raw:die:exit (effectively pushing all three layers on
the trap).  Since this includes :raw, it is also terminating:  Pushing
:flow on a trap will effectively remove all layers below.
.SS ":stdout, :stderr"
.IX Subsection ":stdout, :stderr"
Layers trapping Perl output on \s-1STDOUT\s0 and \s-1STDERR,\s0 respectively.
.SS ":stdout(perlio), :stderr(perlio)"
.IX Subsection ":stdout(perlio), :stderr(perlio)"
As above, but specifying a capture strategy using PerlIO::scalar.  If
this strategy is not available (typically if PerlIO is not), this is
an error.  See \*(L"\s-1CAPTURE STRATEGIES\*(R"\s0.
.SS ":stdout(tempfile), :stderr(tempfile)"
.IX Subsection ":stdout(tempfile), :stderr(tempfile)"
As above, but specifying a capture strategy using File::Temp.  Note
that this is the default strategy, unless the \f(CW\*(C`:output()\*(C'\fR layer is
used to set another default.  See \*(L"\s-1CAPTURE STRATEGIES\*(R"\s0.
.SS ":stdout(a;b;c), :stderr(a,b,c)"
.IX Subsection ":stdout(a;b;c), :stderr(a,b,c)"
(Either syntax, commas or semicolons, is permitted, as is any number
of names in the list.)  As above, but specifying the capture strategy
by the first existing name among \fIa\fR, \fIb\fR, and \fIc\fR.  If no such
strategy is found, this is an error.  See \*(L"\s-1CAPTURE STRATEGIES\*(R"\s0.
.SS ":warn"
.IX Subsection ":warn"
A layer trapping warnings, with additional tee: If \s-1STDERR\s0 is open, it
will also print the warnings there.  (This output may be trapped by
the :stderr layer, be it above or below the :warn layer.)
.SS ":default"
.IX Subsection ":default"
A short-cut for :raw:die:exit:stdout:stderr:warn (effectively pushing
all six layers on the trap).  Since this includes :raw, it is also
terminating:  Pushing :default on a trap will effectively remove all
layers below.
.PP
The other interesting property of :default is that it is what every
trap starts with:  In order not to include the six layers that make up
:default, you need to push a terminating layer (such as :raw or :flow)
on the trap.
.SS ":on_fail(m)"
.IX Subsection ":on_fail(m)"
A (non-default, non-trapping) layer that installs a callback method
(by name) \fIm\fR to be run on test failures.  To run the \*(L"diag_all\*(R"
method every time a test fails:
.PP
.Vb 1
\&  use Test::Trap qw/ :on_fail(diag_all) /;
.Ve
.SS ":void, :scalar, :list"
.IX Subsection ":void, :scalar, :list"
These (non-default, non-trapping) layers will cause the trapped user
code to be run in void, scalar, or list context, respectively.  (By
default, the trap will propagate context, that is, it will run the
code in whatever context the trap itself is in.)
.PP
If more than one of these layers are pushed on the trap, the deepest
(that is, leftmost) takes precedence:
.PP
.Vb 3
\&  use Test::Trap qw/ :scalar:void:list /;
\&  trap { 42, 13 };
\&  $trap\->return_is_deeply( [ 13 ], \*(AqScalar comma.\*(Aq );
.Ve
.SS ":output(a;b;c)"
.IX Subsection ":output(a;b;c)"
A (non-default, non-trapping) layer that sets the default capture
strategy for any output trapping (\f(CW\*(C`:stdout\*(C'\fR, \f(CW\*(C`:stderr\*(C'\fR, or other
similarly defined) layers below iton the trap.
.PP
.Vb 2
\&  use Test::Trap qw/ :output(systemsafe) /;
\&  trap { system echo => \*(AqHello Unix!\*(Aq }; # trapped!
\&
\&  use Test::Trap qw/ :flow:stderr:output(systemsafe):stdout /;
\&  trap { system echo => \*(AqHello Unix!\*(Aq }; # *not* trapped!
\&  trap { system q/ echo \*(AqHello Unix!\*(Aq >&2 / }; # trapped!
.Ve
.PP
See \*(L"\s-1CAPTURE STRATEGIES\*(R"\s0.
.SH "CAPTURE STRATEGIES"
.IX Header "CAPTURE STRATEGIES"
How output is trapped, depends on the capture strategy used.  It is
possible to register more (see Test::Trap::Builder), but the
following strategies are pre-defined by this module:
.SS "tempfile"
.IX Subsection "tempfile"
The default capture strategy, provided by
Test::Trap::Builder::TempFile, in which output is temporarily
redirected to (and read back from) a tempfile.
.SS "tempfile-preserve"
.IX Subsection "tempfile-preserve"
A variant of the capture strategy provided by
Test::Trap::Builder::TempFile, in which the handles used to write
to and read from the tempfile are both binmoded with the same perlio
layers as the trapped output handle originally had.
.PP
Caveat emptor: If the handle has perlio custom layers, they may (or
may not) fail to apply to the tempfile read and write handles.
.SS "systemsafe"
.IX Subsection "systemsafe"
A capture strategy provided by Test::Trap::Builder::SystemSafe,
like the default strategy, except it outputs on file handles with the
same file descriptors as the trapped output handle originally had, and
so can be used to trap output from forked-off processes, including
\&\fIsystem()\fR.
.PP
This strategy may be \*(L"safe\*(R" in relation to forked-off processes, but
it is fragile.  For one, it only works with handles that have \*(L"real\*(R"
file descriptors.  For another, it depends on the original file
descriptors being available after closing.  (If signal handlers or
threads open files, they may well not be.)  And it may fail in other
ways.  But in relation to forked-off processes, the other pre-defined
strategies will silently fail to trap, as will similarly simple
strategies.  This one, when not crashing, will trap that output.
.SS "systemsafe-preserve"
.IX Subsection "systemsafe-preserve"
A variant of the capture strategy provided by
Test::Trap::Builder::SystemSafe, in which the handles used to write
to and read from the tempfile are both binmoded with the same perlio
layers as the trapped output handle originally had.
.PP
Caveat emptor: If the handle has perlio custom layers, they may (or
may not) fail to apply to the tempfile read and write handles.
.SS "perlio"
.IX Subsection "perlio"
A capture strategy provided by Test::Trap::Builder::PerlIO, in
which output is temporarily redirected to an in-memory file via
PerlIO::scalar.
.PP
If PerlIO::scalar is not available, neither is this strategy.
.SH "RESULT ACCESSORS"
.IX Header "RESULT ACCESSORS"
The following methods may be called on the trap objects after any trap
has been sprung, and access the outcome of the run.
.PP
Any property will be undef if not actually trapped \*(-- whether because
there is no layer to trap them or because flow control passed them by.
(If there is an active and successful trap layer, empty strings and
empty arrays trapped will of course be defined.)
.PP
When properties are set, their values will be as follows:
.SS "leaveby"
.IX Subsection "leaveby"
A string indicating how the trap terminated: \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`die\*(C'\fR, or
\&\f(CW\*(C`exit\*(C'\fR.
.SS "die"
.IX Subsection "die"
The exception, if the latest trap threw one.
.SS "exit"
.IX Subsection "exit"
The exit code, if the latest trap tried to exit (by way of the trap's
own &CORE::GLOBAL::exit only; see \*(L"\s-1CAVEATS\*(R"\s0).
.SS "return [\s-1INDEX ...\s0]"
.IX Subsection "return [INDEX ...]"
Returns undef if the latest trap did not terminate with a return;
otherwise returns three different views of the return array:
.IP "\(bu" 4
if no \fI\s-1INDEX\s0\fR is passed, returns a reference to the array (\s-1NB\s0! an
empty array of indices qualifies as \*(L"no index\*(R")
.IP "\(bu" 4
if called with at least one \fI\s-1INDEX\s0\fR in scalar context, returns the
array element indexed by the first \fI\s-1INDEX\s0\fR (ignoring the rest)
.IP "\(bu" 4
if called with at least one \fI\s-1INDEX\s0\fR in list context, returns the
slice of the array by these indices
.PP
Note: The array will hold but a single value if the trap was sprung in
scalar context, and will be empty if it was in void context.
.SS "stdout, stderr"
.IX Subsection "stdout, stderr"
The captured output on the respective file handles.
.SS "warn [\s-1INDEX\s0]"
.IX Subsection "warn [INDEX]"
Returns undef if the latest trap had no warning-trapping layer;
otherwise returns three different views of the warn array:
.IP "\(bu" 4
if no \fI\s-1INDEX\s0\fR is passed, returns a reference to the array (\s-1NB\s0! an
empty array of indices qualifies as \*(L"no index\*(R")
.IP "\(bu" 4
if called with at least one \fI\s-1INDEX\s0\fR in scalar context, returns the
array element indexed by the first \fI\s-1INDEX\s0\fR (ignoring the rest)
.IP "\(bu" 4
if called with at least one \fI\s-1INDEX\s0\fR in list context, returns the
slice of the array by these indices
.SS "wantarray"
.IX Subsection "wantarray"
The context in which the latest code trapped was called.  (By default
a propagated context, but layers can override this.)
.SS "list, scalar, void"
.IX Subsection "list, scalar, void"
True if the latest code trapped was called in the indicated context.
(By default the code will be called in a propagated context, but
layers can override this.)
.SH "RESULT TESTS"
.IX Header "RESULT TESTS"
For each accessor, a number of convenient standard test methods are
also available.  By default, these are a few standard tests from
Test::More, plus the \f(CW\*(C`nok\*(C'\fR test (a negated \f(CW\*(C`ok\*(C'\fR test).  All for
convenience:
.SS "\fI\s-1ACCESSOR\s0\fP_ok        [\s-1INDEX,\s0] \s-1TEST_NAME\s0"
.IX Subsection "ACCESSOR_ok [INDEX,] TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_nok       [\s-1INDEX,\s0] \s-1TEST_NAME\s0"
.IX Subsection "ACCESSOR_nok [INDEX,] TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_is        [\s-1INDEX,\s0] \s-1SCALAR, TEST_NAME\s0"
.IX Subsection "ACCESSOR_is [INDEX,] SCALAR, TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_isnt      [\s-1INDEX,\s0] \s-1SCALAR, TEST_NAME\s0"
.IX Subsection "ACCESSOR_isnt [INDEX,] SCALAR, TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_isa_ok    [\s-1INDEX,\s0] \s-1SCALAR, INVOCANT_NAME\s0"
.IX Subsection "ACCESSOR_isa_ok [INDEX,] SCALAR, INVOCANT_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_like      [\s-1INDEX,\s0] \s-1REGEX, TEST_NAME\s0"
.IX Subsection "ACCESSOR_like [INDEX,] REGEX, TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_unlike    [\s-1INDEX,\s0] \s-1REGEX, TEST_NAME\s0"
.IX Subsection "ACCESSOR_unlike [INDEX,] REGEX, TEST_NAME"
.SS "\fI\s-1ACCESSOR\s0\fP_is_deeply          \s-1STRUCTURE, TEST_NAME\s0"
.IX Subsection "ACCESSOR_is_deeply STRUCTURE, TEST_NAME"
\&\fI\s-1INDEX\s0\fR is not optional:  It is required for array accessors (like
\&\f(CW\*(C`return\*(C'\fR and \f(CW\*(C`warn\*(C'\fR), and disallowed for scalar accessors.  Note
that the \f(CW\*(C`is_deeply\*(C'\fR test does not accept an index.  Even for array
accessors, it operates on the entire array.
.PP
For convenience and clarity, tests against a flow control \fI\s-1ACCESSOR\s0\fR
(\f(CW\*(C`return\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, or any you define yourself) will first
test whether the trap was left by way of the flow control mechanism in
question, and fail with appropriate diagnostics otherwise.
.SS "did_die, did_exit, did_return"
.IX Subsection "did_die, did_exit, did_return"
Conveniences: Tests whether the trap was left by way of the flow
control mechanism in question.  Much like \f(CW\*(C`leaveby_is(\*(Aqdie\*(Aq)\*(C'\fR etc,
but with better diagnostics and (run-time) spell checking.
.SS "quiet"
.IX Subsection "quiet"
Convenience: Passes if zero-length output was trapped on both \s-1STDOUT\s0
and \s-1STDERR,\s0 and generate better diagnostics otherwise.
.SH "UTILITIES"
.IX Header "UTILITIES"
.SS "diag_all"
.IX Subsection "diag_all"
Prints a diagnostic message (as per \*(L"diag\*(R" in Test::More) consisting
of a dump (in Perl code, as per Data::Dump) of the trap object.
.SS "diag_all_once"
.IX Subsection "diag_all_once"
As \*(L"diag_all\*(R", except if this instance of the trap object has
already been diag_all_once'd, the diagnostic message will instead
consist of the string \f(CW\*(C`(as above)\*(C'\fR.
.PP
This could be useful with the \f(CW\*(C`on_fail\*(C'\fR layer:
.PP
.Vb 1
\&  use Test::Trap qw/ :on_fail(diag_all_once) /;
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
This module must be loaded before any code containing \fIexit()\fRs to be
trapped is compiled.  Any \fIexit()\fR already compiled won't be trappable,
and will terminate the program anyway.
.PP
This module overrides &CORE::GLOBAL::exit, so may not work correctly
(or even at all) in the presence of other code overriding
&CORE::GLOBAL::exit.  More precisely: This module installs its own
\&\fIexit()\fR on entry of the block, and restores the previous one, if any,
only upon leaving the block.
.PP
If you use \fIfork()\fR in the dynamic scope of a trap, beware that the
(default) :exit layer of that trap does not trap \fIexit()\fR in the
children, but passes them to the outer handler.  If you think about
it, this is what you are likely to want it to do in most cases.
.PP
Note that the (default) :exit layer only traps &CORE::GLOBAL::exit
calls (and bare \fIexit()\fR calls that compile to that).  It makes no
attempt to trap \fICORE::exit()\fR, \fIPOSIX::_exit()\fR, \fIexec()\fR, untrapped
exceptions from \fIdie()\fR, nor segfault.  Nor does it attempt to trap
anything else that might terminate the program.  The trap is a block
eval on steroids \*(-- not the last block eval of Krypton!
.PP
This module traps warnings using \f(CW$SIG{_\|_WARN_\|_}\fR, so may not work
correctly (or even at all) in the presence of other code setting this
handler.  More precisely: This module installs its own _\|_WARN_\|_
handler on entry of the block, and restores the previous one, if any,
only upon leaving the block.
.PP
The (default) :stdout and :stderr handlers will not trap output from
\&\fIsystem()\fR calls.
.PP
Threads?  No idea.  It might even work correctly.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests directly to the author.
.SH "AUTHOR"
.IX Header "AUTHOR"
Eirik Berg Hanssen, \f(CW\*(C`<ebhanssen@cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006\-2014 Eirik Berg Hanssen, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.