NAME

OptArgs2::Pager - pipe output to a system (text) pager

VERSION

0.0.12_2 (2022-01-27)

SYNOPSIS

# If you want to test this synopsis example you will
# want to prevent OptArgs2::Pager setting default
# environment values which cause pagers to exit on short
# inputs
# $ENV{LESS} = $ENV{MORE} = '';

use OptArgs2::Pager;

# Functions
OptArgs2::Pager->on;
print "This text goes to a pager\n";

OptArgs2::Pager->off;
print "This text goes directly to STDOUT\n";

# Scoped
my $pager = OptArgs2::Pager->new;
print "Back to a pager\n";
undef $pager;
print "Back to STDOUT\n";

DESCRIPTION

OptArgs2::Pager opens a connection to a system pager and makes it the default filehandle so that by default any print statements are sent there.

When the pager object goes out of scope the previous default filehandle is selected again.

FUNCTIONS

OptArgs2::Pager->on(%ARGS)

Creates a (global singleton) pager using %ARGS (passed directly to new() below) and keeps it alive until off() is called.

OptArgs2::Pager->off()

Stops the global pager.

CONSTRUCTOR

The new() constuctor takes the following arguments.

auto => 1

By default the pager is opened when the object is created. Set auto to a false value to inhibit this behaviour.

encoding => ':utf8'

The Perl IO layer encoding to set after the pager has been opened. This defaults to ':utf8'. Set it to 'undef' to get binary mode.

pager => undef

The pager executable to run. The default is to check the PAGER environment variable, and if that is not set then the following programs will be searched for using File::Which: pager, less, most, w3m, lv, pg, more.

You can set PAGER to nothing to temporarily disable OptArgs2::Pager:

$ PAGER= your_cmd --your --options

ATTRIBUTES

fh

The underlying filehandle of the pager.

pid

The process ID of the pager program (only set on UNIX systems)

orig_fh

The original filehandle that was selected before the pager was started.

METHODS

close

Explicitly close the pager. This is useful if you want to keep the object around to start and stop the pager multiple times. Can be called safely when no pager is running.

open

Open the pager if it is not running. Can be called safely when the pager is already running.

SEE ALSO

IO::Pager - does something similar by mucking directly with STDOUT in a way that breaks fork/exec, and I couldn't for the life of me decipher the code style enough to fix it.

AUTHOR

Mark Lawrence <nomad@null.net>

COPYRIGHT AND LICENSE

Copyright 2014-2022 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.