Last modified on 6 March 2014, at 18:01

Clojure Programming/Tutorials and Tips

Learning material available onlineEdit

Online tutorialsEdit
  • Official Clojure reference & API : link
  • "Clojure - Functional Programming for the JVM" by R. Mark Volkmann: link
  • Moxley Stratton - "Clojure Tutorial For the Non-Lisp Programmer" : link
  • Satish Talim - "Clojure Notes": link
  • Eric Rochester - "Clojure Series" (deals with tokenization and stemming) : link
  • "Clojure tutorial for ImageJ" : link
  • "Wikibooks.org/Clojure Programming/Concepts" : link
Online Books ported to ClojureEdit
  • Paul Graham - "On Lisp" => original ; chapters 1-5 by fogus link, chapters 7,9,10 by Halloway link, most chapters from 2 - 16 by pangloss on github
  • "Structure and Interpretation of Computer Programs" => original ; port to clojure chapter 1 link
Installation WalkthroughEdit
  • "Clojure, Emacs and Slime/Swank on Ubuntu 8.10" : link
Other GuidesEdit

Introductions and TipsEdit

Clojure for Java ProgrammersEdit

Rich Hickey gave a talk entitled "An Introduction For Java Programmers". Audio and slides are available in two parts on the Clojure blip.tv channel. Good "Clojure Scripting" tutorial here covers many basics of Clojure, as well as its Java integration (for example, using ImageJ from Clojure).

Invoking Clojure from JavaEdit

The main site's Java Interop reference shows how you can call your Java code from Clojure. But because Clojure is implemented as a Java class library, you can also easily embed Clojure in your Java applications, load code, and call functions.

Repl.java and Script.java in the distribution are the canonical examples for loading code from a user or from a file. In this section we'll show how to use the same underlying machinery to load code and then manipulate it directly from Java.

Here's a script that defines a simple Clojure function.

; foo.clj
(ns user)
 
(defn foo [a b]
  (str a " " b))

And here's a Java class that loads the script, calls the foo function with some Java objects as arguments, and prints the returned object.

// Foo.java
 
import clojure.lang.RT;
import clojure.lang.Var;
 
public class Foo {
    public static void main(String[] args) throws Exception {
        // Load the Clojure script -- as a side effect this initializes the runtime.
        RT.loadResourceScript("foo.clj");
 
        // Get a reference to the foo function.
        Var foo = RT.var("user", "foo");
 
        // Call it!
        Object result = foo.invoke("Hi", "there");
        System.out.println(result);
    }
}

Compile this and run it to see the printed result:

>javac -cp clojure.jar Foo.java

>java -cp clojure.jar Foo
Hi there

>

When Calling code from outside the classpath, the same effect can be achieved by running

clojure.lang.Compiler.loadFile("foo.clj");

From within the Java code instead of RT.loadResourceScript("foo.clj");

Clojure for Scheme ProgrammersEdit

When asked about using SICP to learn about Clojure, Rich had this to say:

Everyone's experience will be different, of course. Here's my 2 cents:
I don't think SICP is a book about a programming language. It's a book about programming. It uses Scheme because Scheme is in many ways an atomic programming language. Lambda calculus + Tail Call Optimization (TCO) for loops + Continuations for control abstraction + syntactic abstraction (macros) + mutable state for when you need it. It is very small. It is sufficient.
The book really deals with the issues in programming. Modularity, abstraction, state, data structures, concurrency etc. It provides descriptions and toy implementations of generic dispatch, objects, concurrency, lazy lists, (mutable) data structures, 'tagging' etc, designed to illuminate the issues.
Clojure is not an atomic programming language. I'm too tired/old/lazy to program with atoms. Clojure provides production implementations of generic dispatch, associative maps, metadata, concurrency infrastructure, persistent data structures, lazy seqs, polymorphic libraries etc etc. Much better implementations of some of the things you would be building by following along with SICP are in Clojure already.
So the value in SICP would be in helping you understand programming concepts. If you already understand the concepts, Clojure lets you get on with writing interesting and robust programs much more quickly, IMO. And I don't think the core of Clojure is appreciably bigger than Scheme's. What do Schemers think?
I think the Lisps prior to Clojure lead you towards a good path with functional programming and lists, only to leave you high and dry when it comes to the suite of data structures you need to write real programs, such data structures, when provided, being mutable and imperative. Prior Lisps were also designed before pervasive in-process concurrency, and before the value of high-performance polymorphic dispatch (e.g. virtual functions) as library infrastructure was well understood. Their libraries have decidedly limited polymorphism.
Stuart Halloway's book Programming Clojure is now available as an e-book (in Beta) and will come out on paper soon. Of course to the extent Schemes go beyond the standard to provide more complete functionality (as most do), there are no books on that either. Just docs in both cases.
Learning Scheme or Common Lisp on your way to Clojure is fine. There will be specifics that don't translate (from Scheme - no TCO, false/ nil/() differences, no continuations; from CL - Lisp-1, symbol/var dichotomy). But I personally don't think SICP will help you much with Clojure. YMMV.


