.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Pager::Buffered 3pm"
.TH IO::Pager::Buffered 3pm "2012-09-04" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Pager::Buffered \- Pipe deferred output to PAGER if destination is a TTY
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  use IO::Pager::Buffered;
\&  {
\&    local $token = IO::Pager::Buffered::open *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!\en";
\&  }
\&
\&  {
\&    # ...or an object interface
\&    my $token = new IO::Pager::Buffered;
\&
\&    $token\->print("OO shiny...\en");
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IO::Pager subclasses are designed to programmatically decide whether
or not to pipe a filehandle's output to a program specified in \fI\s-1PAGER\s0\fR;
determined and set by IO::Pager at runtime if not yet defined.
.PP
This subclass buffers all output for display upon exiting the current scope.
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 \s-1STDOUT\s0 while the process occurs,
showing only warnings on \s-1STDERR,\s0 then displaying the output to \s-1STDOUT\s0 after.
Or alternately letting output to \s-1STDOUT\s0 slide by and defer warnings for later
perusal.
.SH "METHODS"
.IX Header "METHODS"
Class-specific method specifics below, others are inherited from IO::Pager.
.SS "open( [\s-1FILEHANDLE\s0] )"
.IX Subsection "open( [FILEHANDLE] )"
Instantiate a new IO::Pager to paginate \s-1FILEHANDLE\s0 if necessary.
\&\fIAssign the return value to a scoped variable\fR. Output does not
occur until all references to this variable are destroyed eg;
upon leaving the current scope. See \*(L"\s-1DESCRIPTION\*(R"\s0.
.SS "new( [\s-1FILEHANDLE\s0] )"
.IX Subsection "new( [FILEHANDLE] )"
Almost identical to open, except that you will get an IO::Handle
back if there's no \s-1TTY\s0 to allow for IO::Pager agnostic programming.
.SS "tell( \s-1FILEHANDLE \s0)"
.IX Subsection "tell( FILEHANDLE )"
Returns the size of the buffer in bytes.
.SS "flush( \s-1FILEHANDLE \s0)"
.IX Subsection "flush( FILEHANDLE )"
Immediately flushes the contents of the buffer.
.PP
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.
.SH "CAVEATS"
.IX Header "CAVEATS"
If you mix buffered and unbuffered operations the output order is unspecified,
and will probably differ for a \s-1TTY\s0 vs. a file. See perlfunc.
.PP
\&\fI$,\fR is used see perlvar.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Pager, IO::Pager::Unbuffered, IO::Pager::Page,
.SH "AUTHOR"
.IX Header "AUTHOR"
Jerrad Pierce <jpierce@cpan.org>
.PP
Florent Angly <florent.angly@gmail.com>
.PP
This module was inspired by Monte Mitzelfelt's IO::Page 0.02
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003\-2012 Jerrad Pierce
.IP "\(bu" 4
Thou shalt not claim ownership of unmodified materials.
.IP "\(bu" 4
Thou shalt not claim whole ownership of modified materials.
.IP "\(bu" 4
Thou shalt grant the indemnity of the provider of materials.
.IP "\(bu" 4
Thou shalt use and dispense freely without other restrictions.
.PP
Or, if you prefer:
.PP
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.