.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "IO::Pager 3pm"
.TH IO::Pager 3pm "2020-11-07" "perl v5.30.3" "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 \- Select a pager (possibly perl\-based) & pipe it text if a TTY
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # Select an appropriate pager and set the PAGER environment variable
\&  use IO::Pager;
\&
\&  # TIMTOWTDI Object\-oriented
\&  {
\&    # open()                           # Use all the defaults.
\&    my $object = new IO::Pager;
\&
\&    # open FILEHANDLE                  # Unbuffered is default subclass
\&    my $object = new IO::Pager *STDOUT;
\&
\&    # open FILEHANDLE,EXPR             # Specify subclass
\&    my $object = new IO::Pager *STDOUT,  \*(AqUnbuffered\*(Aq;
\&
\&    # Direct subclass instantiation    # FH is optional
\&    use IO::Pager::Unbuffered;
\&    my $object = new IO::Pager::Unbuffered  *STDOUT;
\&
\&
\&    $object\->print("OO shiny...\en") while 1;
\&    print "Some other text sent to STODUT, perhaps from a foreign routine."
\&
\&    # $object passes out of scope and filehandle is automagically closed
\&  }
\&
\&  # TIMTOWTDI Procedural
\&  {
\&    # open FILEHANDLE                    # Unbuffered is default subclass
\&    my $token = IO::Pager::open *STDOUT;
\&
\&    # open FILEHANDLE,EXPR               # Specify subclass
\&    my $token = IO::Pager::open *STDOUT,  \*(AqUnbuffered\*(Aq;
\&
\&    # open FILEHANDLE,MODE,EXPR          # En lieu of a separate binmode()
\&    my $token = IO::Pager::open *STDOUT, \*(Aq|\-:utf8\*(Aq, \*(AqUnbuffered\*(Aq;
\&
\&
\&    print <<"  HEREDOC" ;
\&    ...
\&    A bunch of text later
\&    HEREDOC
\&
\&    # $token passes out of scope and filehandle is automagically closed
\&  }
\&
\&  {
\&    # You can also use scalar filehandles...
\&    my $token = IO::Pager::open(my $FH) or warn($!); XXX
\&    print $FH "No globs or barewords for us thanks!\en" while 1;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IO::Pager can be used to locate an available pager and set the \fI\s-1PAGER\s0\fR
environment variable (see \*(L"\s-1NOTES\*(R"\s0). It is also a factory for creating
I/O objects such as IO::Pager::Buffered and IO::Pager::Unbuffered.
.PP
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.
Subclasses may implement only the \s-1IO\s0 handle methods desired and inherit
the remainder of those outlined below from IO::Pager. For anything else,
\&\s-1YMMV.\s0 See the appropriate subclass for implementation specific details.
.SH "METHODS"
.IX Header "METHODS"
.SS "new( \s-1FILEHANDLE,\s0 [\s-1MODE\s0], [\s-1SUBCLASS\s0] )"
.IX Subsection "new( FILEHANDLE, [MODE], [SUBCLASS] )"
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 "open( \s-1FILEHANDLE,\s0 [\s-1MODE\s0], [\s-1SUBCLASS\s0] )"
.IX Subsection "open( FILEHANDLE, [MODE], [SUBCLASS] )"
Instantiate a new IO::Pager, which will paginate output sent to
\&\s-1FILEHANDLE\s0 if interacting with a \s-1TTY.\s0
.PP
Save the return value to check for errors, use as an object,
or for implict close of \s-1OO\s0 handles when the variable passes out of scope.
.IP "\s-1FILEHANDLE\s0" 4
.IX Item "FILEHANDLE"
You may provide a glob or scalar.
.Sp
Defaults to currently \fBselect()\fR\-ed \fI\s-1FILEHANDLE\s0\fR.
.IP "\s-1SUBCLASS\s0" 4
.IX Item "SUBCLASS"
Specifies which variety of IO::Pager to create.
This accepts fully qualified packages \fIIO::Pager::Buffered\fR,
or simply the third portion of the package name \fIBuffered\fR for brevity.
.Sp
Defaults to IO::Pager::Unbuffered.
.Sp
Returns false and sets \fI$!\fR on failure, same as perl's \f(CW\*(C`open\*(C'\fR.
.SS "\s-1PID\s0"
.IX Subsection "PID"
Call this method on the token returned by \f(CW\*(C`open\*(C'\fR to get the process
identifier for the child process i.e; pager; if you need to perform
some long term process management e.g; perl's \f(CW\*(C`waitpid\*(C'\fR
.PP
You can also access the \s-1PID\s0 by numifying the instantiation token like so:
.PP
.Vb 1
\&  my $child = $token+0;
.Ve
.SS "close( \s-1FILEHANDLE\s0 )"
.IX Subsection "close( FILEHANDLE )"
Explicitly close the filehandle, this stops any redirection of output
on \s-1FILEHANDLE\s0 that may have been warranted.
.PP
\&\fIThis does not default to the current filehandle\fR.
.PP
Alternatively, you may rely upon the implicit close of lexical handles
as they pass out of scope e.g;
.PP
.Vb 6
\&  {
\&     IO::Pager::open local *RIBBIT;
\&     print RIBBIT "No toad sexing allowed";
\&     ...
\&  }
\&  #The filehandle is closed to additional output
\&
\&  {
\&     my $token = new IO::Pager::Buffered;
\&     $token\->print("I like trains");
\&     ...
\&  }
\&  #The string "I like trains" is flushed to the pager, and the handle closed
.Ve
.SS "binmode( \s-1FILEHANDLE,\s0 [\s-1LAYER\s0] )"
.IX Subsection "binmode( FILEHANDLE, [LAYER] )"
Used to set the I/O layer a.k.a. discipline of a filehandle,
such as \f(CW\*(Aq:utf8\*(Aq\fR for \s-1UTF\-8\s0 encoding.
.PP
\fI:LOG([>>\s-1FILE\s0])\fR
.IX Subsection ":LOG([>>FILE])"
.PP
IO::Pager implements a pseudo-IO-layer for capturing output and sending it
to a file, similar to \fBtee\fR\|(1). Although it is limited to one file, this
feature is pure-perl and adds no dependencies.
.PP
You may indicate what file to store in parentheses, otherwise the default is
\&\f(CW\*(C`$$.log\*(C'\fR. You may also use an implicit (no indicator) or explicit (\fI>\fR)
indicator to overwrite an existing file, or an explicit (\fI>>\fR) for
appending to a log file. For example:
.PP
.Vb 3
\&    binmode(*STDOUT, \*(Aq:LOG(clobber.log)\*(Aq);
\&    ...
\&    $STDOUT\->binmode(\*(Aq:LOG(>>noclobber.log)\*(Aq);
.Ve
.PP
For full tee-style support, use PerlIO::Util like so:
.PP
.Vb 3
\&    binmode(*STDOUT, ":tee(TH)");
\&    #OR
\&    $STDOUT\->binmode(\*(Aq:tee(TH)\*(Aq);
.Ve
.SS "eof( \s-1FILEHANDLE\s0 )"
.IX Subsection "eof( FILEHANDLE )"
Used in the eval-until-eof idiom below, \fIIO::Pager\fR will handle broken pipes
from deceased children for you in one of two ways. If \fI\f(CI$ENV\fI{\s-1IP_EOF\s0}\fR is
false then program flow will pass out of the loop on \fI\s-1SIGPIPE\s0\fR, this is the
default. If the variable is true, then the program continues running with
output for the previously paged filehandle directed to the \fI\s-1STDOUT\s0\fR stream;
more accurately, the filehandle is reopened to file descriptor 1.
.PP
.Vb 7
\&  use IO::Pager::Page; #or whichever you prefer;
\&  ...
\&  eval{
\&    say "Producing prodigious portions of product";
\&    ...
\&  } until( eof(*STDOUT) );
\&  print "Cleaning up after our child before terminating."
.Ve
.PP
If using \fBeof()\fR with less, especially when \s-1IP_EOF\s0 is set, you may want to
use the \fI\-\-no\-init\fR option by setting \fI\f(CI$ENV\fI{\s-1IP_EOF\s0}='X'\fR to prevent the
paged output from being erased when the pager exits.
.SS "fileno( \s-1FILEHANDLE\s0 )"
.IX Subsection "fileno( FILEHANDLE )"
Return the filehandle number of the write-only pipe to the pager.
.SS "print( \s-1FILEHANDLE LIST\s0 )"
.IX Subsection "print( FILEHANDLE LIST )"
\&\fBprint()\fR to the filehandle.
.SS "printf( \s-1FILEHANDLE FORMAT, LIST\s0 )"
.IX Subsection "printf( FILEHANDLE FORMAT, LIST )"
\&\fBprintf()\fR to the filehandle.
.SS "syswrite( \s-1FILEHANDLE, SCALAR,\s0 [\s-1LENGTH\s0], [\s-1OFFSET\s0] )"
.IX Subsection "syswrite( FILEHANDLE, SCALAR, [LENGTH], [OFFSET] )"
\&\fBsyswrite()\fR to the filehandle.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1IP_EOF\s0" 4
.IX Item "IP_EOF"
Controls IO:Pager behavior when \f(CW\*(C`eof\*(C'\fR is used.
.IP "\s-1PAGER\s0" 4
.IX Item "PAGER"
The location of the default pager.
.IP "\s-1PATH\s0" 4
.IX Item "PATH"
If the location in \s-1PAGER\s0 is not absolute, \s-1PATH\s0 may be searched.
.Sp
See \*(L"\s-1NOTES\*(R"\s0 for more information.
.SH "FILES"
.IX Header "FILES"
IO::Pager may fall back to these binaries in order if \fI\s-1PAGER\s0\fR is not
executable.
.IP "/etc/alternatives/pager" 4
.IX Item "/etc/alternatives/pager"
.PD 0
.IP "/usr/local/bin/less" 4
.IX Item "/usr/local/bin/less"
.IP "/usr/bin/less" 4
.IX Item "/usr/bin/less"
.ie n .IP "IO::Pager::Perl as ""tp"" via IO::Pager::less" 4
.el .IP "IO::Pager::Perl as \f(CWtp\fR via IO::Pager::less" 4
.IX Item "IO::Pager::Perl as tp via IO::Pager::less"
.IP "/usr/bin/more" 4
.IX Item "/usr/bin/more"
.PD
.PP
See \*(L"\s-1NOTES\*(R"\s0 for more information.
.SH "NOTES"
.IX Header "NOTES"
The algorithm for determining which pager to use is as follows:
.IP "1. Defer to \fI\s-1PAGER\s0\fR" 4
.IX Item "1. Defer to PAGER"
If the \fI\s-1PAGER\s0\fR environment variable is set, use the pager it identifies,
unless this pager is not available.
.IP "2. Usual suspects" 4
.IX Item "2. Usual suspects"
Try the standard, hardcoded paths in \*(L"\s-1FILES\*(R"\s0.
.IP "3. File::Which" 4
.IX Item "3. File::Which"
If File::Which is available, use the first pager possible amongst
\&\f(CW\*(C`less\*(C'\fR, \f(CW\*(C`most\*(C'\fR, \f(CW\*(C`w3m\*(C'\fR, \f(CW\*(C`lv\*(C'\fR, \f(CW\*(C`pg\*(C'\fR and more.
.IP "4. Term::Pager via IO::Pager::Perl" 4
.IX Item "4. Term::Pager via IO::Pager::Perl"
You may also set \f(CW$ENV\fR{\s-1PAGER\s0} to
Term::Pager to select this extensible, pure perl pager for display.
.IP "5. more" 4
.IX Item "5. more"
Set \fI\s-1PAGER\s0\fR to \f(CW\*(C`more\*(C'\fR, and cross our fingers.
.PP
Steps 1, 3 and 5 rely upon the \fI\s-1PATH\s0\fR environment variable.
.SH "CAVEATS"
.IX Header "CAVEATS"
You probably want to do something with \s-1SIGPIPE\s0 eg;
.PP
.Vb 3
\&  eval {
\&    local $SIG{PIPE} = sub { die };
\&    local $STDOUT = IO::Pager::open(*STDOUT);
\&
\&    while (1) {
\&      # Do something
\&    }
\&  }
\&
\&  # Do something else
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Pager::Buffered, IO::Pager::Unbuffered, I::Pager::Perl,
IO::Pager::Page, IO::Page, Meta::Tool::Less
.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\-2020 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.