REPL.lua - a reusable Lua REPL written in Lua, and an alternative to /usr/bin/lua

This project has two uses:

An alternative to the standalone interpreter included with Lua, one that supports things like plugins, tab completion, and automatic insertion of return in front of expressions.
A REPL library you may embed in your application, to provide all of the niceties of the standalone interpreter included with Lua and then some.

Many software projects have made the choice to embed Lua in their projects to allow their users some extra flexibility. Some of these projects would also like to provide a Lua REPL in their programs for debugging or rapid development. Most Lua programmers are familiar with the standalone Lua interpreter as a Lua REPL; however, it is bound to the command line. Until now, Lua programmers would have to implement their own REPL from scratch if they wanted to include one in their programs. This project aims to provide a REPL implemented in pure Lua that almost any project can make use of.

This library also includes an example application (rep.lua), which serves as an alternative to the standalone interpreter included with Lua. If the lua-linenoise library is installed, it uses linenoise for history and tab completion; otherwise, it tries to use rlwrap for basic line editing. If you would like the arrow keys to work as expected rather than printing things like ^[[A, please install the lua-linenoise library or the rlwrap program.

Project Goals

Provide REPL logic to Lua programs that include this module.
Be extensible through polymorphism and plugins.
Abstract away I/O, so you can run this REPL on the command line or in your own event loop and expect the same behavior.

Building

You need Luadoc (http://keplerproject.github.com/luadoc/) installed to build the documentation.
You need Test.More (http://fperrad.github.com/lua-TestMore/testmore.html) installed to run the tests.

Compatibility

The current version of the software runs on Lua 5.1, LuaJIT ?.? etc. A port to Lua 5.2 is envisaged, but is not at this stage a priority. Since it is written purely in Lua, it should work on any platform that has one of those versions of Lua installed.

XXX Check which version of LuaJIT this works with XXX Check that it works with other Lua interpreters

Installation

You can install lua-repl via LuaRocks:

luarocks install luarepl

You can also install it by hand by copying the repl directory to a location in your package.path, and copying rep.lua to somewhere in your PATH.

Recommended packages

rep.lua works best if you also have linenoise installed, available from https://github.com/hoelzro/lua-linenoise. rep.lua will fallback to using rlwrap if you have that as well; without either of these, you will have command editing, history, or other features generally provided by readline.

Features

rep.lua prints the results of simple expressions without requiring a return or a = in front of it. If linenoise is installed, it also offers persistent history and tab completion. It also offers a number of plugins; see plugins.md for a list of plugins that come with lua-repl.

Backwards Compatibility Changes

Removal of default plugins in 0.8

Lua REPL 0.8 breaks backwards compatability by disabling the loading of the default plugins (currently linenoise, rlwrap, history, completion, and autoreturn) if an rcfile is found for a user. This is so that plugins may not be forced onto a user if they don't want them, or play tricks with their setup (see issue #47). If you would like to continue using these plugins, please put the following code into your ~/.rep.lua:

if repl.VERSION >= 0.8 then
  -- default plugins
  repl:loadplugin 'linenoise'
  repl:loadplugin 'history'
  repl:loadplugin 'completion'
  repl:loadplugin 'autoreturn'
end

-- suppress warning message
repl.quiet_default_plugins = true

As mentioned in the code snippet, repl.quiet_default_plugins suppresses the warning. You can remove this after upgrading to Lua REPL 0.8.

hoelzro / lua-repl