File: readline.html

package info (click to toggle)
lua-readline 3.3-3
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 124 kB
sloc: ansic: 251; makefile: 4
file content (474 lines) | stat: -rw-r--r-- 19,192 bytes
<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 with <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.
So 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-3.2-0.rockspec
</CODE>
</P><p>
If this results in an error message such as:<BR>
<CODE>
 &nbsp; Error: Could not find expected file libreadline.a, or libreadline.so,<BR></CODE>
then you need to find the appropriate directory with:<BR><CODE>
 &nbsp; find /usr/lib -name 'libreadline.*' -print</CODE><BR>
and then invoke:<BR><CODE>
 &nbsp; luarocks install readline\<BR>
 &nbsp; READLINE_INCDIR=/usr/local/Cellar/readline/8.1/include \<BR>
 &nbsp; READLINE_LIBDIR=/usr/local/Cellar/readline/8.1/lib \<BR>
 &nbsp; HISTORY_INCDIR=/usr/local/Cellar/readline/8.1/include \<BR>
 &nbsp; HISTORY_LIBDIR=/usr/local/Cellar/readline/8.1/lib # or wherever</CODE><BR>
accordingly.
</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-3.2.tar.gz</CODE>
</P>
<hr />
<h2><a name="changes">CHANGES</a></h2>
<pre>
 20221001 3.2 fix a memory leak in readline()
 20220420 3.1 reset OldHistoryLength if histfile gets set
 20210418 3.0 pass READLINE_INCDIR and READLINE_LIBDIR to gcc
 20210127 2.9 fix version number again
 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,<BR>
wenxichang fixed the memory leak in
<A HREF="#readline">readline()</A>.
</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>