Fennel wiki: Readline

The command-line REPL that comes with the fennel script works out of the box, but the built-in line-reader is very limited in user experience. Adding GNU Readline support enables user-friendly features, such as:

Requirements for readline support

The best way to get readline.lua is to install it with your system's package manager, but if you can't do that you can use LuaRocks, which will fetch the package and automatically compile the native bindings for you.

Note: The Fennel REPL will automatically load and use the readline bindings when it can resolve the readline module, so that's all you need to get started.

Installing readline.lua with LuaRocks

To install readline.lua with LuaRocks:

  1. Ensure libreadline is installed.
  2. Run one of the following commands:
    • luarocks install --local readline (recommended)
    • luarocks install --lua-version=5.1 readline (for a non-default Lua version)
    • luarocks install readline (requires root or admin)

Note: If you've installed with the --local flag, you may need to ensure your package.path and package.cpath contain its location.

Configuring readline.lua

You can configure readline.lua using one of the following options:

If you have readline installed but do not wish to use it (for example, running Fennel inside an Emacs shell or recording a session to a file) you can export TERM=dumb as an environment variable.

Enabling persistent history using fennelrc

To configure the REPL to save the rolling history to file at the end of every session, add the following to your ~/.fennelrc with your desired filename:

See the readline.lua documentation for information on its API, most notably other parameters that can be set via rl.set_options.

;; persist repl history
(case package.loaded.readline
  rl   (rl.set_options {:histfile  "~/.fennel_history" ; default:"" (don't save)
                        :keeplines 1000}))             ; default:1000

Configuring readline in ~/.inputrc

See the documentation on the readline init file for the full set of options and a sample inputrc.

The following example adds these behaviors:

Create a ~/.inputrc file with the following contents:

set enable-bracketed-paste on
set blink-matching-paren on
set show-all-if-ambiguous on

You can make use of a conditional directive your inputrc if you would like certain settings to only apply to Fennel.