File: readline.html

package info (click to toggle)
lua-readline 2.9-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 112 kB
  • sloc: ansic: 253; makefile: 4
file content (456 lines) | stat: -rw-r--r-- 18,267 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
<HTML><HEAD><TITLE>readline.lua</TITLE>
<LINK rel=stylesheet type="text/css"
href="../styles.css" title="PJB Computing Styles">
<META HTTP-EQUIV="Keywords"
CONTENT="readline, history, Lua, module, luarocks">
</HEAD>
<BODY LINK="#000066" VLINK="#000066" ALINK="#000066">
<DIV>
<H1><IMG SRC="../logo.jpg" ALT=" " WIDTH=126 HEIGHT=52>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<FONT COLOR="#800000"><I>readline.lua</I></FONT>
</H1>

<!-- INDEX BEGIN -->
<A NAME="index"></A>

<TABLE ALIGN="center" WIDTH="85%" BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left">
<ul>
    <li><a href="#name">NAME</a></li>
    <li><a href="#synopsis">SYNOPSIS</a></li>
    <li><a href="#description">DESCRIPTION</a></li>
</ul>
</TD><TD ALIGN="left">
<ul>
    <li><a href="#functions">STANDARD INTERFACE</a></li>
    <li><a href="#alternate">ALTERNATE INTERFACE</a></li>
    <li><a href="#custom">CUSTOM COMPLETION</a></li>
</ul>
</TD><TD ALIGN="left">
<ul>
    <li><a href="#installation">INSTALLATION</a></li>
    <li><a href="#changes">CHANGES</a></li>
</ul>
</TD><TD ALIGN="left">
<ul>
    <li><a href="#authors">AUTHORS</a></li>
    <li><a href="#see_also">SEE ALSO</a></li>
</ul>
</TD></TR></TABLE>

<!-- INDEX END -->

<p>
</p>
<hr />
<h2><a name="name">NAME</a></h2>
<p><code>readline</code> - a simple interface
to the <em>readline</em> and <em>history</em> libraries</p>
<p>
</p>
<hr />
<h2><a name="synopsis">SYNOPSIS</a></h2>
<pre>
 local RL = require 'readline'
 RL<A HREF="#set_options">.set_options</A>{ keeplines=1000, histfile='~/.synopsis_history' }
 RL<A HREF="#set_readline_name">.set_readline_name</A>('fennel')

-- the <A HREF="#standard">Standard Interface</A>
 local str = RL<A HREF="#readline">.readline</A>('Please enter some filename: ')</A>
 local save_options = RL<A HREF="#set_options">.set_options</A>{ completion=false }
 str = RL<A HREF="#readline">.readline</A>('Please type a line which can include Tabs: ')
 RL<A HREF="#set_options">.set_options</A>(save_options)
 str = RL<A HREF="#readline">.readline</A>('Now tab-filename-completion is working again: ')
 ...

 -- the <A HREF="#alternate">Alternate Interface</A>
 local poll = require 'posix.poll'.poll
 local line = nil
 local linehandler = function (str)
    RL<A HREF="#add_history">.add_history(str)</A>
    RL<A HREF="#handler_remove">.handler_remove()</A>
    line = str
 end
 RL<A HREF="#handler_install">.handler_install</A>("prompt&gt; ", linehandler)
 local fds = {[0] = {events={IN={true}}}}
 while true do
    poll(fds, -1)
    if fds[0].revents.IN then
       RL<A HREF="#read_char">.read_char()</A>  -- only if there's something to be read
    else
       -- do some useful background task
    end
    if line then break end
 end
 print("got line: " .. line)

 -- <A HREF="#custom">Custom Completion</A>
 local reserved_words = {
   'and', 'assert', 'break', 'do', 'else', 'elseif', 'end', 'false',
   'for', 'function', 'if', 'ipairs', 'local', 'nil', 'not', 'pairs',
   'print', 'require', 'return', 'then', 'tonumber', 'tostring',
   'true', 'type', 'while',
 }
 RL<A HREF="#set_complete_list">.set_complete_list</A>(reserved_words)
 line = RL.readline('now it expands lua reserved words: ')

 ...
 RL<A HREF="#save_history">.save_history()</A> ; os.exit()
