Clojure Programming Cookbook

The + function returns the sum of numbers. You can specify any number of numbers as arguments:

(+ 1 2) 
;;=> 3 
(+ 1 2 3) 
;;=> 6 
(+ 1.2 3.5) 
;;=> 4.7 

The - function subtracts the numbers. If a single argument is supplied, it returns the negation of the numbers:

(- 3 2) 
;;=> 1 
(- 1 2 3) 
;;=> -4 
(- 1) 
;;=> -1 

The * function returns the product of numbers:

(* 5 2) 
;;=> 10  
(* 1 2 3 4 5) 
;;=> 120 

The / function returns the numerator divided by all of the denominators. It is surprising for beginners of Clojure that if the numerator is not indivisible by the denominators, it returns a simple fraction. You can check the name of the class by the class function.

In the following example, 10 divided by 3 returns 10/3 and not 3.3333333...

(/ 10 5) 
;;=> 2  
(/ 10 3) 
;;=> 10/3 

To obtain numerical figures after a decimal point, cast the result by a float or double function:

(float (/ 10 3)) 
;;=> 3.3333333 
(double (/ 10 3)) 
;;=> 3.333333333333333 

The quot function returns the quotient of dividing the numerator by the denominator, and the decimal point is suppressed. rem returns the remainder of dividing the numerator by the denominator:

(quot 10 3) 
;;=> 3 
(rem 10 3) 
;;=> 1 

Clojure supports big numbers, and they are Java's BigDecimal. The bigdec function casts any number to BigDecimal. The suffix M denotes BigDecimal. Though it can express very large numbers, it cannot express repeating decimals and causes an error:

(bigdec (/ 10 2)) 
;;=> 5M 
(bigdec (/ 10 3)) 
;; ArithmeticException Non-terminating decimal expansion; no exact representable decimal result.  ;; java.math.BigDecimal.divide (BigDecimal.java:1690) 

Clojure also provides large integers, clojure.lang.BigInt. It is equivalent to Java's java.math.BigInteger:

(= (bigint 10) 10N) 
;;=> true 

Clojure strings are Java's String(java.lang.String) enclosed by double quotes (""):

"Hello world ! " 
;;=> "Hello world ! " 

Clojure has good interoperability with Java, and it's easy to call Java's member methods from Clojure. In the following example, the code calls the concat method in Java's String class:

(.concat "Hello " "world !") 
;;=> "Hello world !" 

The following syntax is how to call Java's member methods from Clojure:

(.method-name object arg1 arg2 ...) 

The first argument is a dot (.) prefix followed by the method name, then the object and its arguments.

The equivalent Java code is as follows:

String str = "Hello ".concat("world !"); 

The str function is similar to the concat method, but it can take an arbitrary number of arguments:

(str "Hello " "world !" " Clojure") 
;;=> "Hello world ! Clojure" 

To examine the length of the string, use the length method or count function:

(.length "Hello world !") 
;;=> 13 

clojure.string is a built-in Clojure library to manipulate strings. Here, we show some functions in clojure.string:

(clojure.string/blank? "   ") 
;;=> true 
(clojure.string/trim "  Hello ") 
;;=> "Hello" 
(clojure.string/upper-case "clojure") 
;;=> "CLOJURE" 
(clojure.string/capitalize "clojure") 
;;=> "Clojure" 
(clojure.string/lower-case "REPL") 
;;=> "repl" 

Let's go to Clojure character type. Characters in Clojure are java.lang.Character and are preceded by a backslash (\):

\a 
;;=> \a 

The int function gets the integer value of a character. Meanwhile, char gets an integer value from a character:

(int \a) 
;;=> 97 
(char 97) 
;;=> \a 

The seq function returns a sequence of characters from a string, and str makes a string from characters:

(seq "Hello world!") 
;;=> (\H \e \l \l \o \space \w \o \r \l \d \!) 
(str \C \l \o \j \u \r \e) 
;;=> "Clojure" 

