Welcome to Rebel Readline – the snazzy terminal REPL for Clojure!

Rebel Readline offers a Clojure REPL with:

• Easy multi-line editing
• Auto-indentation
• TAB completion
• Argument documentation displayed after typing a function name
• Inline evaluation, allowing you to evaluate code without pressing enter
• Quick access to documentation, source, and apropos for the symbol under the cursor
• Familiar terminal key bindings, including history search, etc.

Rebel Readline is also a library that provides a line reader for Clojure dialects.

Learn more about the motivations behind creating this terminal readline library here.

Recent updates include nREPL support. For details, refer to rebel-readline-nrepl.

The line reader requires direct terminal access. Therefore, do not launch Rebel Readline using clj or any other readline processes (like rlwrap) to avoid conflicts. Use one of the following options to start the JVM:

• The java command
• The Clojure clojure tool (without readline support)
• lein trampoline
• boot (must run in Boot's worker pod)

On Java 22 and later, Rebel Readline can show a native access warning from JLine or one of its terminal support libraries. The warning does not mean Rebel Readline failed to start. To suppress it, pass this JVM option:

clojure -J--enable-native-access=ALL-UNNAMED -Sdeps "{:deps {com.bhauman/rebel-readline {:mvn/version \"0.1.11\"}}}" -M -m rebel-readline.main

For an alias, add the option to :jvm-opts:

:aliases
{:rebel {:extra-deps {com.bhauman/rebel-readline {:mvn/version "0.1.11"}}
         :main-opts ["-m" "rebel-readline.main"]
         :jvm-opts ["--enable-native-access=ALL-UNNAMED"]}}

To quickly try Rebel Readline, install the Clojure CLI tools and execute:

clojure -Sdeps "{:deps {com.bhauman/rebel-readline {:mvn/version \"0.1.11\"}}}" -M -m rebel-readline.main

To install Rebel Readline as a Clojure tool from the latest Git release tag:

clojure -Ttools install-latest :lib com.github.bhauman/rebel-readline :coord '{:git/url "https://github.com/bhauman/rebel-readline.git" :deps/root "rebel-readline"}' :as rebel

Then launch it from a project directory with:

clojure -Trebel repl

Rebel Readline defaults to Emacs-style key bindings, which can be configured.

• Ctrl-C: Abort the current line
• Ctrl-D at line start: Send an end-of-stream signal (usually quits the REPL)
• TAB: Word completion or code indentation
• Ctrl-X Ctrl-D: Show documentation for the current symbol
• Ctrl-X Ctrl-S: Show source code for the current symbol
• Ctrl-X Ctrl-A: Show apropos information for the current symbol
• Ctrl-X Ctrl-E: Inline evaluation for SEXP

You can explore additional key bindings with the :repl/key-bindings command.

Commands start with the :repl/... keyword. For available commands, type :repl/help or :repl followed by TAB.

You can add new commands by implementing methods for the rebel-readline.commands/command multimethod and documenting them using rebel-readline.commands/command-doc.

Add Rebel Readline as a tool within your ~/.clojure/deps.edn:

{
 ...
 :aliases {:rebel {:extra-deps {com.bhauman/rebel-readline {:mvn/version "0.1.11"}}
                   :exec-fn rebel-readline.tool/repl
                   :exec-args {}
                   :main-opts ["-m" "rebel-readline.main"]}}
 ...
}

You can then launch the REPL in your project directory with:

clojure -Xrebel 

Remember to use clojure instead of clj to avoid interference from other readline tools.

Alternatively, run it as a standalone tool:

clojure -T:rebel 

You can pass Configurable Parameters when launching the REPL:

clojure -Xrebel :highlight false 

It's also possible to specify parameters in the :exec-args key of your ~/.clojure/deps.edn.

You can also launch with the rebel-readline.main CLI. With the configuration above you can use:

clojure -Mrebel --no-highlight

Options:
  -h, --help                                       Display help
  -k, --key-map KEYMAP         :emacs              Choose between :viins or :emacs
  -t, --color-theme THEME      :dark-screen-theme  :(light, dark, or neutral)-screen-theme
      --no-highlight                               Disable syntax highlighting
      --no-completion                              Disable code completion
      --no-eldoc                                   Disable function documentation display
      --no-indent                                  Disable auto indentation
      --no-redirect-output                         Disable output redirection
  -b, --key-bindings BINDINGS                      Specify custom key bindings
  -c, --config CONFIG                              Path to a config file

Add the dependency to your project.clj:

[com.bhauman/rebel-readline "0.1.11"]

Start the REPL with:

lein trampoline run -m rebel-readline.main

You can also add it to $HOME/.lein/profiles.clj so you don't have to add it to individual projects.

To simplify REPL launches, create an alias in project.clj:

:aliases {"rebl" ["trampoline" "run" "-m" "rebel-readline.main"]}

This lets you start the REPL using lein rebl.

Start Rebel Readline using Boot with:

boot -d com.bhauman/rebel-readline call -f rebel-readline.main/-main

You can set vi key bindings either in your deps.edn or in ~/.clojure/rebel_readline.edn:

{:key-map :viins}

You can provide various configurable options in your deps.edn or ~/.clojure/rebel_readline.edn:

:config          - path to an edn configuration file

:key-map         - :viins or :emacs (default: :emacs)

:color-theme     - (:light, :dark or :neutral)-screen-theme

:highlight       - (boolean) enable syntax highlighting (default: true)

:completion      - (boolean) enable code completion (default: true)

:eldoc           - (boolean) enable function documentation display (default: true)

:indent          - (boolean) enable auto indentation (default: true)

:redirect-output - (boolean) rebinds output during read (default: true)

:key-bindings    - map of key bindings to apply after others

To configure key bindings, use your configuration file. Ensure correct serialization of key names.

Rebel Readline can replace the clojure.main/repl-read behavior:

(rebel-readline.core/with-line-reader
  (rebel-readline.clojure.line-reader/create
    (rebel-readline.clojure.service.local/create {:highlight false}))
  (clojure.main/repl
     :prompt (fn []) ;; prompt is handled by line-reader
     :read (rebel-readline.clojure.main/create-repl-read)))

You can also use rebel-readline.core/with-readline-in for easier wrapping:

(rebel-readline.core/with-readline-in
  (rebel-readline.clojure.line-reader/create
    (rebel-readline.clojure.service.local/create))
  (clojure.main/repl :prompt (fn [])))

The line reader provides capabilities like completion, documentation, and evaluation through a service. The common service is rebel-readline.services.clojure.local, which queries the local Clojure process.

For environments without a suitable service, you could use clojure.service.local or clojure.service.simple, though with less optimal results.

For ClojureScript, visit this repository section.

Currently, services for SocketREPL and pREPL are not available.

We welcome contributions! Look for issues marked help wanted for good starting points.

When contributing:

• File an issue for non-trivial changes before creating a PR.
• Consolidate PR changes into one commit.
• Make changes small and easy to understand; this allows for better review.
• Break larger solutions into manageable PRs.
• Communicate if a PR represents more exploratory efforts.

If you need assistance on what to work on, feel free to reach out on the Clojurians Slack channel.

Copyright © 2018 Bruce Hauman

Distributed under the Eclipse Public License, version 1.0 or (at your option) any later version.