unravel-repl v0.3.0-beta

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 using npm

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

sudo npm install -g unravel-repl

This installs the unravel binary and adds it to your PATH.

On macOS you can also use

brew install bfontaine/utils/unravel

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

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.