Debian Codegraph @

upstream/debian-unstable/man3/Term::ReadLine.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Term::ReadLine 3perl"
58 .TH Term::ReadLine 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Term::ReadLine \- Perl interface to various "readline" packages.
65 If no real package is found, substitutes stubs instead of basic functions.
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 10
69 \& use Term::ReadLine;
70 \& my $term = Term::ReadLine\->new(\*(AqSimple Perl calc\*(Aq);
71 \& my $prompt = "Enter your arithmetic expression: ";
72 \& my $OUT = $term\->OUT || \e*STDOUT;
73 \& while ( defined ($_ = $term\->readline($prompt)) ) {
74 \& my $res = eval($_);
75 \& warn $@ if $@;
76 \& print $OUT $res, "\en" unless $@;
77 \& $term\->addhistory($_) if /\eS/;
78 \& }
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 This package is just a front end to some other packages. It's a stub to
83 set up a common interface to the various ReadLine implementations found on
84 CPAN (under the \f(CW\*(C`Term::ReadLine::*\*(C'\fR namespace).
85 .SH "Minimal set of supported functions"
86 .IX Header "Minimal set of supported functions"
87 All the supported functions should be called as methods, i.e., either as
88 .PP
89 .Vb 1
90 \& $term = Term::ReadLine\->new(\*(Aqname\*(Aq);
91 .Ve
92 .PP
93 or as
94 .PP
95 .Vb 1
96 \& $term\->addhistory(\*(Aqrow\*(Aq);
97 .Ve
98 .PP
99 where \f(CW$term\fR is a return value of Term::ReadLine\->\fBnew()\fR.
100 .ie n .IP """ReadLine""" 12
101 .el .IP \f(CWReadLine\fR 12
102 .IX Item "ReadLine"
103 returns the actual package that executes the commands. Among possible
104 values are \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR, \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR,
105 \&\f(CW\*(C`Term::ReadLine::Stub\*(C'\fR.
106 .ie n .IP """new""" 12
107 .el .IP \f(CWnew\fR 12
108 .IX Item "new"
109 returns the handle for subsequent calls to following
110 functions. Argument is the name of the application. Optionally can be
111 followed by two arguments for \f(CW\*(C`IN\*(C'\fR and \f(CW\*(C`OUT\*(C'\fR filehandles. These
112 arguments should be globs.
113 .ie n .IP """readline""" 12
114 .el .IP \f(CWreadline\fR 12
115 .IX Item "readline"
116 gets an input line, \fIpossibly\fR with actual \f(CW\*(C`readline\*(C'\fR
117 support. Trailing newline is removed. Returns \f(CW\*(C`undef\*(C'\fR on \f(CW\*(C`EOF\*(C'\fR.
118 .ie n .IP """addhistory""" 12
119 .el .IP \f(CWaddhistory\fR 12
120 .IX Item "addhistory"
121 adds the line to the history of input, from where it can be used if
122 the actual \f(CW\*(C`readline\*(C'\fR is present.
123 .ie n .IP """IN"", ""OUT""" 12
124 .el .IP "\f(CWIN\fR, \f(CWOUT\fR" 12
125 .IX Item "IN, OUT"
126 return the filehandles for input and output or \f(CW\*(C`undef\*(C'\fR if \f(CW\*(C`readline\*(C'\fR
127 input and output cannot be used for Perl.
128 .ie n .IP """MinLine""" 12
129 .el .IP \f(CWMinLine\fR 12
130 .IX Item "MinLine"
131 If argument is specified, it is an advice on minimal size of line to
132 be included into history. \f(CW\*(C`undef\*(C'\fR means do not include anything into
133 history. Returns the old value.
134 .ie n .IP """findConsole""" 12
135 .el .IP \f(CWfindConsole\fR 12
136 .IX Item "findConsole"
137 returns an array with two strings that give most appropriate names for
138 files for input and output using conventions \f(CW"<$in"\fR, \f(CW">out"\fR.
139 .Sp
140 The strings returned may not be useful for 3\-argument \fBopen()\fR.
141 .IP Attribs 12
142 .IX Item "Attribs"
143 returns a reference to a hash which describes internal configuration
144 of the package. Names of keys in this hash conform to standard
145 conventions with the leading \f(CW\*(C`rl_\*(C'\fR stripped.
146 .ie n .IP """Features""" 12
147 .el .IP \f(CWFeatures\fR 12
148 .IX Item "Features"
149 Returns a reference to a hash with keys being features present in
150 current implementation. Several optional features are used in the
151 minimal interface: \f(CW\*(C`appname\*(C'\fR should be present if the first argument
152 to \f(CW\*(C`new\*(C'\fR is recognized, and \f(CW\*(C`minline\*(C'\fR should be present if
153 \&\f(CW\*(C`MinLine\*(C'\fR method is not dummy. \f(CW\*(C`autohistory\*(C'\fR should be present if
154 lines are put into history automatically (maybe subject to
155 \&\f(CW\*(C`MinLine\*(C'\fR), and \f(CW\*(C`addhistory\*(C'\fR if \f(CW\*(C`addhistory\*(C'\fR method is not dummy.
156 .Sp
157 If \f(CW\*(C`Features\*(C'\fR method reports a feature \f(CW\*(C`attribs\*(C'\fR as present, the
158 method \f(CW\*(C`Attribs\*(C'\fR is not dummy.
159 .SH "Additional supported functions"
160 .IX Header "Additional supported functions"
161 Actually \f(CW\*(C`Term::ReadLine\*(C'\fR can use some other package, that will
162 support a richer set of commands.
163 .PP
164 All these commands are callable via method interface and have names
165 which conform to standard conventions with the leading \f(CW\*(C`rl_\*(C'\fR stripped.
166 .PP
167 The stub package included with the perl distribution allows some
168 additional methods:
169 .ie n .IP """tkRunning""" 12
170 .el .IP \f(CWtkRunning\fR 12
171 .IX Item "tkRunning"
172 makes Tk event loop run when waiting for user input (i.e., during
173 \&\f(CW\*(C`readline\*(C'\fR method).
174 .ie n .IP """event_loop""" 12
175 .el .IP \f(CWevent_loop\fR 12
176 .IX Item "event_loop"
177 Registers call-backs to wait for user input (i.e., during \f(CW\*(C`readline\*(C'\fR
178 method). This supersedes tkRunning.
179 .Sp
180 The first call-back registered is the call back for waiting. It is
181 expected that the callback will call the current event loop until
182 there is something waiting to get on the input filehandle. The parameter
183 passed in is the return value of the second call back.
184 .Sp
185 The second call-back registered is the call back for registration. The
186 input filehandle (often STDIN, but not necessarily) will be passed in.
187 .Sp
188 For example, with AnyEvent:
189 .Sp
190 .Vb 10
191 \& $term\->event_loop(sub {
192 \& my $data = shift;
193 \& $data\->[1] = AE::cv();
194 \& $data\->[1]\->recv();
195 \& }, sub {
196 \& my $fh = shift;
197 \& my $data = [];
198 \& $data\->[0] = AE::io($fh, 0, sub { $data\->[1]\->send() });
199 \& $data;
200 \& });
201 .Ve
202 .Sp
203 The second call-back is optional if the call back is registered prior to
204 the call to \f(CW$term\fR\->readline.
205 .Sp
206 Deregistration is done in this case by calling event_loop with \f(CW\*(C`undef\*(C'\fR
207 as its parameter:
208 .Sp
209 .Vb 1
210 \& $term\->event_loop(undef);
211 .Ve
212 .Sp
213 This will cause the data array ref to be removed, allowing normal garbage
214 collection to clean it up. With AnyEvent, that will cause \f(CW$data\fR\->[0] to
215 be cleaned up, and AnyEvent will automatically cancel the watcher at that
216 time. If another loop requires more than that to clean up a file watcher,
217 that will be up to the caller to handle.
218 .ie n .IP """ornaments""" 12
219 .el .IP \f(CWornaments\fR 12
220 .IX Item "ornaments"
221 makes the command line stand out by using termcap data. The argument
222 to \f(CW\*(C`ornaments\*(C'\fR should be 0, 1, or a string of a form
223 \&\f(CW"aa,bb,cc,dd"\fR. Four components of this string should be names of
224 \&\fIterminal capacities\fR, first two will be issued to make the prompt
225 standout, last two to make the input line standout.
226 .ie n .IP """newTTY""" 12
227 .el .IP \f(CWnewTTY\fR 12
228 .IX Item "newTTY"
229 takes two arguments which are input filehandle and output filehandle.
230 Switches to use these filehandles.
231 .PP
232 One can check whether the currently loaded ReadLine package supports
233 these methods by checking for corresponding \f(CW\*(C`Features\*(C'\fR.
234 .SH EXPORTS
235 .IX Header "EXPORTS"
236 None
237 .SH ENVIRONMENT
238 .IX Header "ENVIRONMENT"
239 The environment variable \f(CW\*(C`PERL_RL\*(C'\fR governs which ReadLine clone is
240 loaded. If the value is false, a dummy interface is used. If the value
241 is true, it should be tail of the name of the package to use, such as
242 \&\f(CW\*(C`Perl\*(C'\fR or \f(CW\*(C`Gnu\*(C'\fR.
243 .PP
244 As a special case, if the value of this variable is space-separated,
245 the tail might be used to disable the ornaments by setting the tail to
246 be \f(CW\*(C`o=0\*(C'\fR or \f(CW\*(C`ornaments=0\*(C'\fR. The head should be as described above, say
247 .PP
248 If the variable is not set, or if the head of space-separated list is
249 empty, the best available package is loaded.
250 .PP
251 .Vb 2
252 \& export "PERL_RL=Perl o=0" # Use Perl ReadLine sans ornaments
253 \& export "PERL_RL= o=0" # Use best available ReadLine sans ornaments
254 .Ve
255 .PP
256 (Note that processing of \f(CW\*(C`PERL_RL\*(C'\fR for ornaments is in the discretion of the
257 particular used \f(CW\*(C`Term::ReadLine::*\*(C'\fR package).