IO::Pager(3pm)

1IO::Pager(3)          User Contributed Perl Documentation         IO::Pager(3)
2
3
4

NAME

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

SYNOPSIS

9         # Select an appropriate pager and set the PAGER environment variable
10         use IO::Pager;
11
12         # TIMTOWTDI Object-oriented
13         {
14           # open()                           # Use all the defaults.
15           my $object = new IO::Pager;
16
17           # open FILEHANDLE                  # Unbuffered is default subclass
18           my $object = new IO::Pager *STDOUT;
19
20           # open FILEHANDLE,EXPR             # Specify subclass
21           my $object = new IO::Pager *STDOUT,  'Unbuffered';
22
23           # Direct subclass instantiation    # FH is optional
24           use IO::Pager::Unbuffered;
25           my $object = new IO::Pager::Unbuffered  *STDOUT;
26
27
28           $object->print("OO shiny...\n") while 1;
29           print "Some other text sent to STODUT, perhaps from a foreign routine."
30
31           # $object passes out of scope and filehandle is automagically closed
32         }
33
34         # TIMTOWTDI Procedural
35         {
36           # open FILEHANDLE                    # Unbuffered is default subclass
37           my $token = IO::Pager::open *STDOUT;
38
39           # open FILEHANDLE,EXPR               # Specify subclass
40           my $token = IO::Pager::open *STDOUT,  'Unbuffered';
41
42           # open FILEHANDLE,MODE,EXPR          # En lieu of a separate binmode()
43           my $token = IO::Pager::open *STDOUT, '|-:utf8', 'Unbuffered';
44
45
46           print <<"  HEREDOC" ;
47           ...
48           A bunch of text later
49           HEREDOC
50
51           # $token passes out of scope and filehandle is automagically closed
52         }
53
54         {
55           # You can also use scalar filehandles...
56           my $token = IO::Pager::open(my $FH) or warn($!); XXX
57           print $FH "No globs or barewords for us thanks!\n" while 1;
58         }
59

DESCRIPTION

61       IO::Pager can be used to locate an available pager and set the PAGER
62       environment variable (see "NOTES"). It is also a factory for creating
63       I/O objects such as IO::Pager::Buffered and IO::Pager::Unbuffered.
64
65       IO::Pager subclasses are designed to programmatically decide whether or
66       not to pipe a filehandle's output to a program specified in PAGER.
67       Subclasses may implement only the IO handle methods desired and inherit
68       the remainder of those outlined below from IO::Pager. For anything
69       else, YMMV. See the appropriate subclass for implementation specific
70       details.
71

METHODS

73   new( FILEHANDLE, [MODE], [SUBCLASS] )
74       Almost identical to open, except that you will get an IO::Handle back
75       if there's no TTY to allow for IO::Pager-agnostic programming.
76
77   open( FILEHANDLE, [MODE], [SUBCLASS] )
78       Instantiate a new IO::Pager, which will paginate output sent to
79       FILEHANDLE if interacting with a TTY.
80
81       Save the return value to check for errors, use as an object, or for
82       implict close of OO handles when the variable passes out of scope.
83
84       FILEHANDLE
85           You may provide a glob or scalar.
86
87           Defaults to currently select()-ed FILEHANDLE.
88
89       SUBCLASS
90           Specifies which variety of IO::Pager to create.  This accepts fully
91           qualified packages IO::Pager::Buffered, or simply the third portion
92           of the package name Buffered for brevity.
93
94           Defaults to IO::Pager::Unbuffered.
95
96           Returns false and sets $! on failure, same as perl's "open".
97
98   PID
99       Call this method on the token returned by "open" to get the process
100       identifier for the child process i.e; pager; if you need to perform
101       some long term process management e.g; perl's "waitpid"
102
103       You can also access the PID by numifying the instantiation token like
104       so:
105
106         my $child = $token+0;
107
108   close( FILEHANDLE )
109       Explicitly close the filehandle, this stops any redirection of output
110       on FILEHANDLE that may have been warranted.
111
112       This does not default to the current filehandle.
113
114       Alternatively, you may rely upon the implicit close of lexical handles
115       as they pass out of scope e.g;
116
117         {
118            IO::Pager::open local *RIBBIT;
119            print RIBBIT "No toad sexing allowed";
120            ...
121         }
122         #The filehandle is closed to additional output
123
124         {
125            my $token = new IO::Pager::Buffered;
126            $token->print("I like trains");
127            ...
128         }
129         #The string "I like trains" is flushed to the pager, and the handle closed
130
131   binmode( FILEHANDLE, [LAYER] )
132       Used to set the I/O layer a.k.a. discipline of a filehandle, such as
133       ':utf8' for UTF-8 encoding.
134
135       :LOG([>>FILE])
136
137       IO::Pager implements a pseudo-IO-layer for capturing output and sending
138       it to a file, similar to tee(1). Although it is limited to one file,
139       this feature is pure-perl and adds no dependencies.
140
141       You may indicate what file to store in parentheses, otherwise the
142       default is "$$.log". You may also use an implicit (no indicator) or
143       explicit (>) indicator to overwrite an existing file, or an explicit
144       (>>) for appending to a log file. For example:
145
146           binmode(*STDOUT, ':LOG(clobber.log)');
147           ...
148           $STDOUT->binmode(':LOG(>>noclobber.log)');
149
150       For full tee-style support, use PerlIO::Util like so:
151
152           binmode(*STDOUT, ":tee(TH)");
153           #OR
154           $STDOUT->binmode(':tee(TH)');
155
156   eof( FILEHANDLE )
157       Used in the eval-until-eof idiom below, IO::Pager will handle broken
158       pipes from deceased children for you in one of two ways. If
159       $ENV{IP_EOF} is false then program flow will pass out of the loop on
160       SIGPIPE, this is the default. If the variable is true, then the program
161       continues running with output for the previously paged filehandle
162       directed to the STDOUT stream; more accurately, the filehandle is
163       reopened to file descriptor 1.
164
165         use IO::Pager::Page; #or whichever you prefer;
166         ...
167         eval{
168           say "Producing prodigious portions of product";
169           ...
170         } until( eof(*STDOUT) );
171         print "Cleaning up after our child before terminating."
172
173       If using eof() with less, especially when IP_EOF is set, you may want
174       to use the --no-init option by setting $ENV{IP_EOF}='X' to prevent the
175       paged output from being erased when the pager exits.
176
177   fileno( FILEHANDLE )
178       Return the filehandle number of the write-only pipe to the pager.
179
180   print( FILEHANDLE LIST )
181       print() to the filehandle.
182
183   printf( FILEHANDLE FORMAT, LIST )
184       printf() to the filehandle.
185
186   syswrite( FILEHANDLE, SCALAR, [LENGTH], [OFFSET] )
187       syswrite() to the filehandle.
188