</pre>
<p>
</p>
<hr />
<h2><a name="description">DESCRIPTION</a></h2>
<p>This Lua module offers a simple calling interface
to the GNU Readline/History Library.
</p><p>
The function
<em><A HREF="#readline">readline()</A></em>
is a wrapper, which invokes the GNU
<em>readline</em>, adds the line to the end of the History List,
and then returns the line.  Usually you call
<em><A HREF="#save_history">save_history()</A></em>
before the program exits,
so that the History List is saved to the <em>histfile</em>.
</p><p>
Various options can be changed using the
<em><A HREF="#set_options">set_options{}</A></em>
function.
</p><p>
The user can configure the GNU Readline
(e.g. <em>vi</em> or <em>emacs</em> keystrokes ?)
with their individual <em>~/.inputrc</em> file,
see the <em>INITIALIZATION FILE</em> section of <em>man readline</em>.</p>
</p><p>
By default, the GNU <I>readline</I> library dialogues with the user
by reading from <I>stdin</I> and writing to <I>stdout</I>;
this fits very badly with applications that want to
use <I>stdin</I> and <I>stdout</I> to input and output data.
Therefore, this Lua module dialogues with the user on the controlling-terminal
of the process (typically <I>/dev/tty</I>) as returned by <I>ctermid()</I>.
</P><P>
Most of
<A HREF="https://tiswww.case.edu/php/chet/readline/readline.html#SEC41">
readline's Alternate Interface</A> is now included, namely &nbsp;
<A HREF="#handler_install">handler_install</A>, &nbsp;
<A HREF="#read_char">read_char</A> &nbsp;
and
<A HREF="#handler_remove">handler_remove</A>.<BR>
Some applications need to interleave keyboard I/O with file, device,
or window system I/O, typically by using a main loop to <I>select()</I> on
various file descriptors.
&nbsp; To accommodate this need, <I>readline</I>
can also be invoked as a 'callback' function from an event loop,
and the <I>Alternate Interface</I> offers functions to do this.<BR>
The <I>Alternate Interface</I> does offer tab-completion; but it does not
add to the history file, so you will probably want to call
<CODE>RL.add_history(s)</CODE> explicitly.
See <A HREF="#handler_install">handler_install()</A>
</P><P>
Access to <I>readline</I>'s
<A HREF="#custom">Custom Completion</A>
is now provided.
</P><P>
This module does not work <CODE>lua -i</CODE>
because that runs its own <I>readline</I>,
and the two conflict with each other.
</P>

<a name="functions"><hr /></A>
<h2><a name="standard">STANDARD INTERFACE</a></h2>
<p>
</p>

<h3><a name="set_options">RL.set_options{ histfile='~/.myapp_history', keeplines=100 }</a></h3>
<p>Returns the old options, so they can be restored later.
The <em>auto_add</em> option controls whether the line entered will be
added to the History List,
The default options are:<BR><CODE>
 &nbsp; auto_add   = true,<BR>
 &nbsp; histfile   = '~/.rl_lua_history',<BR>
 &nbsp; keeplines  = 500,<BR>
 &nbsp; completion = true,<BR>
 &nbsp; ignoredups = true,<BR>
 &nbsp; minlength  = 2,</CODE><BR>
<p>Lines shorter than the <em>minlength</em> option will not be put on the
History List.  Tilde expansion is performed on the <em>histfile</em> option.
The <em>histfile</em> option must be a string, so don't set it to <em>nil</em>,
if you want to avoid reading or writing your History List to the filesystem,
set <em>histfile</em> to the empty string.
If you want no history behaviour (Up or Down arrows etc.) at all, then set
<BR><CODE>
 &nbsp; set_options{ histfile='', auto_add=false, }</CODE><BR>

