IO::Tee(3)

📦
version 0.66 · 8 versions
, in alpine 3.24

🎀 NAME — IO::Tee(3) 🎀

okay so this is IO::Tee(3) from User Contributed Perl Documentation, and it is literally the multiplexing bestie for Perl handles. The NAME line is:

IO::Tee — Multiplex output to multiple output handles.

✨ SYNOPSIS ✨

use IO::Tee;

$tee = IO::Tee->new($handle1, $handle2);
print $tee "foo", "bar";
my $input = <$tee>;

💖 DESCRIPTION 💖

IO::Tee objects are your little multiplexing besties — they can handle input and output in two different ways, and both are iconic.

🌸 Way #1: output multiplexing 🌸

You can multiplex output to zero or more output handles. The IO::Tee constructor, given a list of output handles, returns a tied handle that can be written to. When you write to it (using print or printf), the IO::Tee object multiplexes the output to the list of handles originally passed to the constructor.

As a shortcut, you can also directly pass a string or an array reference to the constructor, in which case IO::File::new is called for you with the specified argument or arguments. Convenient? yes. Chaotic? maybe a little. Slay? absolutely.

🦋 Way #2: input multiplexing 🦋

You can also multiplex input from one input handle to zero or more output handles as it is being read. The IO::Tee constructor, given an input handle followed by a list of output handles, returns a tied handle that can be read from as well as written to.

When written to, the IO::Tee object multiplexes the output to all handles passed to the constructor, as described in the previous paragraph. When read from, the IO::Tee object reads from the input handle given as the first argument to the IO::Tee constructor, then writes any data read to the output handles given as the remaining arguments to the constructor.

💅 the method groups, bestie 💅

The IO::Tee class supports certain IO::Handle and IO::File methods related to input and output.

🔥 methods that loop over all associated handles 🔥

These methods iterate themselves over all handles associated with the IO::Tee object, and return TRUE indicating success if and only if all associated handles returned TRUE indicating success:

  • close
  • truncate
  • write
  • syswrite
  • format_write
  • formline
  • fcntl
  • ioctl
  • flush
  • clearerr
  • seek

🌈 methods that do input multiplexing 🌈

The following methods perform input multiplexing as described above:

  • read
  • sysread
  • readline
  • getc
  • gets
  • eof
  • getline
  • getlines

🙈 methods that set output state (but do not retrieve it) 🙈

The following methods can be used to set (but not retrieve) the current values of output-related state variables on all associated handles:

  • autoflush
  • output_field_separator
  • output_record_separator
  • format_page_number
  • format_lines_per_page
  • format_lines_left
  • format_name
  • format_top_name
  • format_line_break_characters
  • format_formfeed

🫶 methods that go straight to the input handle 🫶

The following methods are directly passed on to the input handle given as the first argument to the IO::Tee constructor:

  • input_record_separator
  • input_line_number
🚨 tiny but important: the return value of input multiplexing methods (such as "print") is always the return value of the input action, not the return value of subsequent output actions. In particular, no error is indicated by the return value if the input action itself succeeds but subsequent output multiplexing fails. So do not let that return value gaslight you, bestie.

🍓 EXAMPLE 🍓

use IO::Tee;
use IO::File;

my $tee = new IO::Tee(\*STDOUT,
    new IO::File(">tt1.out"), ">tt2.out");

print join(' ', $tee->handles), "\n";

for (1..10) { print $tee $_, "\n" }
for (1..10) { $tee->print($_, "\n") }
$tee->flush;

$tee = new IO::Tee('</etc/passwd', \*STDOUT);
my @lines = <$tee>;
print scalar(@lines);

🔗 REPOSITORY 🔗

The repo lives at <https://github.com/neilb/IO-Tee> — go poke around, it's giving open source excellence.

👑 AUTHOR 👑

Chung-chieh Shan, ken@digitas.harvard.edu

As of August 2017, now being maintained by Neil Bowers. Shoutout to the maintainer era.

Copyright (c) 1998-2017 Chung-chieh Shan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🦋 SEE ALSO 🦋

  • perlfunc
  • IO::Handle
  • IO::File

This page is from perl v5.42.2, dated 2024-02-21, for IO::Tee(3) — byeee, go tee something fabulous 💅✨

📦 where this page comes from