Clojure's booleans are java.lang.Boolean, and their values are true and false:

true 
;;=> true 
false 
;;=> false 
(= 1 1) 
;;=> true 
(= 1 2) 
;;=> false 
(= "Hello" "Hello") 
;;=> true 
(= "Hello" "hello") 
;;=> false 

The not function returns true if an expression is logically false. It returns false otherwise:

(not true) 
;;=> false 
(not false) 
;;=> true 
(not= 1 2) 
;;=> true 
(not true) 
;;=> false 

The true? function returns true if the expression is true; otherwise, it returns false. The false? function returns false if the expression is true; otherwise, it returns true:

(true? (= 1 1)) 
;;=> true 
(false? (= 1 1)) 
;;=> false 

The nil function means nothing, or the absence of a value. The nil function in Clojure is almost equivalent to the null function in Java. nil is logically false in Clojure conditionals. nil is often used as a return value to indicate false:

(if nil true false) 
;;=> false 

nil is the return value used to indicate an empty sequence:

(seq []) 
;;=> nil 

nil is returned by default when a map collection looks up and can't find a given key:

(get {:a 1 :b 2} :c) 
;;=> nil 

The function def binds global symbols to their values. The next example shows the def binding the pi symbol to a value (3.14159265359):

(def pi 3.14159265359) 
;;=> #'user/pi 
pi 
;;=> 3.14159265359 
pi-not-bind 
;;=> CompilerException java.lang.RuntimeException: Unable to resolve symbol: 
;;    pi-not-bind in this context, compiling:(/tmp/form-init1426260352520034213.clj:1:7266) 

Keywords are similar to symbols, but keywords evaluate to themselves:

:key1 
;;=> :key1 

Keywords are used to identify things, so they are often used in Clojure's map:

(def person {:name "John McCarthy" :country "USA"}) 
;;=>#'living-clojure.core/person 

def is a special form that binds symbols in the global scope in their namespace. def requires var and value:

(def var val) 

This sample binds x to 100:

(def x 100) 
;;=> 100 

Whereas let binds symbols in its local scope. You can put multiple expressions in a let clause. let evaluates them and returns the last expression:

(let [var-1 val-1 var-2 val-2 ...] 
    expr-1 
    expr-2 
    .... 
    ) 

In this example, let binds x to 3 and y to 2. Then, it evaluates two expressions consecutively and returns the second expression:

(let [x 3 y 2] 
  (println "x = " x ", y = " y) 
  (* x y) 
  ) 
;;=> x =  3 , y =  2 
;;=> 6 

if takes three arguments; the third argument (else-expression) is optional:

(if condition then-expression else-expression) 

In the next example, the code returns the absolute value of numbers:

(let [x 10] 
  (if (> x 0)  x  (- x)) 
  ) 
;;=> 10 
(let [x -10] 
  (if (> x 0)  x  (- x)) 
  ) 
;;=> 10 

If there's no third parameter and if the test results as false, it returns nil:

(let [x -10] 
  (if (> x 0)  x)) 
;;=> nil 

if-not is opposite to if. It returns then-expression if the test fails:

(if-not condition then-expression else-expression) 

The example should return false:

(if-not true true false) 
;;=> false 

The when function is similar to if, but it evaluates one or more expressions if the condition is evaluated to true; otherwise, it is false:

(when condition expr-1 expr-2 ...) 

The first expression prints out x = 10 and returns 100. The second one only returns nil:

(let [x 10] 
  (when (> x 0) 
    (println "x = " x) 
    (* x x))) 
;;=> x = 10 
;;=> 100 
(let [x -10] 
  (when (> x 0) 
    (println "x = " x) 
    (* x x))) 
;;=> nil 

when-not is the opposite of when:

(when-not condition expr-1 expr-2 expr 3 ...) 

The next code uses when-not and does the same thing as the preceding function:

(let [x 10] 
  (when-not (<= x 0) 
    (println "x = " x) 
    (* x x))) 
