A Blog about Business, Enterprise Architecture and Software Design by the Founders of ZenModeler

Practical Starter Tips for Clojure

In this article, I share my experience of developing with Clojure over the last months. I focus on the practical tips that will allow you to start seamlessly on Mac Os X (but should apply with Linux and Windows).

Clojure logo

Clojure Resources

When learning Clojure, first of all: have great resources to rely on and not get lost.

Books

If you begins with functional programming I suggest you to start with Clojure Programming from Christophe Grand, O'Reilly, once more experienced you can follow with the amazing Joy of clojure for hindsightful thoughts about programming applied with clojure (a 2nd edition is out). For those of you that prefer a more "example oriented" approach, have a look at the nice Clojure Cookbook. If you have a Java/OO background I suggest you to read Functional Programming for the Java Developer and Functional Programming for the Object Oriented Programmer. Of course, the bible, for more fundamental stuffs: Structure and Interpretation of Computer Programs (A good PDF and EPUB version are available).

Cheatsheet and documentation

I tend to have a Clojure Cheatsheet and a browser always opened on clojuredocs.org. I cloned the clojuredocs repo so I always access the clojuredocs on my Mac even when I'm offline. You can also access clojuredocs directly from the REPL with clojuredocs-client. You should also have a look at the Clojure Style Guide.

Update: there is now an up-to-date alternative to ClojureDocs named Clojure Grimoire, also Clojure Grimoire is available offline. The Clojure Cheatsheet is even updated to link to Grimoire instead of ClojureDocs.

Community news through newsletters and blogs

Clojure is already well-stocked with newsletters: Clojure Gazette, (def newsletter), Read Eval Print λove and agreggators: Planet Clojure and Clojurls.

Tero Parviainen, that organized ClojureCup, also has a great list of Clojure resources, another list of clojure resources.

I personaly gave a clojure presentation at the Lausanne Java User Group some times ago, here are my "Clojure Introduction slides".

Online resources

BraveClojure has great and detailed articles about Clojure and for exercising you've got 4Clojure and ClojureKoans. Clojure from the ground up is also a good introduction, and Clojure Distilled will introduce you to the mindset needed when using Clojure.

Conferences

Some conferences are entirely dedicated to Clojure: ClojureWest and clojure/conj in US, EuroClojure in Europe. Some have a good inclination towards Clojure like StrangeLoop or LambdaJam.

Common Environment for Clojure Programming

Java / Clojure / Leiningen

A JDK, Clojure, and Leiningen if you want your repl loaded with all the classpath dependencies of your project just type lein repl.

Make the non-US keyboard more hacker-friendly

