IO::Pa...uffered(3pm)

💖 IO::Pager::Buffered — the manual, but make it cute 💖

okay bestie, welcome to IO::Pager::Buffered, from the Perl user-contributed docs, section 3pm. sit down, hydrate, and let's talk about deferred output. 🫶

---

✨ NAME ✨

IO::Pager::Buffered — it pipes your output to PAGER, but only if where you're sending it is actually a TTY. no TTY? no pager. it's giving ✨considerate✨.

---

🌸 SYNOPSIS 🌸

  use IO::Pager::Buffered;
  {
    local $token = IO::Pager::Buffered::open local *STDOUT;
    print <<"  HEREDOC" ;
    ...
    A bunch of text later
    HEREDOC
  }

  {
    # You can also use scalar filehandles...
    my $token = IO::Pager::Buffered::open($FH) or warn($!);
    print $FH "No globs or barewords for us thanks!\n" while 1;
  }

  {
    # ...or an object interface
    my $token = new IO::Pager::Buffered;

    $token->print("OO shiny...\n") while 1;
  }

three whole ways to do the thing. pick your fighter. 👑

---

🦋 DESCRIPTION 🦋

so like, the whole IO::Pager subclass family exists so you can programmatically decide whether or not to pipe a filehandle's output into some program that lives in PAGER. and who sets PAGER? IO::Pager does, at runtime, if you haven't already defined it yourself. teamwork. 💅

this particular subclass is the buffered one — capital B, capital energy. it holds all the output hostage until execution returns to the parent scope, or until you manually flush. that's the deal.

not what you wanted? go look at a different subclass, like IO::Pager::Unbuffered. it's fine. no hard feelings.

is buffering useful? probably not common, but lowkey yes in some cases:

• you could buffer everything headed to STDOUT while the process runs, so that warnings on STDERR are way more visible, and then show the less urgent STDOUT stuff after. 💖
• or, alternately, you let the STDOUT output slide right by and defer the warnings for later perusal. 🌈

---

💅 METHODS 💅

the class-specific deets are below, everything else you inherit from IO::Pager. nepotism, but make it OOP.

🎀 open( [FILEHANDLE] )

spin up a fresh IO::Pager to paginate FILEHANDLE — but only if necessary. assign the return value to a scoped variable. and listen: output does not occur until the filehandle is flushed or closed. no cap. the buffer is patient. 😌

🎀 new( [FILEHANDLE] )

almost identical to open, except you get an IO::Handle back if there's no TTY, so you can do IO::Pager agnostic programming. it's the same vibe but with a safety net. 🫶

🎀 close( FILEHANDLE )

flushes the buffer to the pager and closes the filehandle for writing.

normally, if your token lives in a lexically or locally scoped variable from open, you don't need to call close yourself — the scope handles it, iconic behaviour. ✨

but — and this is the important bit — if you're using IO::Pager::Buffered with an unlocalized STDOUT or STDERR, then you gotta close the filehandle to display the buffered content, or just sit there and wait for global garbage cleaning at program termination. your call. 🙈

alternatively? you might prefer to use a non-core filehandle with IO::Pager, and call "select" in perlfunc to make it the default for output. chef's kiss. 💅

🎀 tell( FILEHANDLE )

returns the size of the buffer in bytes. that's it. that's the method. 📏

🎀 flush( FILEHANDLE )

immediately flushes the contents of the buffer. boom. done.

heads up bestie: if the last print didn't end with a newline, the text from the preceding newline to the end of the buffer will be flushed — but it's unlikely to actually display until a newline is printed and flushed. so like, it's flushed but also not showing. the duality. 💀

---

⚠️ CAVEATS ⚠️

if you mix buffered and unbuffered operations, the output order is unspecified, and will probably differ for a TTY vs. a file. not a vibe. see perlfunc.

$, is used — see perlvar.

you probably want to do something with SIGPIPE, eg;

  eval {
    local $SIG{PIPE} = sub { die };
    local $STDOUT = IO::Pager::open(*STDOUT);

    while (1) {
      # Do something
    }
  }

  # Do something else

do it. trust. 🫶

---

👀 SEE ALSO 👀

IO::Pager, IO::Pager::Unbuffered, IO::Pager::Page,

---

💜 AUTHOR 💜

Jerrad Pierce <jpierce@cpan.org>

Florent Angly <florent.angly@gmail.com>

this module was inspired by Monte Mitzelfelt's IO::Page 0.02 — shoutout to the originator, we love an inspiration arc. 🌟

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (C) 2003-2018 Jerrad Pierce

• Thou shalt not claim ownership of unmodified materials.
• Thou shalt not claim whole ownership of modified materials.
• Thou shalt grant the indemnity of the provider of materials.
• Thou shalt use and dispense freely without other restrictions.

or, if you prefer:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.0 or, at your option, any later version of Perl 5 you may have available.

---

okay that's the whole page, periodt. 💖 this was perl v5.30.3, dated 2020-11-07, and the manual is IO::Pa...uffered(3pm) — yes the title gets truncated in the header, that's just how the terminal does her. go forth and buffer responsibly. 🦋✨🎀