ENVIRONMENT

190       IP_EOF
191           Controls IO:Pager behavior when "eof" is used.
192
193       PAGER
194           The location of the default pager.
195
196       PATH
197           If the location in PAGER is not absolute, PATH may be searched.
198
199           See "NOTES" for more information.
200

FILES

202       IO::Pager may fall back to these binaries in order if PAGER is not
203       executable.
204
205       /etc/alternatives/pager
206       /usr/local/bin/less
207       /usr/bin/less
208       /usr/bin/more
209
210       See "NOTES" for more information.
211

NOTES

213       The algorithm for determining which pager to use is as follows:
214
215       1. Defer to PAGER
216           If the PAGER environment variable is set, use the pager it
217           identifies, unless this pager is not available.
218
219       2. Usual suspects
220           Try the standard, hardcoded paths in "FILES".
221
222       3. File::Which
223           If File::Which is available, use the first pager possible amongst
224           "less", "most", "w3m", "lv", "pg" and more.
225
226       4. Term::Pager
227           If instantiating an IO::Pager object and Term::Pager version 1.5 or
228           greater is available, IO::Pager::Perl will be used. You may also
229           set $ENV{PAGER} to Term::Pager to select this extensible, pure perl
230           pager for display.
231
232       5. more
233           Set PAGER to "more", and cross our fingers.
234
235       Steps 1, 3 and 5 rely upon the PATH environment variable.
236

CAVEATS

238       You probably want to do something with SIGPIPE eg;
239
240         eval {
241           local $SIG{PIPE} = sub { die };
242           local $STDOUT = IO::Pager::open(*STDOUT);
243
244           while (1) {
245             # Do something
246           }
247         }
248
249         # Do something else
250

AUTHOR

256       Jerrad Pierce <jpierce@cpan.org>
257
258       Florent Angly <florent.angly@gmail.com>
259
260       This module was inspired by Monte Mitzelfelt's IO::Page 0.02
261

COPYRIGHT AND LICENSE

263       Copyright (C) 2003-2018 Jerrad Pierce
264
265       ·   Thou shalt not claim ownership of unmodified materials.
266
267       ·   Thou shalt not claim whole ownership of modified materials.
268
269       ·   Thou shalt grant the indemnity of the provider of materials.
270
271       ·   Thou shalt use and dispense freely without other restrictions.
272
273       Or, if you prefer:
274
275       This library is free software; you can redistribute it and/or modify it
276       under the same terms as Perl itself, either Perl version 5.0 or, at
277       your option, any later version of Perl 5 you may have available.
278
279
280
281perl v5.30.0                      2019-09-06                      IO::Pager(3)