UNREPL.el (0.1.0)

Emacs >= 25.1, Clojure >= 1.8.0

Pick your definition:

UNREPL.el is a Clojure IDE for Emacs.
UNREPL.el is a client interface to a Clojure’s Socket REPL through the UNREPL protocol.

Introduction

Both definitions above are correct and complement each other.

UNREPL.el started as a simple experiment for using the UNREPL protocol as the communication method between an Emacs buffers and a Clojure Socket REPL. With the pass of time, it has been evolving into an alternative* Clojure IDE. Currently it has a fair amount of Features.

UNREPL.el is meant to be REPL-centric. That means that UI relies heavily on the REPL for displaying any kind of data that may be too big or complex to display in the Echo Area or as an overlay.

\* UNREPL.el is an “alternative” because it is of the same nature as CIDER, but both differ in certain UI decisions, included the aforementioned. That said, UREPL.el also takes a lot of inspiration from CIDER’s features. If you are new to Clojure development in Emacs, for now I would recommend to start with CIDER, since it’s more stable, more & better documented, and has a bigger community behind it.

Features

Automatically create a Socket REPL using your project’s build tool

UNREPL.el currently supports Leiningen or Boot >= 2.7.2.

Connect to an existing Socket REPL

Elided data structures

Taking advantage of one of UNREPL’s nice features, the REPL buffer will elide big or complex data structures with clickable buttons.

Playing with Images? why not opening them in the REPL?

UNREPL.el supports displaying buffered images directly in the REPL.

Standard output strings can be grouped into their respective REPL entries

This is a customizable feature, you can turn it off by setting unrepl-repl-group-stdout to nil.

In place documentation

A la Unravel. Hit C-c C-d to get in-place documentation of the symbol at point.

Pretty (and elided) stacktraces

Even for lazy errors

Lazy errors are reduced to a minimum expression, with a button to inspect further.

Interactive evaluation results overlays

Same as CIDER and LightTable.

Is the result too big? Inspect it in the REPL

When interactive results are too big for in-buffer overlays, you can just move them to the REPL buffer and inspect them there.

UNREPL.el will also copy/paste the evaluated expression and add it to the REPL history.

Interactive Exception happened? Inspect it in the REPL

Exceptions are shown in the REPL buffer, no matter where they come from. UNREPL.el will try to figure out which expression caused the exception and will copy it to the REPL buffer as well.

And there is more to come…

Before releasing the first UNREPL.el stable version, a couple more features might land in:

REPL pretty printing for evaluation results.
Visible UI for interrupting pending evaluations.
Key bindings to navigate buttons in the REPL.

(not so) Quick Start

Installing

As of right now, UNREPL.el is not in MELPA yet, so in order to install it, you might need to get your hands a bit dirty:

Install a.el, clojure-mode, dash, and treepy. All available in MELPA.

Download this repository, or clone it with its submodules:

$ git clone --recursive https://github.com/unrepl/unrepl.el

Then place this repository, and its parseclj submodule copy, somewhere in your load-path. Or just paste this in your emacs configuration and evaluate it:

(let ((unrepl-dir "/path/to/your/copy/of/unrepl.el"))
  (add-to-list 'load-path unrepl-dir)
  (add-to-list 'load-path (expand-file-name "parseclj" unrepl-dir))
  (require 'unrepl))

Connecting to a Socket REPL

The main way to connect to a Socket REPL in UNREPL.EL is by issuing: M-x unrepl-connect.

When this command is executed in a buffer that belongs to a Clojure project, it will automagically create a Socket REPL for it and connect. Right now, UNREPL.el supports only automatic connection in projects using Leiningen or Boot >= 2.7.2.

If you already have a Socket REPL running, you can prefix the connect command (C-u M-x unrepl-connect) or issue M-x unrepl-connect-to to get a prompt for inserting your Socket’s host and port.

There are several ways to create your own Socket REPL, here are some examples:

# lein:
$ JVM_OPTS='-Dclojure.server.myrepl={:port,5555,:accept,clojure.core.server/repl}' lein repl
# or boot < 2.7.2:
$ boot -i "(do (require 'clojure.core.server) (clojure.core.server/start-server {:port 5555 :name :repl :accept 'clojure.core.server/repl}))" wait
# or boot >= 2.7.2:
$ boot socket-server --port 5555 wait
# or plain Clojure jar:
$ java -Dclojure.server.myrepl="{:port 5555,:accept,clojure.core.server/repl}" -jar ~/.m2/repository/org/clojure/clojure/1.8.0/clojure-1.8.0.jar

After UNREPL.el successfully connects to a Socket REPL you will be greeted with a REPL Buffer, and all your Clojure buffers related to the project you just connected will have the unrepl-mode activated automatically.

Usage

Besides the REPL Buffer, UNREPL.el enables a few commands in each Clojure Buffer running unrepl-mode:

Autocompletion with company-mode.
C-c C-z: Switch to REPL buffer
C-x C-e: Evaluate expression before point.
C-c C-c: Evaluate top level expression.
C-c C-r: Send last evaluation to the REPL buffer.
C-c C-b: Evaluate buffer.
C-c C-g: Interrupt current evaluation.
C-c C-q: Quit UNREPL.el

Resources

UNREPL: the protocol.
Unravel: an UNREPL terminal-based client.
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!

License

Distributed under the terms of the GNU GENERAL PUBLIC LICENSE, version 3.

bbatsov/unrepl.el