# Clojure Programming/Tutorials and Tips
## Learning material available online
##### Online tutorials

* 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 Clojure

* Peter Seibel - "Practical Common Lisp" => original ; port to clojure
* 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 Walkthrough

* "Clojure, Emacs and Slime/Swank on Ubuntu 8.10" : link

##### Other Guides

* A Brief Beginner's Guide To Clojure (last updated: 2012-03)

## Introductions and Tips
### Clojure for Java Programmers

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 Java

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.
The main site's Java interop reference also shows how you can do that using the clojure.java.apipackage introduced in Clojure 1.6.

### Clojure for Scheme Programmers

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 |
| lists | list? | seq? |
| lists | car | first |
| lists | cdr | rest |
| lists | caar, cadr, ... | ffirst, fnext, ... |

### Clojure for Common Lisp Programmers

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 Programmers

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

### Unit Testing in Clojure

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-is

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):
Tests can be built standalone as well:
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.

#### Fact

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:
James posted a description of the library on the google group here. The library is hosted on github here.

#### unit-test

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:
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 Clojure

This was tested on Linux only, but should work in other Un*xes.
Put this into command-line-args.clj
Make it executable with something like
And then run it with parameters.
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:
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:
Otherwise, you can reference java the jar directly, like so:
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:
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 .jar

(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# mkdir -p project/{app,classes}
* bash# cd project
* create the clojure application app/hello.clj with content:
* compile the clojure application, using clojure REPL/shell:
* the compiled application is in classes/app:
* unpack the clojure.jar into ./classes :
* delete ./classes/META-INF
* create manifest text file called mf-app.txt with content:
(make sure that the file ends with a new-line character after the "." character)
* create the .jar file:
(the command ends with a ".")
* Try the application (app.jar):

### Using the (ns) macro

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.
* Import all of the functions from clojure.contrib.str-utils directly into the namespace.
* Import all of the functions from clojure.contrib.str-utils with an aliased namespace.
* Exclude Clojure's "list" function so that you can define your own function with that name.