;;=>x = 10 
;;=> 100 
(let [x -10] 
  (when-not (<= x 0) 
    (println "x = " x) 
    (* x x))) 
;;=> nil 

case tests whether there is a matched value. If so, case evaluates the corresponding expression. If there is no matched value, it returns otherwise-value. If there is no otherwise-value specified, it returns nil:

(case condition 
    value1  expr-1 
    value2  expr-2 
    otherwise-value 
    ) 

In the first expression, the condition matches the value 2 and "two" is returned. The second expression returns a string, "otherwise":

(let [x 2] 
  (case x 
    1 "one" 
    2 "two" 
    3 "three" 
    "otherwise" 
        )) 
;;=> "two" 
(let [x 4] 
  (case x 
    1 "one" 
    2 "two" 
    3 "three" 
    "otherwise" 
        )) 
;;=> "otherwise" 

cond is a macro and is similar to case. cond has been heavily used in the Lisp language. cond is more flexible than case.

cond takes a set of condition/expr pairs and evaluates each condition. If one of the conditions is true, cond evaluates the corresponding expression and returns it. Otherwise, it returns the expression of :else:

(cond 
    condition-1 expr-1 
    condition-2 expr-2 
    ... 
    :else expr-else 
    ) 

The next sample code acts the same as the preceding one:

(let [x 10] 
  (cond 
    (= x 1) "one" 
    (= x 1) "two" 
    (= x 3) "three" 
    :else "otherwise" 
        ) 
  ) 

do evaluates the expressions in order and returns the last:

(do expr-1 expr-2 ...) 

In the next sample, do evaluates the first expression and prints x = 10, then it evaluates the second and returns 11:

(def x 10) 
;;=> #'living-clojure.core/x 
(do 
  (println "x = " x) 
  (+ x 1)) 
;;=> x = 10 
;;=> 11 

dotimes repeats the expression while var increments from 0 to (number-exp - 1):

(dotimes [var number-exp] 
    expression 
) 

This example prints the square of x where x is 0 to 4:

(dotimes [x 5] 
  (println "square : " (* x x))) 
;;=> square :  0 
;;=> square :  1 
;;=> square :  4 
;;=> square :  9 
;;=> square :  16 

You may sometimes want to write a program that loops with a condition. Since Clojure is an immutable language, you cannot change a loop counter, unlike in imperative languages such as Java.

The combination of loop and recur is used in such a situation. Their forms are as follows:

(loop [var-1 val-1 var-2 val-2 ...] 
  expr-1 
  expr-2 
  ... 
  ) 
(recur expr-1 expr-2   ... ) 

The next very simple example shows how loop and recur work. In the loop, x is set to 1 and increased until it is smaller than 5:

(loop [x 1] 
  (when (< x 5) 
    (println "x = " x) 
    (recur (inc x)) 
    )  ) 
;;=> x =  1 
;;=> x =  2 
;;=> x =  3 
;;=> x =  4 
;;=> nil 

The next example calculates the sum of 1 to 10 using loop and recur:

(loop [x 1 ret 0] 
  (if (> x 10) 
    ret 
    (recur (inc x) (+ ret x))  
    ) 
) 
;;=> 55 

Clojure uses an error handler borrowed from Java:

