Skip to content
Browse files

updated docs, prereqs, gitignore

  • Loading branch information...
1 parent cb14145 commit a9c7cd548022154a1ce6f549f0126adf2a2304e8 @xdg xdg committed Feb 13, 2009
Showing with 353 additions and 58 deletions.
  1. +1 −0 .gitignore
  2. +21 −17 Build.PL
  3. +13 −12 MANIFEST
  4. +7 −3 META.yml
  5. +18 −0 Makefile.PL
  6. +95 −12 README
  7. +63 −10 lib/Capture/Tiny.pm
  8. +135 −4 lib/Capture/Tiny.pod
View
1 .gitignore
@@ -3,3 +3,4 @@ Build
_build/
blib/
*.tmp
+*.bak
View
38 Build.PL
@@ -4,28 +4,32 @@
# 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/LICENSE-2.0
+use 5.006;
use strict;
use lib 'inc';
eval "require Pod::WikiDoc";
my $class = $@ ? "Module::Build" : "Module::Build::WikiDoc";
eval "require $class";
my $build = $class->new(
- module_name => 'Capture::Tiny',
- dist_author => 'David Golden <dagolden@cpan.org>',
- license => 'apache',
- create_readme => 1,
-# create_makefile_pl => 'traditional',
- requires => {
- 'perl' => '5.004',
- },
- build_requires => {
- 'Test::More' => 0.47,
- },
- meta_add => {
- no_index => {
- directory => [ qw/ examples inc t /],
- }
- },
+ module_name => 'Capture::Tiny',
+ dist_author => 'David Golden <dagolden@cpan.org>',
+ license => 'apache',
+ create_readme => 1,
+ create_makefile_pl => 'traditional',
+ requires => {
+ 'perl' => 5.006,
+ 'Exporter' => 0,
+ 'Fatal' => 0,
+ 'File::Temp' => 0.14,
+ 'IO::Handle' => 0,
+ },
+ build_requires => {
+ 'Test::More' => 0.47, # 0.47 in perl 5.006002; 0.62 in perl 5.008008;
+ },
+ meta_add => {
+ no_index => {
+ directory => [ qw/ examples inc t /],
+ }
+ },
);
$build->create_build_script;
-
View
25 MANIFEST
@@ -1,22 +1,23 @@
-# Initial manifest generated by Module::Boilerplate
-lib/Capture/Tiny.pm
-t/01-Capture-Tiny.t
Build.PL
-LICENSE
+Changes
+examples/tee.pl
+inc/Module/Build/WikiDoc.pm
INSTALL
+lib/Capture/Tiny.pm
+lib/Capture/Tiny.pod
+LICENSE
+Makefile.PL
MANIFEST
MANIFEST.SKIP
+META.yml
README
-Changes
+t/01-Capture-Tiny.t
+t/02-capture.t
+t/03-tee.t
Todo
-inc/Module/Build/WikiDoc.pm
-xt/pod-format.t
-xt/pod-coverage.t
xt/critic.t
xt/perlcriticrc
+xt/pod-coverage.t
+xt/pod-format.t
xt/spelling.t
xt/stopwords.txt
-lib/Capture/Tiny.pod
-t/02-capture.t
-META.yml
-t/03-tee.t
View
10 META.yml
@@ -3,19 +3,23 @@ name: Capture-Tiny
version: 0.01
author:
- 'David Golden <dagolden@cpan.org>'
-abstract: 'Capture STDOUT and STDERR from perl, XS or system commands'
+abstract: 'Capture STDOUT and STDERR from Perl, XS or external programs'
license: apache
resources:
license: http://www.apache.org/licenses/LICENSE-2.0.txt
requires:
- perl: 5.004
+ Exporter: 0
+ Fatal: 0
+ File::Temp: 0.14
+ IO::Handle: 0
+ perl: 5.006
build_requires:
Test::More: 0.47
provides:
Capture::Tiny:
file: lib/Capture/Tiny.pm
version: 0.01
-generated_by: Module::Build version 0.3001
+generated_by: Module::Build version 0.31012
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.2.html
version: 1.2
View
18 Makefile.PL
@@ -0,0 +1,18 @@
+# Note: this file was auto-generated by Module::Build::Compat version 0.31012
+require 5.006;
+use ExtUtils::MakeMaker;
+WriteMakefile
+(
+ 'INSTALLDIRS' => 'site',
+ 'NAME' => 'Capture::Tiny',
+ 'EXE_FILES' => [],
+ 'VERSION_FROM' => 'lib/Capture/Tiny.pm',
+ 'PREREQ_PM' => {
+ 'Test::More' => '0.47',
+ 'Fatal' => 0,
+ 'IO::Handle' => 0,
+ 'File::Temp' => '0.14',
+ 'Exporter' => 0
+ }
+ )
+;
View
107 README
@@ -1,40 +1,124 @@
NAME
- Capture::Tiny - Capture STDOUT and STDERR from perl, XS or system
- commands
+ Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external
+ programs
VERSION
This documentation describes version 0.01.
SYNOPSIS
- use Capture::Tiny;
-
- ($stdout, $stderr) = capture {
+ use Capture::Tiny qw/capture tee/;
+
+ ($stdout, $stderr) = capture {
# your code here
};
-
- ($stdout, $stderr) = tee {
+
+ ($stdout, $stderr) = tee {
# your code here
};
DESCRIPTION
+ Capture::Tiny provides a simple, portable way to capture anything sent
+ to STDOUT or STDERR, regardless of whether it comes from Perl, from XS
+ 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.
+
+ This module was heavily inspired by IO::CaptureOutput, which provides
+ similar functionality without the ability to tee output and with more
+ complicated code and API.
+
USAGE
+ The following functions are available. None are exported by default.
+
capture
+ ($stdout, $stderr) = capture \&code;
+ $stdout = capture \&code;
+
+ The "capture" function takes a code reference and returns what is sent
+ to STDOUT and STDERR. In scalar context, it returns only STDOUT.
+ Regardless of context, all output is captured -- nothing is passed to
+ the existing handles.
- ($stdout, $stderr) = capture \&code_ref;
+ It is prototyped to take a subroutine reference as an argument. Thus, it
+ can be called in block form:
+
+ ($stdout, $stderr) = capture {
+ # your code here ...
+ };
tee
+ ($stdout, $stderr) = tee \&code;
+ $stdout = tee \&code;
+
+ The "tee" function works just like "capture", except that output is
+ captured as well as passed on to the original STDOUT and STDERR. As with
+ "capture" it may be called in block form.
- ($stdout, $stderr) = capture \&code_ref;
+LIMITATIONS
+ Portability is a goal, not a guarantee. "tee" requires fork, except on
+ Windows where "system(1, @cmd)" is used instead. Not tested on any
+ esoteric platforms yet. Minimal test suite so far.
+
+ No support for merging STDERR with STDOUT. This may be added in the
+ future.
BUGS
Please report any bugs or feature using the CPAN Request Tracker. Bugs
can be submitted through the web interface at
- http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny
+ <http://rt.cpan.org/Dist/Display.html?Queue=Capture-Tiny>
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.
SEE ALSO
+ This is a selection of CPAN 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 show why I felt Capture::Tiny was necessary.
+
+ * IO::Capture
+
+ * IO::Capture::Extended
+
+ * IO::CaptureOutput
+
+ * IPC::Capture
+
+ * IPC::Cmd
+
+ * IPC::Open2
+
+ * IPC::Open3
+
+ * IPC::Open3::Simple
+
+ * IPC::Open3::Utils
+
+ * IPC::Run
+
+ * IPC::Run::SafeHandles
+
+ * IPC::Run::Simple
+
+ * IPC::Run3
+
+ * IPC::System::Simple
+
+ * Tee
+
+ * IO::Tee
+
+ * File::Tee
+
+ * Filter::Handle
+
+ * Tie::STDERR
+
+ * Tie::STDOUT
+
+ * Test::Output
+
AUTHOR
David A. Golden (DAGOLDEN)
@@ -44,8 +128,7 @@ COPYRIGHT AND LICENSE
Licensed under Apache License, Version 2.0 (the "License"). 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:E<sol>E<sol>www.apache.orgE<sol>licensesE<sol>LICENSE-2.0
+ License from http://www.apache.org/licenses/LICENSE-2.0
Files produced as output though the use of this software, shall not be
considered Derivative Works, but shall be considered the original work
View
73 lib/Capture/Tiny.pm
@@ -16,7 +16,7 @@ use Fatal qw/pipe open close/;
our $VERSION = '0.01';
$VERSION = eval $VERSION; ## no critic
our @ISA = qw/Exporter/;
-our @EXPORT = qw/capture tee/;
+our @EXPORT_OK = qw/capture tee/;
my $use_system = $^O eq 'MSWin32';
@@ -141,7 +141,7 @@ sub _capture_tee {
# capture()
#--------------------------------------------------------------------------#
-sub capture(&) {
+sub capture(&) { ## no critic
$_[1] = 0; # no tee
goto \&_capture_tee;
}
@@ -150,7 +150,7 @@ sub capture(&) {
# tee()
#--------------------------------------------------------------------------#
-sub tee(&) {
+sub tee(&) { ## no critic
$_[1] = 1; # tee
goto \&_capture_tee;
}
@@ -163,15 +163,15 @@ __END__
= NAME
-Capture::Tiny - Capture STDOUT and STDERR from perl, XS or external programs
+Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external programs
= VERSION
This documentation describes version %%VERSION%%.
= SYNOPSIS
- use Capture::Tiny;
+ use Capture::Tiny qw/capture tee/;
($stdout, $stderr) = capture {
# your code here
@@ -183,20 +183,53 @@ This documentation describes version %%VERSION%%.
= DESCRIPTION
-Capture::Tiny provides a simple, portable way to capture anything sent to
+Capture::Tiny provides a simple, portable way to capture anything sent to
STDOUT or STDERR, regardless of whether it comes from Perl, from XS code or
-from an external program. Optionally, output can be teed so that it is
-captured while being passed through to the original handlers.
+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.
+
+This module was heavily inspired by [IO::CaptureOutput], which provides
+similar functionality without the ability to tee output and with more
+complicated code and API.
= USAGE
+The following functions are available. None are exported by default.
+
== capture
- ($stdout, $stderr) = capture \&code_ref;
+ ($stdout, $stderr) = capture \&code;
+ $stdout = capture \&code;
+
+The {capture} function takes a code reference and returns what is sent to
+STDOUT and STDERR. In scalar context, it returns only STDOUT. Regardless of
+context, all output is captured -- nothing is passed to the existing handles.
+
+It is prototyped to take a subroutine reference as an argument. Thus, it
+can be called in block form:
+
+ ($stdout, $stderr) = capture {
+ # your code here ...
+ };
== tee
- ($stdout, $stderr) = tee \&code_ref;
+ ($stdout, $stderr) = tee \&code;
+ $stdout = tee \&code;
+
+The {tee} function works just like {capture}, except that output is captured
+as well as passed on to the original STDOUT and STDERR. As with {capture} it
+may be called in block form.
+
+= LIMITATIONS
+
+Portability is a goal, not a guarantee. {tee} requires fork, except on
+Windows where {system(1, @cmd)} is used instead. Not tested on any
+esoteric platforms yet. Minimal test suite so far.
+
+No support for merging STDERR with STDOUT. This may be added in the future.
= BUGS
@@ -209,12 +242,32 @@ existing test-file that illustrates the bug or desired feature.
= SEE ALSO
+This is a selection of CPAN 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 show why
+I felt Capture::Tiny was necessary.
+
+* [IO::Capture]
+* [IO::Capture::Extended]
* [IO::CaptureOutput]
+* [IPC::Capture]
* [IPC::Cmd]
* [IPC::Open2]
* [IPC::Open3]
+* [IPC::Open3::Simple]
+* [IPC::Open3::Utils]
* [IPC::Run]
+* [IPC::Run::SafeHandles]
+* [IPC::Run::Simple]
* [IPC::Run3]
+* [IPC::System::Simple]
+* [Tee]
+* [IO::Tee]
+* [File::Tee]
+* [Filter::Handle]
+* [Tie::STDERR]
+* [Tie::STDOUT]
+* [Test::Output]
= AUTHOR
View
139 lib/Capture/Tiny.pod
@@ -4,15 +4,15 @@
=head1 NAME
-Capture::Tiny - Capture STDOUT and STDERR from perl, XS or system commands
+Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external programs
=head1 VERSION
This documentation describes version 0.01.
=head1 SYNOPSIS
- use Capture::Tiny;
+ use Capture::Tiny qw/capture tee/;
($stdout, $stderr) = capture {
# your code here
@@ -24,15 +24,53 @@ This documentation describes version 0.01.
=head1 DESCRIPTION
+Capture::Tiny provides a simple, portable way to capture anything sent to
+STDOUT or STDERR, regardless of whether it comes from Perl, from XS 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.
+
+This module was heavily inspired by L<IO::CaptureOutput>, which provides
+similar functionality without the ability to tee output and with more
+complicated code and API.
+
=head1 USAGE
+The following functions are available. None are exported by default.
+
=head2 capture
- ($stdout, $stderr) = capture \&code_ref;
+ ($stdout, $stderr) = capture \&code;
+ $stdout = capture \&code;
+
+The C<<< capture >>> function takes a code reference and returns what is sent to
+STDOUT and STDERR. In scalar context, it returns only STDOUT. Regardless of
+context, all output is captured -- nothing is passed to the existing handles.
+
+It is prototyped to take a subroutine reference as an argument. Thus, it
+can be called in block form:
+
+ ($stdout, $stderr) = capture {
+ # your code here ...
+ };
=head2 tee
- ($stdout, $stderr) = capture \&code_ref;
+ ($stdout, $stderr) = tee \&code;
+ $stdout = tee \&code;
+
+The C<<< tee >>> function works just like C<<< capture >>>, except that output is captured
+as well as passed on to the original STDOUT and STDERR. As with C<<< capture >>> it
+may be called in block form.
+
+=head1 LIMITATIONS
+
+Portability is a goal, not a guarantee. C<<< tee >>> requires fork, except on
+Windows where C<<< system(1, @cmd) >>> is used instead. Not tested on any
+esoteric platforms yet. Minimal test suite so far.
+
+No support for merging STDERR with STDOUT. This may be added in the future.
=head1 BUGS
@@ -45,6 +83,99 @@ existing test-file that illustrates the bug or desired feature.
=head1 SEE ALSO
+This is a selection of CPAN 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 show why
+I felt Capture::Tiny was necessary.
+
+=over
+
+=item *
+
+L<IO::Capture>
+
+=item *
+
+L<IO::Capture::Extended>
+
+=item *
+
+L<IO::CaptureOutput>
+
+=item *
+
+L<IPC::Capture>
+
+=item *
+
+L<IPC::Cmd>
+
+=item *
+
+L<IPC::Open2>
+
+=item *
+
+L<IPC::Open3>
+
+=item *
+
+L<IPC::Open3::Simple>
+
+=item *
+
+L<IPC::Open3::Utils>
+
+=item *
+
+L<IPC::Run>
+
+=item *
+
+L<IPC::Run::SafeHandles>
+
+=item *
+
+L<IPC::Run::Simple>
+
+=item *
+
+L<IPC::Run3>
+
+=item *
+
+L<IPC::System::Simple>
+
+=item *
+
+L<Tee>
+
+=item *
+
+L<IO::Tee>
+
+=item *
+
+L<File::Tee>
+
+=item *
+
+L<Filter::Handle>
+
+=item *
+
+L<Tie::STDERR>
+
+=item *
+
+L<Tie::STDOUT>
+
+=item *
+
+L<Test::Output>
+
+=back
+
=head1 AUTHOR
David A. Golden (DAGOLDEN)

0 comments on commit a9c7cd5

Please sign in to comment.
Something went wrong with that request. Please try again.