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       IO::Pager::Perl as "tp" via IO::Pager::less
209       /usr/bin/more
210
211       See "NOTES" for more information.
212

NOTES

214       The algorithm for determining which pager to use is as follows:
215
216       1. Defer to PAGER
217           If the PAGER environment variable is set, use the pager it
218           identifies, unless this pager is not available.
219
220       2. Usual suspects
221           Try the standard, hardcoded paths in "FILES".
222
223       3. File::Which
224           If File::Which is available, use the first pager possible amongst
225           "less", "most", "w3m", "lv", "pg" and more.
226
227       4. Term::Pager via IO::Pager::Perl
228       5. more
229           Set PAGER to "more", and cross our fingers.
230
231       Steps 1, 3 and 5 rely upon the PATH environment variable.
232

CAVEATS

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

AUTHOR

252       Jerrad Pierce <jpierce@cpan.org>
253
254       Florent Angly <florent.angly@gmail.com>
255
256       This module was inspired by Monte Mitzelfelt's IO::Page 0.02
257

COPYRIGHT AND LICENSE

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

POD ERRORS

276       Hey! The above document had some coding errors, which are explained
277       below:
278
279       Around line 551:
280           =pod directives shouldn't be over one line long!  Ignoring all 3
281           lines of content
282
283
284
285perl v5.30.1                      2020-01-30                      IO::Pager(3)