NAME

PerlIO::tee - Multiplex output layer

SYNOPSIS

open my $out, '>>:tee', $file, @sources;

$out->push_layer(tee => $file);
$out->push_layer(tee => ">> $file");
$out->push_layer(tee => \$scalar);
$out->push_layer(tee => \*FILEHANDLE);

DESCRIPTION

PerlIO::tee provides a multiplex output stream like tee(1) command. It makes a filehandle write to one or more files (or scalars via the :scalar layer) at the same time.

You can use push_layer() (defined in PerlIO::Util) to add a source to a filehandle. The source may be a file name, a scalar reference, or a filehandle. For example:

$fh->push_layer(tee => $file);    # meaning "> $file"
$fh->push_layer(tee => ">>$file");# append mode
$fh->push_layer(tee => \$scalar); # via :scalar
$fh->push_layer(tee => \*OUT);    # shallow copy, not duplication

You can also use open() with multiple arguments. However, it is just a syntax sugar to call push_layer(): One :tee layer has a single extra filehandle, so arguments $x, $y, $z of open(), for example, prepares a filehandle with one default layer and two :tee layers with a internal filehandle.

open my $tee, '>:tee', $x, $y, $z;
# the code above means:
#   open my $tee, '>', $x;
#   $tee->push_layer(tee => $y);
#   $tee->push_layer(tee => $z);

$tee->get_layers(); # => "perlio", "tee($y)", "tee($z)"

$tee->pop_layer();  # "tee($z)" is popped
$tee->pop_layer();  # "tee($y)" is popped
# now $tee is a filehandle only to $x

EXAMPLE

Here is an minimal implementation of tee(1).

#!/usr/bin/perl -w
# Usage: $0 files...
use strict;
use PerlIO::Util;

STDOUT->push_layer(tee => $_) for @ARGV;

while(read STDIN, $_, 2**12){
	print;
}
__END__

SEE ALSO

PerlIO::Util.

AUTHOR

Goro Fuji <gfuji (at) cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2008, Goro Fuji <gfuji (at) cpan.org>. Some rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.