NAME

       IO::Pager::Buffered - Pipe deferred output to PAGER if destination is a TTY

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;
         }

DESCRIPTION

       IO::Pager subclasses are designed to programmatically decide whether or not to pipe a
       filehandle's output to a program specified in PAGER; determined and set by IO::Pager at
       runtime if not yet defined.

       This subclass buffers all output for display until execution returns to the parent scope
       or a manual flush occurs. If this is not what you want look at another subclass such as
       IO::Pager::Unbuffered. While probably not common, this may be useful in some cases, such
       as buffering all output to STDOUT while the process occurs so that warnings on STDERR are
       more visible, then displaying the less urgent output from STDOUT after. Or, alternately,
       letting output to STDOUT slide by and defer warnings for later perusal.

METHODS

       Class-specific method specifics below, others are inherited from IO::Pager.

   open( [FILEHANDLE] )
       Instantiate a new IO::Pager to paginate FILEHANDLE if necessary.  Assign the return value
       to a scoped variable. Output does not occur until the filehandle is flushed or closed.

   new( [FILEHANDLE] )
       Almost identical to open, except that you will get an IO::Handle back if there's no TTY to
       allow for IO::Pager agnostic programming.

   close( FILEHANDLE )
       Flushes the buffer to the pager and closes the filehandle for writing.  Normally, when
       using a lexically or locally scoped variable to hold the token supplied by open, explicit
       calls to close are unnecessary.  However, if you are using IO::Pager::Buffered with an
       unlocalized STDOUT or STDERR you close the filehandle to display the buffered content or
       wait for global garbage cleaning upon program termination.

       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.

   tell( FILEHANDLE )
       Returns the size of the buffer in bytes.

   flush( FILEHANDLE )
       Immediately flushes the contents of the buffer.

       If the last print did not end with a newline, the text from the preceding newline to the
       end of the buffer will be flushed but is unlikely to display until a newline is printed
       and flushed.

CAVEATS

       If you mix buffered and unbuffered operations the output order is unspecified, and will
       probably differ for a TTY vs. a file. 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

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

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.