Clojure is a dynamic, functional programming language that is a joy to write. I’ve been writing it professionally for the last year-and-a-half and wanted to share something I wish existed when I first got started.
This guide is not a primer on Clojure itself. I will not be going over the basics of the language, there are plenty of great guides out there that are a web search away.
This guide, therefore, is aimed at:
- Programmers coming from a different language who have decided to try Clojure;
- Programmers that are writing Clojure for the first time professionally.
The motivation might be a quick way to get a reliable environment up and running, freeing up more time to focus on learning the language itself.
(Hopefully) after reading this post, you can quickly start to form a workflow for tinkering away at Clojure code in little time.
To keep the scope of this guide relatively focused, I will assume that you are using an up to date version of macOS and understand how to use Homebrew.
While Homebrew works on Linux, I’ve not personally used it, therefore I cannot vouch if the commands have parity.
Dependencies
You will need Java, Clojure, Leiningen, and Visual Studio Code installed.
brew install adoptopenjdk clojure leiningen
brew cask install visual-studio-code
Calva
The only Visual Studio Code extension you will need to be productive with Clojure codebases is Calva. Make sure to have it installed.
I will be using terminology that is specific to Visual Studio Code and its UI elements.
To reduce confusion, make sure to read this document to familiarise yourself with elements of the User Interface.
Let’s tinker
In this next part, we’re going to:
- Create a new Clojure project using Leiningen.
- Connect to the REPL using Visual Studio Code and Calva.
- Evaluate Clojure expressions directly in your editor.
- Evaluate and run tests directly in your editor.
Create a new Clojure project
Inside the directory you want to create your Clojure project, run
lein new clojure-sandbox
Open the newly created clojure-sandbox directory inside Visual Studio Code.
Jacking-In
A large part of building software with Clojure is the REPL. Programmers are familiar with the concept of a REPL from other programming languages (e.g. irb for Ruby, python3 for Python).
In Clojure, things are taken one step further. A REPL instance created with Leiningen has a network port that allows incoming connections.
Since the aforementioned port is opened over a socket, a valid client — a terminal session or an editor, for example — can connect to it.
The simplest way to open a REPL instance is to run the command lein run in the clojure-sandbox directory.
We can take things a step further, however, by connecting to a REPL instance from Visual Studio Code using Calva.
Calva takes care of all this for us by providing a command called Jack In.
In Visual Studio Code
- Open
src/clojure_sandbox/core.clj - Bring up Visual Studio Code’s command palette.
- Type in
Jack-Inand select the optionCalva: Start a Project REPL and Connect (aka Jack-In) - Select the
Leiningenproject type
You should be connected to a REPL instance and ready to evaluate code.
Evaluating Clojure Forms
https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FjkAcslwOBu4%3Ffeature%3Doembed&display_name=YouTube&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjkAcslwOBu4&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FjkAcslwOBu4%2Fhqdefault.jpg&key=a19fcc184b9711e1b4764040d3dc5c07&type=text%2Fhtml&schema=youtubeA quick screencast to help with visualising evaluating forms in Clojure.
By default, Calva opens a REPL window on the right hand side after Jack-In. I will refer to the window as the Calva REPL.
You can start to evaluate Clojure forms in the Calva REPL just like any other REPL. Type in an expression, press the return key and observe the feedback — e.g. typing (+ 2 2) followed by the return key will return 4.
Since you have jacked into a REPL connection, you can tinker around with Clojure code in your editor and evaluate the code you write. This workflow is known in the Clojure community as “REPL driven development” and is a powerful paradigm.
Type (+ 2 2) anywhere in core.clj and then, with your cursor anywhere on that line, you can evaluate the result of this form by pressing Ctrl + Command + C and E or selecting Calva: Evaluate Current Form in Visual Studio Code’s command palette. This will output 4 to the output window.
Calva: Evaluate Current Form in REPL Window in Visual Studio Code’s command palette will evaluate output the evaluation to the REPL window instead of the output window.
I prefer using the output window on my laptop as I can close the REPL window and use the output window for my feedback loop, saving me precious screen real-estate.
The choice of the output window or REPL is a standard evaluation pattern in Calva. There are other options to output which you should play around with. I will focus on outputting the result to the output window, as that is my personal preference (but feel free to use the output type you prefer).
Once you start to write more complex Clojure, evaluating the result of a form might not do what you expect, e.g.
(let [name "Muyiwa"]
(str "Hello " name))
If your cursor is on "Hello " and you try to evaluate the form, you will get a syntax error because we are trying to evaluate and incomplete form. If your cursor is on name then it will evaluate to a function symbol.
For use-cases like this, you want Calva to evaluate the top-level form. If you start typing Top Level in the Visual Studio Code command palette, you can see your options. The shortcut to evaluate the top level form to the output window is Ctrl + Command + C``Space.
This is the command with the heaviest use when writing Clojure in my day-to-day as the top-level form will work even for the simple examples that we tried earlier like (+ 2 2). It’s a handy shortcut to know.
Running Clojure Tests
To run Clojure tests in Visual Studio Code, open a test file (e.g. test/clojure_sandbox/core_test.clj and start typing calva test into the Visual Studio Code command palette.
The four options:
- Run Tests
- Run Current Test
- Run Failing Tests again
- Run Tests for Current Namespace
Should be enough for you to fit into your testing workflow. See if you can make the test pass.
Conclusion
If this is the beginning of your journey with Clojure and REPL driven development, I recommend the following next steps:
- Read the Calva documentation and refer to it when you need it.
- Memorise the Calva shortcuts for
Jack-InandEvaluate top level form. - Follow all the exercises under the Learn Clojure official guide, using the sandbox project and REPL driven development for the exercises.
- Read the Leiningen documentation.
I hope this has been a useful primer to help you get going and focus on playing around with a delightful language.