Introduction

Clojure koans are exercises meant to initiate you to the mysteries of the Clojure language. By following along the path set before you, you will touch on all the major aspects of the language, from simple datatypes to macros, from tail recursion to Java interoperability. Many will find Clojure quite different from any programming language they've used before. The koans' incremental, interactive approach to learning the language will help make the transition feel natural. By the time you are finished with them, Clojure will not be so mysterious at all.

Install Java

Before we begin the koans, we need Clojure, and before we install Clojure, we'll need Java. You probably already have Java installed, but if you don't, it's not difficult. Oracle provides installation instructions for Windows users, and Linux users should use their package manager of choice. Apple distributes Java 6 with their system update tool.

After downloading Java (if necessary), go to your console and enter:

Make sure the version installed is 1.5 or greater.

Install the Koans

If you'd like to jump into Clojure like the pros, you can install the koans with Leiningen, Clojure's most popular dependency management tool. (It will install Clojure for us shortly.) Follow the installation instructions for Leiningen bliss.

Important: if you already have lein 1.x installed, you'll need to upgrade to Leiningen 2.

Once you have Leiningen installed, you just need to clone the koans repo:

If you don't want to use Leiningen to manage dependencies for you, you can still easily install the koans manually. [Note: this option will only work until Github shuts down the Downloads feature completely in March 2013.] Just download and unzip the latest version of the koans here, and you should be ready to start.

Run the First Koan

Once you're inside the koans directory, you can immediately begin by running

if you have Leiningen installed as described above.

(Don't forget to cd into the clojure-koans directory after you've cloned the repo!)

Or, if you're not using Leiningen, you can use

on Mac or Unix, or

on Windows.

On the first run, you should see an error message like this:

The output is telling you that you have a failing test in the file 01_equalities.clj, on line 3. So open that file up in a text editor and make it pass by filling in the blanks!

Repeat

After you run and pass your first test, you'll find that the next one is failing. After all the tests in a file are passing, the run script will automatically begin testing the next file in the koans sequence.

A Word on Testing

The pattern of writing failing tests first and code to make them pass later is no mere novelty: it is the essence of test-driven development (TDD). The sages of TDD say that every new test should strive to be the simplest and most natural extension of those that come before it, so as to cover only one new part of the code. They also enjoin disciples to meditate on their progress regularly: after a test is made to pass, one should pause to refactor and refine one's code before moving on to the next test.

The koans, unlike tests in real test-driven projects, are already written for you. When you are ready to begin your own Clojure project and therefore your own tests, consider using a framework like Speclj to aid you on your journey.

Contributors

Our Contributors

If you have any questions or suggestions about the koans, feel free to open an issue or pull request.

Thanks

Using the koans metaphor as a tool for learning a programming language started with the Ruby Koans by EdgeCase; the Clojure koans themselves were started by developers at Relevance. This website is produced and hosted by 8th Light and powered by Joodo.