OptArgs2::Pager - pipe output to a system (text) pager
2.0.0 (2022-10-05)
use OptArgs2::Pager 'start_pager', 'page', 'stop_pager'; # One-shot output to a pager page("this goes to a page with page()\n" x 50); # Or make the pager filehandle the default start_pager(); print "This text also goes pager by default\n" x 50; stop_pager(); print "This text goes straight to STDOUT\n"; # Scoped { my $pager = OptArgs2::Pager->new; print "Back to a pager by default\n" x 50; } print "Back to STDOUT\n";
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.
An all-in-one function to start a pager (using the optional %ARGS passed directly to new() below), send it a $string, and close it. If a pager is already running when this is called (due to a previous start_pager()) it will reused and left open. Returns the response from the underlying printflush().
%ARGS
new()
$string
start_pager()
Create a pager using %ARGS (passed directly to new() below) and makes it the default output file handle.
Make the original file handle (usually STDOUT) the default again. Closes the pager input, letting it know that no more content is coming.
The new() constuctor takes the following arguments.
auto => 1
By default the pager is selected as the default filehandle when the object is created. Set auto to a false value to inhibit this behaviour.
auto
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
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.
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.
Already mentioned above is the check for $PAGER when choosing which pager to run. Additionally, OptArgs2 temporarily sets $LESS to -FSXeR and $MORE to -FXer if they are unset at the time the pager is opened.
$PAGER
$LESS
-FSXeR
$MORE
-FXer
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.
Mark Lawrence <nomad@null.net>
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.
To install OptArgs2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OptArgs2
CPAN shell
perl -MCPAN -e shell install OptArgs2
For more information on module installation, please visit the detailed CPAN module installation guide.