Including

lua-readline isn't more difficult to attach to your Lua program than any other Lua library is:

local readline = require "readline"

readline.readline()

The main API function of the lua-readline library is surprisingly called readline. It's signature is:

readline.readline(prompt, generator)

where:

• prompt is a string prompt displayed before the user input. Compare with native readline()'s prompt argument.
• generator is a function or a table to be used for word completion. This functions returns:
• A string on success
• nil on EOF

Generator

While native readline()'s completion uses a single generator function (supplied via rl_completion_entry_function global variable), lua-readline uses two kinds of them:

• Generator function
• Iterator function

The generator function

The generator function is called once for each completion request. It is intended to create an iterator that will allow readline() to enumerate all possible completions. Its signature is:

generator(prefix)

where:

• prefix is the part of word that the user has already typed in The generator function must return an iterator function.

The iterator function

The iterator function is called to request one possible completion suggestion. Its signature is:

iterator()

It accepts no parameters, so it's more likely a closure than a function. It must return:

• A string - the next completion suggestion if there are any more suggestions left
• nil otherwise

Simple completion

As mentioned above, it's possible to supply a table in place of the generator function. In this case lua-readline creates its own generator function with the following semantics: it enumerates all the strings in the table (like ipairs() does - morover, it actually calls ipairs() to do that!), eliminates the strings that don't start with the typed in prefix and returns them as completion suggestions one by one. This allows the developer not to care about generators and supply a list of possible words in advance.

History support

lua-readline uses GNU History library for history support. The current version of lua-readline has only one history-related function:

readline.addhistory(line)

where:

• line is a string to store in the history.

Application name

libreadline has application-dependent configuration facilities in inputrc files. So it has to know the application name in some way. The function provided for this is:

readline.setname(name)

where:

• name - A string, the name of the application to set Returns nothing. It's also possible to get the application name previously set by calling:

readline.getname()

Returns a string representing the previously set name.