# Generated by Pod::WikiDoc version 0.15

=pod

=head1 NAME

Tee - Pure Perl emulation of GNU tee

=head1 VERSION

This documentation refers to version 0.12

=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<ptee> 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<ptee> 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<ptee> (default: false)

=item *

append -- passes the C<<< -a >>> flag to L<ptee> 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<IPC::Run3>, though it does not allow passing it through to a terminal at the
same time.

=head1 SEE ALSO

=over

=item *

L<ptee>

=item *

IPC::Run3

=item *

IO::Tee

=back

=head1 BUGS

Please report any bugs or feature using the CPAN Request Tracker.  
Bugs can be submitted by email to C<<< bug-Tee@rt.cpan.org >>> or 
through the web interface at 
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Tee>

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 A. Golden (DAGOLDEN)

dagolden@cpan.org

http:E<sol>E<sol>www.dagolden.orgE<sol>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2006 by David A. Golden

This program is free software; you can redistribute
it andE<sol>or modify it under the same terms as Perl itself.

The full text of the license can be found in the
LICENSE file included with this module.

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS ANDE<sol>OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY ANDE<sol>OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.


