1 Introduction

Version 2016-09-22, 7966 words. Reading time: 50 minutes.

Interactive development is at the very heart of Clojure's philosophy. Exploration, fast feedback, poking at and into a running system, these are the bread and butter of Clojure programming, and it all starts with a humble REPL.

user=> █

As the Clojure ecosystem evolved, its REPLs evolved as well. We now have network and socket REPLs, browser connected and bootstrapped REPLs, REPLs in our editors that power our tools. It's easy to lose track of all the options available. What are they for? How do you use them?

While writing this guide I kept remembering the first time I went to Berlin's Clojure Dojo. We didn't have many presentations back then, instead people just chose a topic and hacked around. This first time I was there the topic was Om. I was eager to get started, but first I wanted to have my trusty Emacs set up. I had heard about browser connected REPLs, surely I should be able to set one up to help me along the way.

I spent the whole meetup poring over the READMEs of Austin and Piggieback, not making sense of any it. CIDER was still called nREPL.el, which just added to the confusion. I went home with a broken setup and a broken heart.

Things have come a long way since then. So much love and hard work has gone into the tooling surrounding Clojure it makes me giddy. Unfortunately there is still a lot of confusion as well, and documentation isn't always comprehensive. This guide seeks to remedy that. It will give you a map of the territory, with clear instructions to help you get where you want to be. I hope you'll enjoy the trip.

What's a REPL?

A REPL is an interactive prompt, a program which allows you to type in some code, and shows you the result of evaluating this code. You are probably already familiar with several REPLs, such as the browser console, which evaluates JavaScript, or your Terminal (Console, Command Prompt, Shell), which evaluates shell code.

Dynamic programming languages all come with REPLs nowadays, like irb for Ruby, or iex for Elixir, and LISP languages in particular have a long history of using REPLs for interactive development.

What is it good for?

REPLs are important because they give you instant feedback. You don't have to save, compile, then run. Just type the code and press enter. This encourages experimentation. It's the "let's poke at it with a stick" of programming, a way of instantly validating, or adjusting, your concept of reality.

Clojure is especially suitable for this because the representation of its values is in turn valid Clojure code, so the return value of a function can be easily read and interpreted. Instead of opaque impenetrable objects we have simple maps, vectors, sets, with their contents clearly showing.

How does a REPL work?

REPL stands for Read-Eval-Print-Loop, this bit of Clojure pseudocode demonstrates how a REPL works.

(loop [input (read-line-from-stdin)]
  (-> input
  (recur (read-line-from-stdin)))

First some code is READ from the input stream, then that code is EVALuated, and finally the result is PRINTed on the output stream, before LOOPing back and starting over again.

Contributing to This Guide

The source for this book is on Github: lambdaisland/lambdaisland-guides. If you find a typo, find parts that could be improved or extended, or if you want to contribute new sections, then please open a pull request.

This book is written in org-mode format, so it's easiest to edit it with Emacs and org-mode, although it's just plain text so any editor will do. For small fixes you can even make the edits directly on Github.



  • Dive into cljs.repl/doc and friends. These are the equivalents of the clojure.repl helpers. Planck makes these available in the cljs.user namespace, Figwheel does not. Try out the various ClojureScript repls and see how to access these helpers.
  • Add a section on Dirac / cljs-devtools.
  • Add a section on boot-cljs-repl
  • Gorilla REPL
  • crepl