You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
4.0 KiB
102 lines
4.0 KiB
# 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`:
|
|
|
|
```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.
|
|
|