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");
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";
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   eof( FILEHANDLE )
136       Used in the eval-until-eof idiom below, IO::Pager will handle broken
137       pipes from deceased children for you in one of two ways. If
138       $ENV{IP_EOF} is false then program flow will pass out of the loop on
139       SIGPIPE, this is the default. If the variable is true, then the program
140       continues running with output for the previously paged filehandle
141       directed to the STDOUT stream; more accurately, the filehandle is
142       reopened to file descriptor 1.
143
144         use IO::Pager::Page; #or whichever you prefer;
145         ...
146         eval{
147           say "Producing prodigious portions of product";
148           ...
149         } until( eof(*STDOUT) );
150         print "Cleaning up after our child before terminating."
151
152       If using eof() with less, especially when IP_EOF is set, you may want
153       to use the --no-init option by setting $ENV{IP_EOF}='X' to prevent the
154       paged output from being erased when the pager exits.
155
156   print( FILEHANDLE LIST )
157       print() to the filehandle.
158
159   printf( FILEHANDLE FORMAT, LIST )
160       printf() to the filehandle.
161
162   syswrite( FILEHANDLE, SCALAR, [LENGTH], [OFFSET] )
163       syswrite() to the filehandle.
164

ENVIRONMENT

166       IP_EOF
167           Controls IO:Pager behavior when "eof" is used.
168
169       PAGER
170           The location of the default pager.
171
172       PATH
173           If the location in PAGER is not absolute, PATH may be searched.
174
175           See "NOTES" for more information.
176

FILES

178       IO::Pager may fall back to these binaries in order if PAGER is not
179       executable.
180
181       /etc/alternatives/pager
182       /usr/local/bin/less
183       /usr/bin/less
184       /usr/bin/more
185
186       See "NOTES" for more information.
187

NOTES

189       The algorithm for determining which pager to use is as follows:
190
191       1. Defer to PAGER
192           If the PAGER environment variable is set, use the pager it
193           identifies, unless this pager is not available.
194
195       2. Usual suspects
196           Try the standard, hardcoded paths in "FILES".
197
198       3. File::Which
199           If File::Which is available, use the first pager possible amongst
200           "less", "most", "w3m", "lv", "pg" and more.
201
202       4. more
203           Set PAGER to "more", and cross our fingers.
204
205       Steps 1, 3 and 4 rely upon the PATH environment variable.
206

AUTHOR

213       Jerrad Pierce <jpierce@cpan.org>
214
215       Florent Angly <florent.angly@gmail.com>
216
217       This module was inspired by Monte Mitzelfelt's IO::Page 0.02
218

COPYRIGHT AND LICENSE

220       Copyright (C) 2003-2015 Jerrad Pierce
221
222       ·   Thou shalt not claim ownership of unmodified materials.
223
224       ·   Thou shalt not claim whole ownership of modified materials.
225
226       ·   Thou shalt grant the indemnity of the provider of materials.
227
228       ·   Thou shalt use and dispense freely without other restrictions.
229
230       Or, if you prefer:
231
232       This library is free software; you can redistribute it and/or modify it
233       under the same terms as Perl itself, either Perl version 5.0 or, at
234       your option, any later version of Perl 5 you may have available.
235
236
237
238perl v5.28.0                      2017-05-13                      IO::Pager(3)