IO::Pager - Select a pager, optionally pipe it output if destination is a TTY

NAME

IO::Pager - Select a pager, optionally pipe it output if destination is a TTY

SYNOPSIS

  #Select a pager, sets $ENV{PAGER}
  use IO::Pager;
  #Optionally pipe output
  {
    #local $STDOUT =     IO::Pager::open *STDOUT;
    local  $STDOUT = new IO::Pager       *STDOUT;
    print <<"  HEREDOC" ;
    ...
    A bunch of text later
    HEREDOC
  }

DESCRIPTION

IO::Pager is lightweight and can be used to locate an available pager and set $ENV{PAGER} (see NOTES) or as a factory for creating objects defined elsewhere such as the IO::Pager::Buffered manpage and the IO::Pager::Unbuffered manpage.

IO::Pager subclasses are designed to programmatically decide whether or not to pipe a filehandle's output to a program specified in $ENV{PAGER}. Subclasses are only required to support filehandle output methods and close, namely

CLOSE
Supports close() of the filehandle.

PRINT
Supports print() to the filehandle.

PRINTF
Supports printf() to the filehandle.

WRITE
Supports syswrite() to the filehandle.

For anything else, YMMV.

new( [FILEHANDLE], [EXPR] )

Instantiate a new IO::Pager to paginate FILEHANDLE if necessary. Assign the return value to a scoped variable.

See the appropriate subclass for implementation specific details.

FILEHANDLE
Defaults to currently select()-ed FILEHANDLE.

EXPR
An expression which evaluates to the subclass of object to create.

Defaults to the IO::Pager::Unbuffered manpage.

open( [FILEHANDLE], [EXPR] )

An alias for new.

close( FILEHANDLE )

Explicitly close the filehandle, this stops any redirection of output on FILEHANDLE that may have been warranted. Normally you'd just wait for the object to pass out of scope.

This does not default to the current filehandle.

See the appropriate subclass for implementation specific details.

ENVIRONMENT

PAGER
The location of the default pager.

PATH
If PAGER does not specify an absolute path for the binary PATH may be used.

See NOTES for more information.

FILES

IO::Pager may fall back to these binaries in order if $ENV{PAGER} is not executable.

/usr/local/bin/less
/usr/bin/less
/usr/bin/more

See NOTES for more information.

NOTES

The algorythm for determining which pager is to use as follows:

  1. Defer to $ENV{PAGER}
    Use the value of $ENV{PAGER} if it exists unless File::Which is available and the pager in $ENV{PAGER} is determined to be unavailable.

  2. Usual suspects
    Try the standard, hardcoded paths in FILES.

  3. File::Which
    If File::Which is available check for less and the more manpage.

  4. more
    Set $ENV{PAGER} to more

Steps 1, 3 and 4 rely upon $ENV{PATH}.

SEE ALSO

the IO::Pager::Buffered manpage, the IO::Pager::Unbuffered manpage, the IO::Pager::Page manpage

the IO::Page manpage, the Tool::Less manpage

AUTHOR

Jerrad Pierce <jpierce@cpan.org>

This module is forked from IO::Page 0.02 by Monte Mitzelfelt

LICENSE

 IO::Pager - Select a pager, optionally pipe it output if destination is a TTY