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

NAME

6       IO::Pager::Buffered - Pipe deferred output to PAGER if destination is a
7       TTY
8

SYNOPSIS

10         use IO::Pager::Buffered;
11         {
12           local $token = IO::Pager::Buffered::open local *STDOUT;
13           print <<"  HEREDOC" ;
14           ...
15           A bunch of text later
16           HEREDOC
17         }
18
19         {
20           # You can also use scalar filehandles...
21           my $token = IO::Pager::Buffered::open($FH) or warn($!);
22           print $FH "No globs or barewords for us thanks!\n" while 1;
23         }
24
25         {
26           # ...or an object interface
27           my $token = new IO::Pager::Buffered;
28
29           $token->print("OO shiny...\n") while 1;
30         }
31

DESCRIPTION

33       IO::Pager subclasses are designed to programmatically decide whether or
34       not to pipe a filehandle's output to a program specified in PAGER;
35       determined and set by IO::Pager at runtime if not yet defined.
36
37       This subclass buffers all output for display until execution returns to
38       the parent scope or a manual flush occurs. If this is not what you want
39       look at another subclass such as IO::Pager::Unbuffered. While probably
40       not common, this may be useful in some cases, such as buffering all
41       output to STDOUT while the process occurs so that warnings on STDERR
42       are more visible, then displaying the less urgent output from STDOUT
43       after. Or, alternately, letting output to STDOUT slide by and defer
44       warnings for later perusal.
45

METHODS

47       Class-specific method specifics below, others are inherited from
48       IO::Pager.
49
50   open( [FILEHANDLE] )
51       Instantiate a new IO::Pager to paginate FILEHANDLE if necessary.
52       Assign the return value to a scoped variable. Output does not occur
53       until the filehandle is flushed or closed.
54
55   new( [FILEHANDLE] )
56       Almost identical to open, except that you will get an IO::Handle back
57       if there's no TTY to allow for IO::Pager agnostic programming.
58
59   close( FILEHANDLE )
60       Flushes the buffer to the pager and closes the filehandle for writing.
61       Normally, when using a lexically or locally scoped variable to hold the
62       token supplied by open, explicit calls to close are unnecessary.
63       However, if you are using IO::Pager::Buffered with an unlocalized
64       STDOUT or STDERR you close the filehandle to display the buffered
65       content or wait for global garbage cleaning upon program termination.
66
67       Alternatively, you might prefer to use a non-core filehandle with
68       IO::Pager, and call "select" in perlfunc to make it the default for
69       output.
70
71   tell( FILEHANDLE )
72       Returns the size of the buffer in bytes.
73
74   flush( FILEHANDLE )
75       Immediately flushes the contents of the buffer.
76
77       If the last print did not end with a newline, the text from the
78       preceding newline to the end of the buffer will be flushed but is
79       unlikely to display until a newline is printed and flushed.
80

CAVEATS

82       If you mix buffered and unbuffered operations the output order is
83       unspecified, and will probably differ for a TTY vs. a file. See
84       perlfunc.
85
86       $, is used see perlvar.
87
88       You probably want to do something with SIGPIPE eg;
89
90         eval {
91           local $SIG{PIPE} = sub { die };
92           local $STDOUT = IO::Pager::open(*STDOUT);
93
94           while (1) {
95             # Do something
96           }
97         }
98
99         # Do something else
100

SEE ALSO

102       IO::Pager, IO::Pager::Unbuffered, IO::Pager::Page,
103

AUTHOR

105       Jerrad Pierce <jpierce@cpan.org>
106
107       Florent Angly <florent.angly@gmail.com>
108
109       This module was inspired by Monte Mitzelfelt's IO::Page 0.02
110

112       Copyright (C) 2003-2018 Jerrad Pierce
113
114       •   Thou shalt not claim ownership of unmodified materials.
115
116       •   Thou shalt not claim whole ownership of modified materials.
117
118       •   Thou shalt grant the indemnity of the provider of materials.
119
120       •   Thou shalt use and dispense freely without other restrictions.
121
122       Or, if you prefer:
123
124       This library is free software; you can redistribute it and/or modify it
125       under the same terms as Perl itself, either Perl version 5.0 or, at
126       your option, any later version of Perl 5 you may have available.
127
128
129
130perl v5.36.0                      2023-01-20            IO::Pager::Buffered(3)
Impressum