NAME

IO::Pager - Select a pager and pipe text to it if destination is a TTY

SYNOPSIS

  # Select an appropriate pager and set the PAGER environment variable
  use IO::Pager;

  # Optionally, pipe output to it
  {
    #local $retval =     IO::Pager::open *STDOUT; # Defaults to 'Unbuffered'
    local  $retval = new IO::Pager       *STDOUT, 'Buffered';
    print <<"  HEREDOC" ;
    ...
    A bunch of text later
    HEREDOC
  }

DESCRIPTION

IO::Pager can be used to locate an available pager and set the PAGER environment variable (see "NOTES"). It is also a factory for creating I/O objects such as IO::Pager::Buffered and IO::Pager::Unbuffered.

IO::Pager subclasses are designed to programmatically decide whether or not to pipe a filehandle's output to a program specified in PAGER. Subclasses may implement only the IO handle methods desired and inherit the following from IO::Pager:

BINMODE

Used to set the I/O layer a.ka. discipline of a filehandle, such as ':utf8' for UTF-8 encoding.

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], [SUBCLASS] )

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

The object will be of type SUBCLASS (IO::Pager::Unbuffered by default). See the appropriate subclass for details.

FILEHANDLE

Defaults to currently select()-ed FILEHANDLE.

EXPR

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

Defaults to IO::Pager::Unbuffered.

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 PAGER is not executable.

/usr/local/bin/less

/usr/bin/less

/usr/bin/more

See "NOTES" for more information.

NOTES

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

1. Defer to PAGER

If the PAGER environment variable is set, use the pagger it identifies, unless this pager is not available.

2. Usual suspects

Try the standard, hardcoded paths in "FILES".

3. File::Which

If File::Which is available, use the first pager possible amongst less, most, w3m and more.

4. more

Set PAGER to more, and cross our fingers.

Steps 1, 3 and 4 rely upon the PATH environment variable.

SEE ALSO

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

IO::Page, Meta::Tool::Less

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-2012 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.

cpanm IO::Pager

perl -MCPAN -e shell
install IO::Pager