| # 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.13 |
| |
| =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. |
| |
| |
