File Coverage

blib/lib/Tee.pm

Criterion	Covered	Total	%
statement	20	20	100.0
branch	6	6	100.0
condition			n/a
subroutine	6	6	100.0
pod	1	1	100.0
total	33	33	100.0

#
# This file is part of Tee
#
# This software is Copyright (c) 2006 by David Golden.
#
# This is free software, licensed under:
#
#   The Apache License, Version 2.0, January 2004
#
use strict;
use warnings;
package Tee;
BEGIN {
  $Tee::VERSION = '0.14';
}
# ABSTRACT: Pure Perl emulation of GNU tee

use Exporter ();
use Probe::Perl;

our @ISA         = qw (Exporter);
our @EXPORT      = qw (tee);

#--------------------------------------------------------------------------#
# Platform independent ptee invocation
#--------------------------------------------------------------------------#

my $perl = Probe::Perl->find_perl_interpreter;
my $ptee_cmd = "$perl -MTee::App -e run --";

#--------------------------------------------------------------------------#
# Functions
#--------------------------------------------------------------------------#

sub tee {
    my $command = shift;
    my $options;
    $options = shift if (ref $_[0] eq 'HASH');
    my $files = join(" ", @_);
    my $redirect = $options->{stderr} ? " 2>&1 " : q{};
    my $append = $options->{append} ? " -a " : q{};
    system( "$command $redirect | $ptee_cmd $append $files" );
}

1; # modules must be true



=pod

=head1 NAME

Tee - Pure Perl emulation of GNU tee

=head1 VERSION

version 0.14

=head1 SYNOPSIS

  # from Perl
  use Tee;
  tee( $command, @files );

  # from the command line
  $ cat README.txt | ptee COPY.txt

=head1 DESCRIPTION

The C<<< Tee >>> distribution provides the L program, a pure Perl emulation of
the standard GNU tool C<<< tee >>>.  It is designed to be a platform-independent
replacement for operating systems without a native C<<< tee >>> program.  As with
C<<< tee >>>, it passes input received on STDIN through to STDOUT while also writing a
copy of the input to one or more files.  By default, files will be overwritten.

Unlike C<<< tee >>>, C<<< ptee >>> does not support ignoring interrupts, as signal handling
is not sufficiently portable.

The C<<< Tee >>> module provides a convenience function that may be used in place of
C<<< system() >>> to redirect commands through C<<< ptee >>>.

=head1 USAGE

=head2 C<<< tee() >>>

   tee( $command, @filenames );
   tee( $command, \%options, @filenames );

Executes the given command via C<<< system() >>>, but pipes it through L to copy
output to the list of files.  Unlike with C<<< system() >>>, the command must be a
string as the command shell is used for redirection and piping.  The return
value of C<<< system() >>> is passed through, but reflects the success of
the C<<< ptee >>> command, which isn't very useful.

The second argument may be a hash-reference of options.  Recognized options
include:

=over

=item *

stderr -- redirects STDERR to STDOUT before piping to L (default: false)

=item *

append -- passes the C<<< -a >>> flag to L to append instead of overwriting
(default: false)

=back

=head1 LIMITATIONS

Because of the way that C<<< Tee >>> uses pipes, it is limited to capturing a single
input stream, either STDOUT alone or both STDOUT and STDERR combined.  A good,
portable alternative for capturing these streams from a command separately is
L, though it does not allow passing it through to a terminal at the
same time.

=head1 SEE ALSO

=over

=item *

L

=item *

IPC::Run3

=item *

IO::Tee

=back

=head1 BUGS

Please report any bugs or feature using the CPAN Request Tracker.
Bugs can be submitted through the web interface at
L

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.

=head1 AUTHOR

David Golden

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2006 by David Golden.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut


__END__