C<readline> - a simple interface to the I<readline> and I<history> libraries

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS

RL.set_options{ histfile='~/.myapp_history', keeplines=100 }
RL.readline( prompt )
RL.save_history()
RL.add_history( line )

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_option(save_options)
 str = RL.readline('Now tab-filename-completion is working again: ')
 ...
 PL.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.

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 luarocks.org/repositories/rocks so you should be able to install it with the command:

 $ su
 Password:
 # luarocks install readline

or:

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

It depends on readline library and its header-files; for example, on Debian you will need:

 # aptitude install libreadline6 libreadline6-dev

CHANGES

 20130918 1.0 first working version

AUTHOR

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