readline.lua

NAME
SYNOPSIS

DESCRIPTION
FUNCTIONS

DOWNLOAD
CHANGES

AUTHOR
SEE ALSO

NAME

readline - a simple interface to the readline and history libraries

SYNOPSIS

 local RL = require 'readline'
 -- see: man readline
 RL.set_options{ keeplines=1000, histfile='~/.synopsis_history' }
 local str = RL.readline('Please enter some filename: ')
 local save_options = RL.set_options{ completion=false }
 str = RL.readline('Please type a line which can include Tabs: ')
 RL.set_options(save_options)
 str = RL.readline('Now tab-filename-completion is working again: ')
 ...
 RL.save_history() ; os.exit()

DESCRIPTION

This Lua module offers a simple calling interface to the GNU Readline/History Library.

The function readline() is a wrapper, which invokes the GNU readline, adds the line to the end of the History List, and then returns the line. Usually you call save_history() before the program exits, so that the History List is saved to the histfile.

Various options can be changed using the set_options{} function.

The user can configure the GNU Readline (e.g. vi or emacs keystrokes ?) with their individual ~/.inputrc file, see the INITIALIZATION FILE section of man readline.

By default, the GNU readline library dialogues with the user by reading from stdin and writing to stdout; this fits badly with applications that want to use stdin and stdout to input and output data. Therefore, this Lua module dialogues with the user on the controlling-terminal of the process (typically /dev/tty) as returned by ctermid().

FUNCTIONS

RL.set_options{ histfile='~/.myapp_history', keeplines=100 }

Returns the old options, so they can be restored later. The auto_add option controls whether the line entered will be added to the History List, The default options are:

 auto_add   = true,
 histfile   = '~/.rl_lua_history',
 keeplines  = 500,
 completion = true,
 ignoredups = true,
 minlength  = 2,

Lines shorter than the minlength option will not be put on the History List. Tilde expansion is performed on the histfile option. The histfile option must be a string, so don't set it to nil, if you want to avoid reading or writing your History List to the filesystem, set histfile to the empty string. If you want no history behaviour (Up or Down arrows etc.) at all, then set

 set_options{ histfile='', auto_add=false, }

RL.readline( prompt )

Displays the prompt 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, nil is returned; if an EOF is read with a non-empty line, it is treated as a newline.

If the auto_add option is true (which is the default), the line the user enters will be added to the History List, unless it's shorter than minlength, or it's the same as the previous line and the ignoredups option is set.

RL.save_history()

Normally, you should call this function before your program exits. It saves the lines the user has entered onto the end of the histfile file. Then if necessary it truncates lines off the beginning of the histfile to confine it to keeplines long.

RL.add_history( line )

Adds the line to the History List. You'll only need this function if you want to assume complete control over the strings that get added, in which case you:

 RL.set_options{ auto_add=false, }

and then after calling readline(prompt) you can process the line as you wish and call add_history(line) if appropriate.

DOWNLOAD

This module is available as a LuaRock in rocks.moonscript.org/modules/peterbillam so you should be able to install it with the command:

 $ su
 Password:
 # luarocks install --server=http://rocks.moonscript.org readline

or:

 # luarocks install http://www.pjb.com.au/comp/lua/readline-1.5-0.rockspec

It depends on the readline library and its header-files; for example on Debian you may need:
# aptitude install libreadline6 libreadline6-dev

or on Centos you may need:
# yum install readline-devel

CHANGES

 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

AUTHOR

Peter Billam, http://www.pjb.com.au/comp/contact.html