The (caps-lock) key is almost unused and as a very convenient and accessible one I suggest you to remap it to ctrl. All the non-US keyboard layout are painful for daily use (I use a french one!), especially when you type a lot of (), {} and []. Therefore, I installed KeyRemap4MacBook and assign the [ to a single keystroke on the (shift) key. Of cource I assigned ( for the left one, and ) for the right one. The combination of of 'alt-shift' but by hitting the 'alt' or 'cmd' key first print me respectively a { or [ (and so on for the right side } and ]). Here is my modified KeyRemap4MacBook private.xml as a gist.

iTerm2

iTerm2 is a terminal emulator for Max OS X with impressive features, its configurability is the major one for me.

tmux

tmux is a terminal multiplexer allowing you to manage window and panes in one terminal and in a persistent way (that's to say you can close the terminal window, your session stay alive in the background with the tmux process). The best part of tmux is that it allows to script all my development environment in one command invocation: starting all the databases, the web server, the log tail, a window for the front-end, the backend, the infrastructure, etc.. The tmux book from pragprog is a must have to get started.

zsh

zsh is a shell designed for interactive use, hence the shortcuts and auto-completion it provides are simply awesome. Install oh-my-zsh to get a bundle of useful plugins in a seamless installation.

Here are some links to discover the power of zsh:

As a conclusion, here is a great blog post about the text triumvira that the combination of zsh, tmux and vim is.

Clojure Editor

The very first goal is to have an editor opened in one window and a clojure REPL beside, then to send code in the REPL for evaluation. That's all I need and it's called REPL-Oriented Development! beside the IDE choice, a good workflow with the REPL is also mandatory, here are some links about the subject: the famous Clojure Workflow Reloaded based on tools.namespace, Give your Clojure Workflow more flow.

There are basically 2 schools of thoughts on the editor subject: vim and emacs.

The vim School of Thought

Vim is a basic choice with limited features about the language comprehension as vim almost edit text only but also easier to start with. I don't cover the basics of working with vim as there is plenty of resources on the web, here are some:

Clojure and Vim

Install VimClojure and then C-c C-c will send the form under the cursor to the REPL hosted in a tmux pane. The first time you invoke the command it will ask you the tmux window.pane you want your selection to be sent. It's the most simpler and immediate development environment I used myself for some months. I didn't use the nailgun plugin for interacting with a repl as the level of clojure integration is very low with vim. At that time I prefered to just send basic text to the repl and switch between vim and the repl inside a tmux pane. A better integration and understanding of the edited language is also why I migrate to emacs.

I suggest you to read "The Text Triumvirate", a great blog post about the productive environment resulting from the use of the "vim/tmux/zsh".

The Emacs School of Thought

I switch from vim to emacs to get a better integration between the Clojure source and the repl. Emacs has a different philosophy compared to Vim, here is the emacs manual to get through it, and an Emacs CheatSheet for a reference.

Starting and Quitting Emacs

Emacs should be started in the background as its initialization is costly.

      $ emacs --daemon
   

then start instantaneously emacs with:

      $ emacsclient your_file.clj
   

Then to kill softly the daemon:

      $ emacsclient -r "(kill-emacs)"
   

Basic Functions I use with Emacs

  1. Start the cider repl: M-x cider-jack-in (should auto complete!)
  2. Evaluate the entire file: C-c C-k
Essential Emacs Functions key binding
Undo C-x u then q to quit the undo-tree
Load file C-x f
Save file C-x C-s
Split window vertically C-x 3
Go to the beginning of the file M-<
Go to the end of the file M->
Move to other window C-x o (should really work on this for a more straightforward keystroke as this function will be call several times per minutes)

Interacting with nrepl

Install emacs live

I find the "emacs live" bundle to be a good one to start with for clojure development, it bundles the cider project to boost emacs REPL capabilities.

nREPL Functions key binding
Switch the namespace of the repl buffer to the namespace of the current buffer C-cM-n
Evaluate the form preceding point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer C-xC-e
Evaluate the form preceding point and display the result in a popup buffer C-cC-p
Evaluate the top level form under point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer. C-M-x or C-cC-c
Evaluate the region and display the result in the echo area. C-cC-r
Interrupt any pending evaluations. C-cC-b
Invoke macroexpand-1 on the form at point and display the result in a macroexpansion buffer. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1. C-cC-m
Invoke clojure.walk/macroexpand-all on the form at point and display the result in a macroexpansion buffer. C-cM-m
Eval the ns form C-cC-n
Select the REPL buffer. With a prefix argument - changes the namespace of the REPL buffer to the one of the currently visited source file. C-cC-z
Clear the entire REPL buffer, leaving only a prompt. Useful if you're running the REPL buffer in a side by side buffer. C-cM-o
Evaluate the current buffer. C-cC-k
Load a file. C-cC-l
Display doc string for the symbol at point. C-cC-d
Display the source for the symbol at point. C-cC-s
Display JavaDoc (in your default browser) for the symbol at point. C-cC-j
Jump to the definition of a symbol M-.
Return to your pre-jump location M-,
Complete the symbol at point. (For auto-complete integration, see ac-nrepl) M-TAB

I also wrote a short emacs-lisp function, called nrepl-send-to-repl, that send the form under the cursor as text to the repl.

paredit-mode

At first, I found the paredit-mode to be the most annoying one I ever met until I understood the "way of seeing it": think of the function as moving parens to the left or to the right and not moving the text (see the first two examples below). The 3 paredit functions I constantly use are the followings:

Paredit Function Binding Example
paredit-forward-slurp-sexp (foo (bar |baz) quux zot) ---> (foo (bar |baz quux) zot)
paredit-forward-barf-sexp (foo (bar |baz quux) zot) ---> (foo (bar |baz) quux zot)
paredit-splice-sexp M-s (foo (bar| baz) quux) ---> (foo bar| baz quux)
disable paredit

In short I constantly move the "end" paren to the right or to the left (I actually seldom move the "start" paren) end remove enclosing parens. The rest "nice-to-have" paredit functions are not as mandatory as that 3 ones and I often replace one paredit function with a sequence of that 3 basic ones (like splitting a (foo bar) into (foo) (bar) just ). Then I sometimes disable paredit to insert or remove a specific paren like any "dumb" editor. Finally, here is the best paredit explanation I stumbled upon.

The outsiders

The community is quite active in the IDE field. Here are some other options you should consider:

Being an occasional Sublime Text user and a Light table backer, I don't have an opinion about these environments. I'm quite happy with my emacs choice for the moment and should stick with it in the short term.

Conclusion

This post should give you a good overview of the resources to get started with Clojure and what it's like to install and use a Clojure development environment.