(try exp-1 exp 2 ... 
  (catch class-of-exception var exception  
  (finally finally-expr) 
 ) 

Inside try, there are one or more expressions. finally is optional. The following example emits an exception and returns a string generated in the catch:

(try 
  (println "Let's test try ... catch ... finally") 
      (nth "Clojure" 7) 
  (catch Exception e 
      (str "exception occured: " (.getMessage e))) 
  (finally (println "test finished")) 
  ) 
;;=> Let's test try ... catch ... finally 
;;=> test finished 
;;=> "exception occured: String index out of range: 7" 

Let's start with a minimum function definition. Here is a minimal syntax of defn:

(defn funtion-name [arg1 arg2 ...] 
  expr-1  
  expr-2 
  .. 
  expr-n 
  ) 

defn is a special form. The first argument is a function name and is followed by a vector of one or more arguments, then one or more expressions. The last expression is returned to the caller.

Here, we define a very simple function. The hello function returns a Hello world string:

(defn hello [s] 
  (str "Hello world " s " !")) 
;;=> #'living-clojure.core/hello 
(hello "Nico") 
;;=> "Hello world Nico !" 
(hello "Makoto") 
;;=> "Hello world Makoto !" 

The next sample defines a simple adder function:

(defn simple-adder [x y] 
  (+ x y) 
  ) 
;;=> #'living-clojure.core/simple-adder 
(simple-adder  2 3) 
;;=> 5 

A variadic function allows a variable number of arguments. The next example defines another adder. It may have an arbitrary number of arguments:

(defn advanced-adder [x & rest] 
  (apply + (conj rest x)) 
  ) 
;;=> #'living-clojure.core/advanced-adder 
(advanced-adder 1 2 3 4 5) 
;;=> 15 

Here, we will introduce the multiple arity function. The following function defines a single argument function and a couple of argument functions with the same defn:

(defn multi-arity-hello 
  ([] (hello "you")) 
  ([name] (str "Hello World " name " !"))) 
;;=> #'living-clojure.core/multi-arty-hello 
(multi-arity-hello) 
;;=> Hello World you ! 
(multi-arity-hello "Nico") 
  ;;=> Hello World Nico ! 

Sometimes, specifying a keyword is useful, since it is not necessary to remember the order of arguments.

The next example shows how to define such a function. The options are :product-name, :price, and :description. The :or expression supplies default values if any values in keys are omitted:

(defn make-product-1 
  [serial & 
   {:keys [product-name price description] 
    :or {product-name "" price nil description "no description !"} 
    }  
   ] 
   {:serial-no serial :product-name product-name 
    :price price :description description} 
  ) 
;;=> #'living-clojure.core/make-product-1 
 
(defn make-product-2 
  [serial & 
   {:keys [product-name price description] 
    :or {:product-name "" :description "no description !"} 
    }    
   ] 
   {:serial-no serial :product-name product-name 
    :price price :description description} 
  ) 
;;=> #'living-clojure.core/make-product-2 
 
(make-product-1 "0000-0011") 
;;=> {:serial-no "0000-0011", :product-name "", :price nil, :description "no description !"} 
(make-product-2 "0000-0011") 
;;=> {:serial-no "0000-0011", :product-name nil, :price nil, :description nil} 

Clojure can define functions with pre-condition and post-condition. In the following defn, :pre checks whether an argument is positive. :post checks whether the result is smaller than 10:

(require '[clojure.math.numeric-tower :as math]) 
;;=> nil 
(math/sqrt -10) 
;;=> NaN 
(defn pre-and-post-sqrt [x] 
  {:pre  [(pos? x)] 
   :post [(< % 10)]} 
   (math/sqrt x)) 
;;=> #'living-clojure.core/pre-and-post-sqrt 
(pre-and-post-sqrt 10) 
;;=> 3.1622776601683795 
(pre-and-post-sqrt -10) 
;;=> AssertionError Assert failed: (pos? x)  user/pre-and-post-sqrt (form-init2377591389478394456.clj:1) 
(pre-and-post-sqrt 120) 
AssertionError Assert failed: (< % 10)  user/pre-and-post-sqrt (form-init2377591389478394456.clj:1) 

Moreover, in this recipe, we will show a more complicated function. The make-triangle function prints a triangle with a character. If this function is called without a :char argument, it prints a triangle made of asterisks. If it is called with a :char argument, it prints a triangle comprising characters specified by :char:

(defn make-triangle 
  [no & {:keys [char] :or {char "*"}}] 
  (loop [x 1] 
    (when (<= x no)  
      (dotimes  
          [n (- no x)] (print " ")) 
      (dotimes  
          [n  
           (if (= x 1)  
             1     
             (dec (* x 2)))] 
        (print char)) 
      (print "\n") 
      (recur (inc x)) 
      ) 
    ) 
  ) 
(make-triangle 5)     
;;=>     * 
;;=>    *** 
;;=>   ***** 
;;=>  ******* 
;;=> ********* 
;;=> nil 
(make-triangle 6 :char "x"))     
;;=>      x 
;;=>     xxx 
;;=>    xxxxx 
;;=>   xxxxxxx 
;;=>  xxxxxxxxx 
;;=> xxxxxxxxxxx 

Say we have found the following library, clj-tuples, and we want to add this to our REPL session. Most JARs for Clojure are available on either mvnrepository.com or clojars.org.

clj-tuples is on clojars, and since clojars is a regular Maven repository, we can navigate directly through the file. Download and save it (https://clojars.org/repo/ruiyun/tools.timer/1.0.1/tools.timer-1.0.1.jar), and now let's start a Clojure REPL:

java -cp .:clj-tuple-0.2.2.jar:clojure-1.8.0-beta1.jar  clojure.main

And let's quickly have fun with our new library code...mmmmm, tuples:

user=> (use 'ruiyun.tools.timer) 
; nil 
user=> (run-task!  
#(println "Say hello every 5 seconds.") :period 5000); #object[java.util.Timer 0x45a4b042 "java.util.Timer@45a4b042"] 
user=> Say hello every 5 seconds. 
   user=> (cancel! *1) 

Ok, great!

So, that was fun, but maybe you have more than one person's code you want to steal, and also, you just noticed that some of the stolen code is also stealing code from somebody else's code...what do you do?

Leiningen is a command-line tool that will, among other things, help you maintain stolen code. This recipe will not look into installing Leiningen because there is documentation all around that does this, so we just want to make sure at this stage that you have a recent version:

NicolassMacBook:chapter01 niko$ lein version

Leiningen 2.5.1 on Java 1.8.0_45 Java HotSpot(TM) 64-Bit Server VM

To make Leiningen understand what we want, most of the time, we would give it a project.clj file with a DSL that looks mostly like a gigantic Clojure map. If we want to import the same dependency as we did previously, this is the way we would write it:

(defproject chapter01 "0.1.0" 
  :dependencies  
  [[org.clojure/clojure "1.8.0-beta1"] 
   [clj-tuple "0.2.2"]]) 

At its root, declaring a dependency on a third-party library is done through this mini DSL, where a two element vector points to a name and a version:

[name "version"] 

So here:

[clj-tuple "0.2.2"] 

Dependencies are declared as Clojure vectors in the project map, with :dependencies as its key. We now have access to billions of libraries of somewhat different quality depending on the author, but anyway, it's done. Leiningen also uses clojars by default, so there's no need to define repository definitions yet. The same code as before works:

(use 'clj-tuple) 

Using the project.clj file, we can directly see what our code depends on, and in particular the version of things our code depends on. The project.clj file of clj-tuple is located at https://github.com/Ruiyun/tools.timer/blob/master/project.clj and the portion we are interested in is as follows:

(defproject clj-tuple "0.2.2" 
  :description "Efficient small collections." 
  :dependencies [] 
  ...) 

This means that clj-tuples does not depend on anything else and is a well behaved self-contained library.

This is obviously not always the case, and while we are at it we can look at another library, named puget.

Puget has the following dependencies defined:

:dependencies 
    [[fipp "0.6.2"] 
    [mvxcvi/arrangement "1.0.0"] 
    [org.clojure/clojure "1.8.0"]] 

But the great thing is that we don't need to write all those dependency lines ourselves. Transitive dependencies are pulled properly by Leiningen, so our project.clj file will now look simply like this:

(defproject chapter01 "0.1.0" 
  :dependencies [ 
                 [org.clojure/clojure "1.8.0-beta1"] 
                [clj-tuple "0.2.2"]                  
                 [mvxcvi/puget "0.9.1"]]) 

The first time we launch a new REPL we will notice all the dependencies being downloaded:

NicolassMacBook:chapter01 niko$ lein repl 
Retrieving mvxcvi/puget/0.9.1/puget-0.9.1.pom from clojars 
Retrieving fipp/fipp/0.6.2/fipp-0.6.2.pom from clojars 
Retrieving org/clojure/core.rrb-vector/0.0.11/core.rrb-vector-0.0.11.pom from central 
Retrieving mvxcvi/arrangement/1.0.0/arrangement-1.0.0.pom from clojars 
Retrieving org/clojure/core.rrb-vector/0.0.11/core.rrb-vector-0.0.11.jar from central 
Retrieving fipp/fipp/0.6.2/fipp-0.6.2.jar from clojars 
Retrieving mvxcvi/arrangement/1.0.0/arrangement-1.0.0.jar from clojars 
Retrieving mvxcvi/puget/0.9.1/puget-0.9.1.jar from clojars     

This only applies the first time. The second time it occurs without extra messages, and you can now check for yourself that the library is there, and you get the expected colorized output, but not in this book:

user=> (require '[puget.printer :as puget]) 
nil 
user=> (puget/pprint #{'x :a :z 3 1.0}) 
#{1.0 3 :a :z x} 
nil 
user=> (puget/cprint #{'x :a :z 3 1.0}) 
#{1.0 3 :a :z x} 

Sometimes it is great to just try things out, and have a one-off REPL to try out the new dependencies. This is where we can use a Leiningen plugin named try.

Plugins for Leiningen can be installed globally on your machine with a file named profiles.clj located here:

$HOME/.lein/profiles.clj

The file is a simple map with user-defined settings; here, we just want to add a plugin, so we add it to the vector:

{:user {:plugins [ [lein-try "0.4.3"] ]}} 

That's it. From anywhere on your computer you can now try dependencies. To make things new, we will look at a new useful dependency named env, which makes it easy to retrieve environment settings.

This is the usual Leiningen definition of env, and the following code would be used in project.clj, as seen before:

[adzerk/env "0.2.0"] 

Here, we just type the following:

lein try adzerk/env  

And we can see the dependencies coming along locally (provided you have an Internet connection):

Retrieving adzerk/env/0.2.0/env-0.2.0.pom from clojars 
Retrieving adzerk/env/0.2.0/env-0.2.0.jar from clojars 

And we can now use the require macro:

(require '[adzerk.env :as env]) 

And try it. env returns all the env variables available, whether through Java or Shell:

user=> (env/env) 
; ... 

If you have the chance to run the preceding command where project.clj was located, the dependencies from the project are also available, so we can combine dependencies:

user=> (require '[puget.printer :as puget]) 
 
user=> (puget/cprint (env/env))  
{"Apple_PubSub_Socket_Render" "/private/tmp/com.apple.launchd.jI7P2DRL6X/Render", 
 "HOME" "/Users/niko", 
 "JAVA_ARCH" "x86_64", 
 "JAVA_CMD" "java", 
 "JAVA_MAIN_CLASS_3927" "clojure.main", 
 "JVM_OPTS" "", 
 ... 

Voila! Now we have combined a temporary dependency with our main project dependencies.

So far we have seen how to add dependencies offline, in the sense that we need to stop our REPL in order for the new dependencies to be handled properly. Now we will see how to add a dependency on the fly.

The dependency we will look at now is named pomegranate and it does just that, add dependencies on the fly.

In the same way we added a Leiningen plugin earlier on, we will add a global dependency to our runtimes by adding a dependency to the same profiles.clj file:

{:user  
    {:dependencies  
    [[com.cemerick/pomegranate "0.3.0"]] }} 

Those dependencies will be ready to be loaded through all your Leiningen-based projects, so be careful not to add too many. With a new REPL loaded, we can now load pomegranate, and the only method we need is happily named add-dependencies:

(require '[cemerick.pomegranate :refer [add-dependencies]])  

The newly required function takes a vector of coordinates using the same pattern we have seen so far, and a map of repositories, with a name for the key and a URL to a Maven-like repository for the value:

(add-dependencies  
                 :coordinates '[[active-quickcheck "0.3.0"]] 
                 :repositories  {"clojars" "http://clojars.org/repo"}) 

The first time this is called, the dependency and all the underlying will be downloaded and be ready for use. We took active-quickcheck as a sample, a library that can be used to generate random tests based on some given predicates. The library still needs to be required in the current namespace:

(use 'active.quickcheck) 
 
; sample dependency test, we will not go in the details here 
(quickcheck (property [a integer 
                   b integer] 
           (= (+ a b) (+ b a)))) 

So we have pretty much seen all the different ways to add dependencies to our Clojure environment, whether through:

We start here by looking at how namespaces are created. While working in the REPL, making changes to or creating a namespace mostly resorts to using the in-ns function from clojure.core:

(in-ns 'hello) 

And next time we define a var using def, we see it bound to that namespace:

hello=> (in-ns 'hello) 
#object[clojure.lang.Namespace 0x3b5fad2d "hello"] 
hello=> (def a 1) 
#'hello/a 

Great. Now, since the function resolves to var as well, we can define the function in our namespace. We need to give the full path to fn now to define the definition, so clojure.core/fn:

hello=> (def b (clojure.core/fn[c] (clojure.core/inc c))) 
#'hello/b 
hello=> (b 2) 
3 

Namespaces are regular objects, so on the JVM we can see their internals very easily. find-ns tells us what the object is, and on the JVM we then call .getMappings from the namespace object:

(find-ns 'hello) 
; #object[clojure.lang.Namespace 0x3b5fad2d "hello"] 
(.getMappings *1) 
.... 

Namespaces are listed and retained statically in a static field of this class on the JVM so we can refer to things later.

While in-ns helps us define namespaces, we will actually use a higher-level function named ns:

helloagain=> (ns helloagain) 
nil 
helloagain=>  

If you want to go and have a look, ns actually does quite a bit for us. The two main keywords that can be used are imports and refers.

:import will import classes from the hosting virtual machine (JVM, JavascriptVM, and .NET VM for now). Say in Java we want to use the raw Random Java object directly, we will import it in the namespace with the following:

(ns helloagain (:import [java.util Random])) 
(Random.) 
; #object[java.util.Random 0x6337c201 "java.util.Random@6337c201"] 

We can also check the imports defined in each namespace with ns-imports:

(ns-imports 'helloagain) 
;...  

By default, Clojure does some work for us, to make sure the basic Java objects are already available in each new namespace.

In the same way as we can import Java objects, we can go along and require other Clojure namespaces in the current namespace. This is done through the :require keyword in the namespace definition:

helloagain=>  (ns helloagain (:require [clojure.string :refer :all])) 
WARNING: reverse already refers to: #'clojure.core/reverse in namespace: helloagain, being replaced by: #'clojure.string/reverse 
WARNING: replace already refers to: #'clojure.core/replace in namespace: helloagain, being replaced by: #'clojure.string/replace 
nil 
helloagain=> (reverse "helloagain") 
"niagaolleh" 

The newly referred functions can be seen using ns-refers:

(ns-refers 'helloagain) 
; ... (somewhere clojure.string ...)     

Now, effectively, the ns calls will mostly be located at the top of each file. Let's say we want to keep the code we have now on this helloagain namespace; we will create a helloagain.clj file and copy the following content:

(ns helloagain  
      (:import [java.util Random]) 
     (:require [clojure.string :refer :all])) 
 
(println  
     (clojure.string/reverse (str (.getName *ns*)))) 
 
 (println (Random.)) 

The namespace and thus the file can be loaded through require. For this to work, we need to validate our classpath, so let's review the way we started the REPL earlier on:

java -cp .:clojure-1.8.0-beta1.jar clojure.main  

The . makes the files in the current folder available on the classpath, so then require can look through the defined classpath and find the file helloagain.clj we have just defined:

user=>  (require 'helloagain) 
niagaolleh 
nil 
user=>  

You will notice the code is executed when calling require on the command line. The ' is required because helloagain should not be evaluated, but instead kept as a symbol.

Now, here's something slightly more complicated. We want to add a function to the helloagain namespace:

(defn only-one [] 
   (println "only one")) 

We want to use this function in a different user namespace, so we can call the ns macro again to do this, or we can also use require directly. Supposing we have added the preceding function to our filename; simply calling require should do it for us:

user=> (require 'helloagain)  
nil 
user=>  (helloagain/only-one) 
CompilerException java.lang.RuntimeException: No such var: helloagain/only-one, compiling:(NO_SOURCE_PATH:4:2)  

Or not. What happened there? The file was not reloaded from disk, and we just got a reference to the already created namespace. The :reload keyword gives us a chance to specify that we want to reload from disk:

(require 'helloagain :reload) 
user=> (helloagain/only-one) 
; only one 

IDEs such as IntelliJ will actually, most of the time, reload the full current file from the buffer, and so the definition of the namespace can be updated.

When loading and reloading namespaces, state management becomes problematic, so we will focus on that a little bit later.

There is great science and research being done on how to organize namespaces; even Albert Einstein had a biweekly meeting to make sure namespaces would be organized in a compatible way.

Here is a list that will help you focus on creating namespaces around coherent goals:

A public API namespace will have well defined contracts and extensive documentation, while low-level functions maybe be more tested but could be less well documented.

Some people have suggested grouping functions depending on the kind of data they are handling. This is also good when you do not have to deal with the relationships of those namespaces; for example, you defined a User namespace and a ShoppingList namespace, but then Users with many ShoppingList items make the relationship management between the two namespaces cumbersome. Only use this way of organization if the data handled is straightforward and simple.

Possibly the most interesting motivation to separate namespaces is the public API method.

potemkin has a very interesting method, named import-vars, that allows something like a copy/paste of a function from a different namespace to a current one. If we remember the previous recipe, we can simply try the potemkin dependency as follows:

lein try potemkin "0.4.1" 

Then we can select on-demand functions and clean up our public-facing namespace:

user=> (require 'potemkin) 
(potemkin/import-vars [clojure.string reverse]) 
 (user/reverse "hello")  

This makes selecting functions for our namespace clean, without any code, mostly documentation.

This also makes a case for versioning our namespace, in case some breaking changes are introduced but there is no need to make a completely new version of your code.

Now, we saw just a few moments ago that we can force :reload on a namespace, but things get complicated when namespaces depend on each other, and you are not sure which one was reloaded and which one was not. This is where tools.namespace makes it easier for you to track all this for you. Let us start a REPL and try this out:

lein try org.clojure/tools.namespace "0.2.11" 

As per the doc, the refresh function will scan all the directories on the classpath for Clojure source files, read their ns declarations, build a graph of their dependencies, and load them in dependency order. (You can change the directories it scans with set-refresh-dirs.)

So, at the REPL, the function we mostly need from tools.namespace is refresh:

(require '[clojure.tools.namespace.repl :refer [refresh]]) 

Now, supposing our file helloagain.clj is in the src folder so, src/helloagain.clj, and lein can find and load the file with require:

(require '[helloagain :refer :all]) 
user=> (only-one) 
only one 

We will quickly add a new function to our file:

 (defn only-two [] 
    (println "only two"))   

And call refresh to make sure we have the latest code:

user=> (refresh) 
; :reloading (helloagain) 
user> (helloagain/only-two) 
; only two 

And that is all. We have pulled the latest from our namespace code, and the required namespaces will be reloaded as needed.