Function type Scheme function Clojure function
lists cons cons
list? seq?
car first
cdr rest
caar, cadr, ... ffirst, fnext, ...

Clojure for Common Lisp ProgrammersEdit

The table below lists some of the Common Lisp entities (functions, macros etc.) and their (somewhat) equivalent Clojure entities. Note that some of the concepts may not be an exact match. For the exact behavior of the Clojure entities it is recommended that the reader see the Clojure Reference Documentation available at the Clojure home page. Note that some of these differences may be because Clojure has its heritage in Lisp-1 and not Lisp-2.

The Clojure reference also documents common differences to lisps here.

Common Lisp Feature Clojure Equivalent
load load-file
make-array or #(N N N N) vector or [N N N N]
#| |# (multiline comment) (comment ...)
documentation doc, find-doc, javadoc
in-package in-ns
defstruct defstruct and create-struct (defrecord or deftype are preferred in 1.3)
defun defn
inline definline
lambda fn or the reader macro #(..)
cons cons, lazy-cons, conj
car, first first
cdr, rest rest
#\x (characters) \x
, ~
,@ ~@
eq (and variants) =
expt Math/pow java.lang.Math
user=> (Math/pow 10 2)
100.0
format String/format java.lang.String
user=> (format "0x%x 0x%x 0x%x" 10 20 30)
"0xa 0x14 0x1e"

or

