unravel

Unravel your REPL

Unravel is a simple command-line client for Clojure REPLs. It is based on the unrepl protocol, so instead of relying on nREPL, unravel communicates with your Clojure process through a Socket Server REPL.

Unravel provides a richer user experience by:

• showing docstring and arglist of vars as you type them
• eliding long or infinite sequences but allowing the user to request a continuation

Installation

To use unravel you need Clojure 1.8.0 or above.

Simple installation

On macOS, the easiest way to install unravel is via brew:

brew install unrepl/bin/unravel

On Linux or macOS you can also install (or update) unravel via npm:

sudo npm install -g unravel-repl

In either case you should end up with an unravel binary in your PATH:

unravel --version

Installation from git

For a more up-to-date version, you can check out master:

git clone https://github.com/pesterhazy/unravel.git
cd unravel
npm install
scripts/run [--debug] <host> <port>

Usage

Connect to a Clojure Socket REPL:

unravel [--debug] <host> <port>

In addition to common readline shortcuts, the following keybindings are available:

• Control-D: exit the REPL
• Control-O: show docstring for symbol under the cursor
• <Tab>: complete var or namespace

Lines starting with #__ are treated as special commands and interpreted by the REPL client. The following specials are available:

• #__help shows a help screen
• #__1, #__2, #__3 ...: expand the numberd lazy seq ellipsis
• #__: expand the most recent lazy seq ellipsis

Launching a Socket REPL

You can easily enable the Socket REPL feature for your Clojure project, whether you use boot, lein or a plain clojure jar. The Socket REPL does not have any dependencies other than Clojure 1.8.0.

To launch a Clojure process with a Socket REPL listening on port 50505 using boot, use:

boot -i "(do (require 'clojure.core.server) (clojure.core.server/start-server {:port 50505 :name :repl :accept 'clojure.core.server/repl}))" wait

Or if you have boot >= 2.7.2:

boot socket-server --port 50505 wait

Using Leiningen:

JVM_OPTS='-Dclojure.server.myrepl={:port,50505,:accept,clojure.core.server/repl}' lein repl

Using a plain Clojure jar:

java -Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}" -jar ~/.m2/repository/org/clojure/clojure/1.8.0/clojure-1.8.0.jar

As of Clojure 1.9 you can use the clojure command line tool:

clojure -J-Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}"

You can then connect to the process by running unravel in a separate terminal window:

unravel localhost 50505

Changes

0.2.2

• Print vars correctly
• Update unrepl
• Use 'user as init-ns
• Don't write to socket after closing connection
• Update to Lumo 1.6.0

0.2.1

• Enable lumo caching (3x startup time improvement)
• Interrupt running process on SIGINT
• Fix exceptions when connected to Boot-based socket server

0.2.0

• Live docs for vars and namespaces
• Use separate tooling connection for tab completion and docs
• Start in "user" namespace

0.1.6

• Fix installation via NPM

0.1.5

• Add repl specials
• Expand lazy seq ellipsis
• Fix issue with non-existant namespaces

0.1.4

• Tab completion (namespaces and vars)
• Pretty-print exceptions
• Use tagged literals
• Re-prompt on newline or Control-C

0.1.3

Persistent history

0.1.2

Distribute via npm

0.1.0

Show docstring

Future work

See TODO.md for a list of planned improvements. Unravel is developed in conjunction with unrepl.

Resources

• The Ultimate Guide To Clojure REPLs on the Socket REPL

• replicant: proof of concept of using Socket REPL for tooling

Join the #unrepl channel in the Clojurians slack!

Contributing

See [contributing.md].

Copyright

(c) 2017 Paulus Esterhazy

Unrepl payload.clj (c) 2017 Christophe Grand

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