<h3><a name="set_readline_name">RL.set_readline_name( 'myapp' )</a></h3>
<p>
Sets the internal libreadline variable <I>rl_readline_name</I>
for use with conditional directives in <CODE>.inputrc</CODE>
(see the
<A HREF="https://tiswww.cwru.edu/php/chet/readline/readline.html">manual</A>).
<BR>It should be
invoked once, before calling <CODE>readline()</CODE>,
so that the name is set before <CODE>.inputrc</CODE> is sourced.
<BR>
For example: if, in the initialization before first readline prompt, you
<BR><CODE>
 &nbsp; RL.set_readline_name('<A HREF="https://fennel-lang.org/">fennel</A>')</CODE>
<BR><BR>
then the call to <CODE>readline()</CODE>
would execute this conditional in <CODE>.inputrc</CODE><BR>
<CODE> &nbsp; $if <A HREF="https://fennel-lang.org/">fennel</A><BR>
 &nbsp; &nbsp; set blink-matching-paren On<BR>
 &nbsp; &nbsp; set enable-bracketed-paste On<BR>
 &nbsp; $endif
</CODE>
</p>

<h3><a name="readline">RL.readline( prompt )</a></h3>
<p>Displays the <em>prompt</em> and returns the text of the line the
user enters.  A blank line returns the empty string.
If EOF is encountered while reading a line, and the line is empty,
<em>nil</em> is returned;
if an EOF is read with a non-empty line, it is treated as a newline.</p>
<p>If the <em>auto_add</em> option is <em>true</em> (which is the default),
the line the user enters will be added to the History List,
unless it's shorter than <em>minlength</em>, or it's the same
as the previous line and the <em>ignoredups</em> option is set.</p>
<p>
</p>
<h3><a name="save_history">RL.save_history()</a></h3>
<p>Normally, you should call this function once, just before your program
exits.
It saves the lines the user has entered onto the end of the <em>histfile</em>
file.  Then if necessary it truncates lines off the beginning of the
<em>histfile</em> to confine it to <em>keeplines</em> long.</p>
<p>
</p>
<h3><a name="add_history">RL.add_history( line )</a></h3>
<p>Adds the <em>line</em> to the History List.<BR>
With the Standard Interface, you'll only need this function
if you want to assume complete control over the strings that get added,
in which case you set:
<BR><CODE> &nbsp;
 RL.set_options{ auto_add=false, }</CODE><BR>
and then after calling <em>readline(prompt)</em>
you can process the <em>line</em> as you wish
and call <em>add_history(line)</em> if appropriate.
</p><P>
But with the Alternative Interface, you have to call
<em>add_history(line)</em> yourself, even if <I>{auto_add=true}</I><BR>
You should do this in the linehandler function, see below.

</P>
<h2><a name="alternate">ALTERNATE INTERFACE</a></h2><P>
Some applications need to interleave keyboard I/O with file, device,
or window system I/O, by using a main loop to <I>select()</I> on
various file descriptors.
<BR>With the Alernate Interface, readline can
be invoked as a 'callback' function from an event loop.
</P><P>
The Alternate Interface does not add to the history file,
so you will probably want to call
RL.<A HREF="#add_history">add_history(s)</A> explicitly.<BR>
<B>You should do this within the linehandler function !</B><BR>
(This constraint is due to what may be an unadvertised quirk
of <I>libreadline</I>.)
</P>

<h3><a name="handler_install">RL.handler_install( prompt, linehandlerfunction )</a></h3>
<p>
This function sets up the terminal, installs a linehandler function
that will receive the text of the line as an argument,
and displays the string <B>prompt</B>. &nbsp;
A typical linehandler function might be:<BR><CODE>
&nbsp; linehandler = function (str) <BR>
&nbsp; &nbsp; RL.add_history(str)<BR>
&nbsp; &nbsp; RL.handler_remove()<BR>
&nbsp; &nbsp; line = str &nbsp; -- line is a global, or an upvalue<BR>
&nbsp; end<BR>
</CODE>

</p>

<h3><a name="read_char">RL.read_char()</a></h3>
<p>
Whenever an application determines that keyboard input is available,
it should call <I>read_char()</I>,
which will read the next character from the current input source.
If that character completes the line, <I>read_char</I> will invoke the
linehandler function installed by <I>handler_install</I> to process the line.
<BR>
Before calling the linehandler function, the terminal settings are reset to
the values they had before calling <I>handler_install</I>.
If the linehandler function returns, and the line handler remains installed,
the terminal settings are modified for Readline's use again.
EOF is indicated by calling the linehandler handler with a <B>nil</B> line.
</p>

<h3><a name="handler_remove">RL.handler_remove()</a></h3>
<p>
Restore the terminal to its initial state and remove the line handler.
You may call this function from within the linehandler as well as independently.
If the linehandler function does not exit the program,
this function should be called before the program exits
to reset the terminal settings.
</p>

<h2><a name="custom">CUSTOM COMPLETION</a></h2>

<h3><a name="set_complete_list">RL.set_complete_list( array_of_strings )</a></h3>
<p>
This function sets up custom completion of an array of strings.
<BR>
For example, the <I>array_of_strings</I>
might be the dictionary-words of a language,
or the reserved words of a programming language.
</p>

<h3><a name="set_complete_function">RL.set_complete_function( completer_function )</a></h3>
<p>
This is the lower-level function on which
<A HREF="set_complete_list">set_complete_list()</A> is based.
Its argument is a function which takes three arguments:
the <B>text</B> of the line as it stands,
and the indexes  <B>from</B> and <B>to</B>,
which delimit the segment of the text (for example, the <I>word</I>)
which is to be completed.
This syntax is the same as <I>string.sub(text, from, to)</I>
<BR>
The <I>completer_function</I> must return an array of the possible
completions.
<BR>
For example, the <I>completer_function</I> of
<A HREF="set_complete_list">set_complete_list()</A> is:
<PRE>  local completer_function = function(text, from, to)
     local incomplete = string.sub(text, from, to)
     local matches = {}
     for i,v in ipairs(array_of_strings) do
        if incomplete == string.sub(v, 1, #incomplete) then
           matches[1 + #matches] = v
        end
     end
     return matches
  end
</PRE>
but the <I>completer_function</I> can also have more complex behaviour.
Because it knows the contents of the line so far,
it could ask for a date in format <B>18 Aug 2018</B>
and offer three different completions for the three different fields.<BR>
Or if the line so far seems to be in
<A HREF="../../esperanto/index.html">Esperanto</A>
it could offer completions in Esperanto, and so on.
</p><p>
By default, after every completion <I>readline</I> appends a space
to the string, so you can start the next word.
You can change this space to another character by calling
<I>set_completion_append_character(s)</I>,
which sets the <I>append_character</I>
to the first byte of the string <B>s</B>.
For example, this sets it to the empty string:<BR>
<CODE> &nbsp; RL.set_completion_append_character('')</CODE><BR>
It only makes sense to call <I>set_completion_append_character</I>
from within a <I>completer_function</I>.<BR>
After the <I>completer_function</I> has executed,
the <I>readline</I> library resets the <I>append_character</I> to the default space.
<BR>
Setting the <I>append_character</I> to
<CODE>','</CODE> or
<CODE>':'</CODE> or
<CODE>'.'</CODE> or
<CODE>'-'</CODE>
may not behave as you expect when trying to tab-complete the
following word, because <I>readline</I> treats those characters
as being part of a 'word', not as a delimiter between words.
</p>
<p>
</p>
<hr />
<h2><a name="installation">INSTALLATION</a></h2>
<p>This module is available as a LuaRock in
<A HREF="http://luarocks.org/modules/peterbillam">
luarocks.org/modules/peterbillam</A>
so you should be able to install it with the command:<BR><CODE>
 &nbsp; $ su<BR>
 &nbsp; Password:<BR>
 &nbsp; # luarocks install readline</CODE>
</p><p>
or:<BR><CODE>
&nbsp; # luarocks install https://pjb.com.au/comp/lua/readline-2.8-0.rockspec
</CODE>
</P><p>
It depends on the <em>readline</em> library and its header-files;
for example on Debian you may need:<BR>
<CODE> &nbsp; # aptitude install libreadline6 libreadline6-dev</CODE>
</P><P>
or on Centos you may need:<BR>
<CODE> &nbsp; # yum install readline-devel</CODE></P>
</P><P>
You can see the source-code in:<BR>
<CODE> &nbsp; https://pjb.com.au/comp/lua/readline-2.8.tar.gz</CODE>
</P>
<hr />
<h2><a name="changes">CHANGES</a></h2>
<pre>
 20210106 2.8 include string.h
 20200801 2.7 add lua 5.4
 20200409 2.6 jaawerth: added set_readline_name()
 20190110 2.5 fix a lua_rawlen v. lua_objlen bug if using lua 5.1
 20180924 2.2 add set_completion_append_character
 20180912 2.1 C code stack-bug fix in handler_calls_completion_callback
 20180910 2.0 add set_complete_list and set_complete_function
 20180827 1.9 add handler_install read_char and handler_remove
 20151020 1.8 readline() returns nil correctly on EOF
 20150421 1.7 include lua5.3, and move pod and doc back to luarocks.org
 20150416 1.6 readline specified as an external dependency
 20140608 1.5 switch pod and doc over to using moonrocks
 20140519 1.4 installs as readline not Readline under luarocks 2.1.2
 20131031 1.3 readline erases final space if tab-completion is used
 20131020 1.2 set_options{histfile='~/d'} expands the tilde
 20130921 1.1 uses ctermid() (usually /dev/tty) to dialogue with the user
 20130918 1.0 first working version</pre>
<p>
</p>
<hr />
<h2><a name="authors">AUTHORS</a></h2>
<p>Peter Billam &nbsp;
<a href="../contact.html">https://pjb.com.au/comp/contact.html</a><BR>
Alexander Adler, University of Frankfurt, contributed the
<A HREF="#alternate">Alternate Interface</A> and
<A HREF="#custom">Custom Completion</A><BR>
Jesse Wertheim, one of the developers of
<A HREF="https://fennel-lang.org/">Fennel</A>,
contributed the
<A HREF="#set_readline_name">set_readline_name()</A> function.</p>
<p>
</p>
<hr />
<h2><a name="see_also">SEE ALSO</a></h2>
<!--
 <a href="http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html">http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html</a>
 <a href="http://cnswww.cns.cwru.edu/php/chet/readline/readline.html">http://cnswww.cns.cwru.edu/php/chet/readline/readline.html</a>
 <a href="http://cnswww.cns.cwru.edu/php/chet/readline/history.html">http://cnswww.cns.cwru.edu/php/chet/readline/history.html</a>
-->
<P>
 man readline &nbsp;
 <a href="http://www.gnu.org/s/readline">http://www.gnu.org/s/readline</a><BR>
 <A HREF="https://tiswww.case.edu/php/chet/readline/readline.html">https://tiswww.case.edu/php/chet/readline/readline.html</A><BR>
<A HREF="https://tiswww.case.edu/php/chet/readline/readline.html#SEC28">
https://tiswww.case.edu/php/chet/readline/readline.html#SEC28</A>
&nbsp; Readline Variables <BR>
 <A HREF="https://tiswww.case.edu/php/chet/readline/readline.html#SEC41">https://tiswww.case.edu/php/chet/readline/readline.html#SEC41</A><BR>
 <A HREF="https://tiswww.case.edu/php/chet/readline/readline.html#SEC45">https://tiswww.case.edu/php/chet/readline/readline.html#SEC45</A><BR>
 <a href="file:/usr/share/readline/inputrc">/usr/share/readline/inputrc</A>
 &nbsp; ~/.inputrc<BR>
 <a href="http://lua-users.org/wiki/CompleteWithReadline">http://lua-users.org/wiki/CompleteWithReadline</a><BR>
 <A HREF="http://luaposix.github.io/luaposix">http://luaposix.github.io/luaposix</A><BR>
 <A HREF="https://fennel-lang.org/">fennel-lang.org/</A><BR>
 <a href="terminfo.html">terminfo.lua</a><BR>
 <a href="../../index.html">https://pjb.com.au</a><BR>
 <a href="../index.html#lua">https://pjb.com.au/comp/index.html#lua</a>
</P>

</DIV>
</body>

</html>