user=> (clojure.pprint/cl-format false "~R" 42)
"forty-two"
gensym gensym or Simply suffix the symbol name with # as ` has auto-gensyms.
user=> `(x#)
(x__2136)
progn do
type-of class
typep instance?
let let and binding
do loop + recur
(loop [temp-one 1
       temp-two 0]
  (if (= 3 temp-two)
    temp-one
    (recur (inc temp-one) (inc temp-one)))) 
=> 3
cond cond, with one level of parens removed
(cond test-form1
        form1
      test-form2
        form2
      ...
      :else ;; :else or non nil or true
        form)
Hyperspec

http://clojure.github.com/clojure/
http://docs.oracle.com/javase/7/docs/
http://www.oracle.com/technetwork/java/index.html

Clojure for Python/Ruby/Perl ProgrammersEdit

A list of equivalent clojure functions for all methods in Ruby's Enumerable and Array classes.

Unit Testing in ClojureEdit

There are several unit testing solutions available in Clojure. They have slightly different ideas of how to approach testing. Check out each one and see which fits your testing philosophy the best.

test-isEdit

The test-is framework by Stuart Sierra is included in clojure.contrib. It allows you to tag your function definitions with assertions declared by the "is" macro as shown in this example (from the code):

(defn add2
  ([x] (+ x 2))
    {:test (fn [] (is (= (add2 3) 5))
                  (is (= (add2 -4) -2)
                  (is (> (add2 50) 50)))}

Tests can be built standalone as well:

(deftest test-new-fn
  (is (= (new-fn) "Awesome")))

The best place to look for more detail is in the source code itself which is part of the clojure-contrib library on Google Code.

In recent releases, this function has been moved into the core distribution in the namespace clojure.test; a compatibility library still exists in clojure-contrib.

FactEdit

Fact is a unit testing library by James Reeves styled after systems such as Ruby's RSpec. Using this approach, you write your tests as "facts" each with an assertion which should demonstrate that fact:

(fact "The length of a concatenated list is equal to the length of its parts"
  [xs (rand-seqs rand-ints)
   ys (rand-seqs rand-ints)]
  (= (count (concat xs ys))
     (+ (count xs) (count ys)))) 

James posted a description of the library on the google group here. The library is hosted on github here.

unit-testEdit

unit-test is a xUnit-style unit test system that allows you to define tests using a deftest macro. Tests contain various assertions and if one of the assertions fails, the test fails.

An example:

(deftest my-example-test []
   (let [x 1]
     (assert-equal 1 x "x is NOT one!")))

The original version of unit-test has not been kept up to date with Clojure changes (original home page here), but Tyler McMullen has patched it up and posted a working version on github here.

Shebang Scripting in ClojureEdit

This was tested on Linux only, but should work in other Un*xes.

Put this into command-line-args.clj

#^:shebang '[
exec java -cp "$HOME/.m2/repository/org/clojure/clojure/1.5.1/clojure-1.5.1.jar" clojure.main "$0" "$@"
]
(prn *command-line-args*)

Make it executable with something like

$ chmod 755 command-line-args.clj

And then run it with parameters.

$ ~/src/clj/lab/command-line-args.clj a b c
("a" "b" "c")

The explanation for this approach is described in this mail on Clojure group.


A more modern version of this approach is to write command-line-args.clj as:

":";exec java -cp "$HOME/path-to-clojure.jar" clojure.main $0 $*

(ns command-line-args)

(defn command-line? []                               
  (.isAbsolute (java.io.File. *file*)))

(defn main [] (println *command-line-args*))

(if (command-line?) (main))

It has a simpler "shebang" line.

(main) is always executed when the script is called from the command-line, even when called with no arguments.

(main) is not executed when command-line-args is used or required by another clojure file.

This method is inspired by this method of emacs scripting and works for the same reasons.


A recent update to Clojure made #! a to-end-of-line comment. Using revision 1106 or later shebang scripting can be done as normal if you have created a clj script, such as those described in Getting started:

#! /usr/bin/env clj

(println "Hello World!")

Otherwise, you can reference java the jar directly, like so:

#! /usr/bin/java -jar clojure.jar clojure.lang.Script

Note: this may not work on all systems, since on some systems only one argument is allowed!


On Windows, a similar approach works for embedding a Clojure script into a batch file:

:x (comment
@echo off
java -cp clojure.jar clojure.main "%~f0" %*
goto :eof
)

(println "Hi!" *command-line-args*)

Here, the first line is seen as a label (because of the initial colon) by cmd.exe, and as a bare keyword followed by the start of a multi-line comment by Clojure. The next lines (to the closing parenthesis) run Java with an appropriate classpath, passing the batch file name ("%~f0") and the command line arguments ("%*") and then exit the batch file (goto eof). The closing parenthesis then terminates the Clojure comment, and Clojure interprets the rest of the file.

Distributing application as self contained .jarEdit

(done under linux under bash shell)

  • add ./classes and ./ to the CLASSPATH shell variable and make sure that this class-path is also used by clojure (could mean editing the clj bash script):
bash# export CLASSPATH=./classes:./
  • bash# mkdir -p project/{app,classes}
  • bash# cd project
  • create the clojure application app/hello.clj with content:

(ns app.hello (:gen-class))

(refer 'clojure.core) ; not sure if this is necessary

(defn -main [& args] (println "application works"))
  • compile the clojure application, using clojure REPL/shell:
user=> (compile 'app.hello)
app.hello
user=> <CTRL><d>
  • the compiled application is in classes/app:
bash# ls classes/app/
hello.class  hello__init.class  hello$_main__4.class
  • unpack the clojure.jar into ./classes :
bash# unzip /opt/clojure/clojure.jar -d classes/.
  • delete ./classes/META-INF
bash# rm -r ./classes/META-INF
  • create manifest text file called mf-app.txt with content:
Main-Class: app.hello
Class-Path: .

(make sure that the file ends with a new-line character after the "." character)

  • create the .jar file:
bash# jar cmf mf-app.txt app.jar -C classes .

(the command ends with a ".")

  • Try the application (app.jar):
bash# java -jar app.jar
application works

Using the (ns) macroEdit

The (ns) macro can be a bit tricky. Here are some examples that might help.

  • Require all of the functions from clojure.contrib.str-utils, without importing them directly into the namespace.
(ns foo
  (:require clojure.contrib.str-utils))

(clojure.contrib.str-utils/str-join ", " ["foo" "bar"])
  • Import all of the functions from clojure.contrib.str-utils directly into the namespace.
(ns foo
  (:use clojure.contrib.str-utils))

(str-join ", " ["foo" "bar"])
  • Import all of the functions from clojure.contrib.str-utils with an aliased namespace.
(ns foo
  (:require [clojure.contrib [str-utils :as str-utils]]))

(str-utils/str-join "," ["foo" "bar"])
  • Exclude Clojure's "list" function so that you can define your own function with that name.
(ns foo
  (:refer-clojure :exclude [list]))