--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" 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 "Capture::Tiny 3"
+.TH Capture::Tiny 3 "2009-05-07" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Capture::Tiny \- Capture STDOUT and STDERR from Perl, XS or external programs
+.SH "VERSION"
+.IX Header "VERSION"
+This documentation describes version 0.06.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use Capture::Tiny qw/capture tee capture_merged tee_merged/;
+.Ve
+.PP
+.Vb 3
+\& ($stdout, $stderr) = capture {
+\& # your code here
+\& };
+.Ve
+.PP
+.Vb 3
+\& ($stdout, $stderr) = tee {
+\& # your code here
+\& };
+.Ve
+.PP
+.Vb 3
+\& $merged = capture_merged {
+\& # your code here
+\& };
+.Ve
+.PP
+.Vb 3
+\& $merged = tee_merged {
+\& # your code here
+\& };
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Capture::Tiny provides a simple, portable way to capture anything sent to
+\&\s-1STDOUT\s0 or \s-1STDERR\s0, regardless of whether it comes from Perl, from \s-1XS\s0 code or
+from an external program. Optionally, output can be teed so that it is
+captured while being passed through to the original handles. Yes, it even
+works on Windows. Stop guessing which of a dozen capturing modules to use in
+any particular situation and just use this one.
+.PP
+This module was heavily inspired by IO::CaptureOutput, which provides
+similar functionality without the ability to tee output and with more
+complicated code and \s-1API\s0.
+.SH "USAGE"
+.IX Header "USAGE"
+The following functions are available. None are exported by default.
+.Sh "capture"
+.IX Subsection "capture"
+.Vb 2
+\& ($stdout, $stderr) = capture \e&code;
+\& $stdout = capture \e&code;
+.Ve
+.PP
+The \f(CW\*(C`capture\*(C'\fR function takes a code reference and returns what is sent to
+\&\s-1STDOUT\s0 and \s-1STDERR\s0. In scalar context, it returns only \s-1STDOUT\s0. If no output
+was received, returns an empty string. Regardless of context, all output is
+captured \*(-- nothing is passed to the existing handles.
+.PP
+It is prototyped to take a subroutine reference as an argument. Thus, it
+can be called in block form:
+.PP
+.Vb 3
+\& ($stdout, $stderr) = capture {
+\& # your code here ...
+\& };
+.Ve
+.Sh "capture_merged"
+.IX Subsection "capture_merged"
+.Vb 1
+\& $merged = capture_merged \e&code;
+.Ve
+.PP
+The \f(CW\*(C`capture_merged\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR except \s-1STDOUT\s0 and
+\&\s-1STDERR\s0 are merged. (Technically, \s-1STDERR\s0 is redirected to \s-1STDOUT\s0 before
+executing the function.) If no output was received, returns an empty string.
+As with \f(CW\*(C`capture\*(C'\fR it may be called in block form.
+.PP
+Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be
+properly ordered due to buffering.
+.Sh "tee"
+.IX Subsection "tee"
+.Vb 2
+\& ($stdout, $stderr) = tee \e&code;
+\& $stdout = tee \e&code;
+.Ve
+.PP
+The \f(CW\*(C`tee\*(C'\fR function works just like \f(CW\*(C`capture\*(C'\fR, except that output is captured
+as well as passed on to the original \s-1STDOUT\s0 and \s-1STDERR\s0. As with \f(CW\*(C`capture\*(C'\fR it
+may be called in block form.
+.Sh "tee_merged"
+.IX Subsection "tee_merged"
+.Vb 1
+\& $merged = tee_merged \e&code;
+.Ve
+.PP
+The \f(CW\*(C`tee_merged\*(C'\fR function works just like \f(CW\*(C`capture_merged\*(C'\fR except that output
+is captured as well as passed on to \s-1STDOUT\s0. As with \f(CW\*(C`capture\*(C'\fR it may be called
+in block form.
+.PP
+Caution: \s-1STDOUT\s0 and \s-1STDERR\s0 output in the merged result are not guaranteed to be
+properly ordered due to buffering.
+.SH "LIMITATIONS"
+.IX Header "LIMITATIONS"
+.Sh "Portability"
+.IX Subsection "Portability"
+Portability is a goal, not a guarantee. \f(CW\*(C`tee\*(C'\fR requires fork, except on
+Windows where \f(CW\*(C`system(1, @cmd)\*(C'\fR is used instead. Not tested on any
+particularly esoteric platforms yet.
+.Sh "PerlIO layers"
+.IX Subsection "PerlIO layers"
+Capture::Tiny does it's best to preserve PerlIO layers such as ':utf8' or
+\&':crlf' when capturing. Layers should be applied to \s-1STDOUT\s0 or \s-1STDERR\s0 \fIbefore\fR
+the call to \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR.
+.Sh "Closed \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
+.IX Subsection "Closed STDIN, STDOUT or STDERR"
+Capture::Tiny will work even if \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0 have been previously
+closed. However, since they may be reopened to capture or tee output, any code
+within the captured block that depends on finding them closed will, of course,
+not find them to be closed. If they started closed, Capture::Tiny will reclose
+them again when the capture block finishes.
+.Sh "Scalar filehandles and \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
+.IX Subsection "Scalar filehandles and STDIN, STDOUT or STDERR"
+If \s-1STDOUT\s0 or \s-1STDERR\s0 are reopened to scalar filehandles prior to the call to
+\&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR, then Capture::Tiny will override the output handle for the
+duration of the \f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then send captured output to the
+output handle after the capture is complete. (Requires Perl 5.8)
+.PP
+Capture::Tiny attempts to preserve the semantics of \s-1STDIN\s0 opened to a scalar
+reference.
+.Sh "Tied \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0"
+.IX Subsection "Tied STDIN, STDOUT or STDERR"
+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
+Capture::Tiny will attempt to override the tie for the duration of the
+\&\f(CW\*(C`capture\*(C'\fR or \f(CW\*(C`tee\*(C'\fR call and then send captured output to the tied handle after
+the capture is complete. (Requires Perl 5.8)
+.PP
+Capture::Tiny does not (yet) support resending utf8 encoded data to a tied
+\&\s-1STDOUT\s0 or \s-1STDERR\s0 handle. Characters will appear as bytes.
+.PP
+Capture::Tiny attempts to preserve the semantics of tied \s-1STDIN\s0, but capturing
+or teeing when \s-1STDIN\s0 is tied is currently broken on Windows.
+.Sh "Modifiying \s-1STDIN\s0, \s-1STDOUT\s0 or \s-1STDERR\s0 during a capture"
+.IX Subsection "Modifiying STDIN, STDOUT or STDERR during a capture"
+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
+almost certainly going to cause problems. Don't do that.
+.SH "BUGS"
+.IX Header "BUGS"
+Please report any bugs or feature requests using the \s-1CPAN\s0 Request Tracker.
+Bugs can be submitted through the web interface at
+<http://rt.cpan.org/Dist/Display.html?Queue=Capture\-Tiny>
+.PP
+When submitting a bug or request, please include a test-file or a patch to an
+existing test-file that illustrates the bug or desired feature.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+This is a selection of \s-1CPAN\s0 modules that provide some sort of output capture,
+albeit with various limitations that make them appropriate only in particular
+circumstances. I'm probably missing some. The long list is provided to show
+why I felt Capture::Tiny was necessary.
+.IP "\(bu" 4
+IO::Capture
+.IP "\(bu" 4
+IO::Capture::Extended
+.IP "\(bu" 4
+IO::CaptureOutput
+.IP "\(bu" 4
+IPC::Capture
+.IP "\(bu" 4
+IPC::Cmd
+.IP "\(bu" 4
+IPC::Open2
+.IP "\(bu" 4
+IPC::Open3
+.IP "\(bu" 4
+IPC::Open3::Simple
+.IP "\(bu" 4
+IPC::Open3::Utils
+.IP "\(bu" 4
+IPC::Run
+.IP "\(bu" 4
+IPC::Run::SafeHandles
+.IP "\(bu" 4
+IPC::Run::Simple
+.IP "\(bu" 4
+IPC::Run3
+.IP "\(bu" 4
+IPC::System::Simple
+.IP "\(bu" 4
+Tee
+.IP "\(bu" 4
+IO::Tee
+.IP "\(bu" 4
+File::Tee
+.IP "\(bu" 4
+Filter::Handle
+.IP "\(bu" 4
+Tie::STDERR
+.IP "\(bu" 4
+Tie::STDOUT
+.IP "\(bu" 4
+Test::Output
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+David A. Golden (\s-1DAGOLDEN\s0)
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright (c) 2009 by David A. Golden. All rights reserved.
+.PP
+Licensed under Apache License, Version 2.0 (the \*(L"License\*(R"). You may not use
+this file except in compliance with the License. A copy of the License was
+distributed with this file or you may obtain a copy of the License from
+http://www.apache.org/licenses/\s-1LICENSE\-2\s0.0
+.PP
+Files produced as output though the use of this software, shall not be
+considered Derivative Works, but shall be considered the original work of the
+Licensor.
+.PP
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1BASIS\s0,
+\&\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.
+See the License for the specific language governing permissions and
+limitations under the License.
projects / catagits/Gitalist.git / blobdiff