Clojure In Small Pieces

Clojure In Small Pieces

0 Ungluers have Faved this Work

Rich Hickey invented Clojure. This is a fork of the project to experiment with literate programming as a development and documentation technology.

Every effort is made to give credit for any and all contributions.

Clojure is a break with the past traditions of Lisp. This literate fork is a break with the past traditions of code development. As such it is intended as an experiment, not a replacement or competition with the official version of Clo jure.

Most programmers are still locked into the idea of making a program out of a large pile of tiny files containing pieces of programs. They do not realize that this organization was forced by the fact that machines like the PDP 11 only had 8k of memory and a limit of 4k buffers in the editor. Thus there was a lot of machinery built up, such as overlay linkers, to try to reconstruct the whole program.

The time has come to move into a more rational means of creating and main- taining programs. Knuth suggested we write programs like we write literature, with the idea that we are trying to communicate the ideas to other people. The fact that the machine can also run the programs is a useful side-effect but not important.

Very few people have seen a literate program so this is intended as a complete working example, published in book form. The intent is that you can sit and read this book like any other novel. At the end of it you will be familiar with the ideas and how those ideas are actually expressed in the code.


Well, I previously commented that Advocacy is Volunteering and then I managed to advocate moving clojure to literate form. Since I'm studying the details of the inner workings of Clojure this seemed to be the right time to experiment with a literate form. I have put together the beginnings of a Clojure in Small Pieces book.  The book is hyperlinked so if your pdf reader supports it you can go to the index and find pieces of code or move from the table of contents to the appropriate code chunks. Chunking is very coarse-grained at the moment but will become smaller as more code is explained. The literate chunk machinery uses the previously posted code. The code has been lightly modified to fit into the page format. Clearly some of the developers have very wide screens. When rendered on a page in raw form the code runs off the side of the page.

In the book you can see that I've split out portions of the code into the Red-Black section, the Seq section, and the Iterator section. I am also experimenting with parallel programming using both MPI and MapReduce (Hadoop). The idea is to build a multiple node Ants demo that has N independent ant colonies, one per parallel node, all being displayed on a single ant field. I would like the parallel form to be very close in spirit to Rich's original version so I'll have to document that in detail first. Note that the people named on the front cover are from the author tags in the source code. I have no idea who else might have worked on portions of the code. If you know, please let me know. Literature references are especially welcome. I have a few, such as the Multi-Version Concurrency Control papers, which will be added when I get to the STM section. In any case, this is purely an experiment in literate clojure.

-- Tim Daly

Why read this book? Have your say.

You must be logged in to comment.

Rights Information

Are you the author or publisher of this work? If so, you can claim it as yours by registering as an rights holder.


This work has been downloaded 127 times via ebook links.
  1. 127 - pdf (OSI) at


  • Clojure (Computer program language)
  • Computers
  • Computers / Programming Languages
  • literate programming


edition cover


Copy/paste this into your site: