I’ve been using Leiningen for all my Clojure projects and its REPL environment is very helpful to do experimentations with the language. However, I would like to have features like, for example, automatic indentation or the ability to execute pieces of code without needing to rewrite or add them line by line using the arrow keys. Also, it’s not handy when I want to share my snippets or make a presentation out of them. If only there was an easy way for this…

Well, it seems that Jupyter could be the solution here. It is,undoubtedly, one of the most expressive tools for programming and science. A fully open source project, supported by NumFocus, Jupyter supports kernels for a big number of programming languages. In this article, I will focus on one of the two available kernels for Clojure, called CloJupyter (the other one, Clj-Jupyter has been inactive for almost a year). CloJupyter is a project that started on 2015 and it is been active seen then.

Install Jupyter

The first thing we’ll need is to install Jupyter (if you have already installed it, feel free to skip this paragraph).

For all my personal projects I use virtual environments with Miniconda. If you don’t have Miniconda in your system, you can download it from its website and run the bash script to install it

bash Miniconda3-latest-Linux-x86_64.sh

Next, create a virtual environment for python=3.5

conda create -n jupyter_playground python=3.5

activate it

source activate jupyter-playground

and install Jupyter itself

conda install jupyter

To test it, run

jupyter notebook

to start the Jupyter server. You should be able to see the startup screen in your browser

If you started the server inside a non empty folder, you would see its contents from this page. Now, select “New”–>”Python 3″ in order to get an empty notebook

Let’s execute a simple Python command. Try

print('Hello Jupyter!')

in the first cell and execute it with Shift+Enter

Piece of cake! In the same way you can write whole snippets in one cell or split your code in different cells. Have a look at this quick start documentation page for a more analytic presentation, or go directly to the official doc page.

Now, select “File”–>”Close and Halt” to close the notebook, then close the startup window and Ctrl+c in the console to stop the Jupyter server: it is time to see how to add the CloJupyter kernel.

Install CloJupyter kernel

Clone the project from its GitHub page in your workspace folder

git clone https://github.com/roryk/clojupyter

Enter the clojupyter folder and run

make make install

Assuming that there were no error during the compilation, you can start the Jupyter server again and this time select “New”–>”Clojure”. You should get a notebook with the Clojure kernel which you can test right away

Great! How about digging a bit further?

What’s in the box?

The standard features that are included in Jupyter:

tab completion

syntax highlighting (very important with all these LISP brackets!)

indentation

are here to help us write Clojure code (especially the indentation, which is something missing from Leiningen REPL…). Let’s create a simple function

Bliss!

Another useful Jupyter feature is the documentation. In a Python kernel, you can see the docstring of a function by adding a ? after its name. This will not work in CloJupyter, but we can use Clojure’s documentation functions, doc and find-doc. However, if you try, for example

(doc print)

it will fail, because doc belongs to clojure.repl library, which is not included in the default namespace. That means, you need to either need to specifically refer to its namespace (clojure.repl/doc, clojure.repl/find-doc) or include clojure.repl namespace into the default one

(use '[clojure.repl :only (doc)])

You take it from here

Now I believe you are ready to start your own experiments with Clojure and Jupyter.

Of course, as with all software projects, you should come across unexpected behaviour or bugs. In such case, do a search first in case it is something known. If the problem persists, then you can always notify the contributors by raising an issue in the project’s Github page.

Happy coding!