Whenever you are working at the Clojure REPL, the REPL prompt tells you that you are "in" a particular namespace. Clojure always starts in the user namespace:

user=>

Any symbols you define will be created in the user namespace. You can switch to a different namespace with the in-ns function:

user=> (in-ns 'greetings)
#<Namespace greetings>
greetings=>

in-ns takes a symbol argument, and switches to the namespace named by the symbol, creating it if it does not already exist. Please notice in the example that the symbol greetings was quoted to prevent Clojure from trying to evaluate it.

A newly-created namespace does not have any symbols in it, not even the core language functions. If you try to call a built-in Clojure function, you will get an error:

greetings=> (println "Hello, World!")
java.lang.Exception: Unable to resolve symbol: println in this context

Clojure's built-in functions are defined in the namespace clojure.core, and you can refer to them from your new namespace by qualifying the symbols with their namespace:

greetings=> (clojure.core/println "Hello, World!")
Hello, World!
nil

To avoid having to qualify all the symbols you use, you can refer another namespace with the refer function, which is also defined in clojure.core:

greetings=> (clojure.core/refer 'clojure.core)
nil

Now you can call functions in clojure.core directly, without qualification:

greetings=> (println "Hello, World!")
Hello, World!
nil

refer takes a symbol argument and maps all the public symbols from that namespace into the current namespace. (We will cover the difference between public and private symbols later in the section "Public and Private Vars.") The symbols are still mapped to the values in their original namespace. By calling refer in the example, you created a namespace mapping from the symbol greetings/println to the Var # 'clojure .core/println.

refer takes additional options that specify filters for the symbols to be referred. The options take the form of a keyword followed by a list or map of symbols. The :exclude option is followed by a (quoted) list of symbols that should not be referred into the current namespace. For example, the following code:

(refer 'clojure.core :exclude '(map set))

This refers all the symbols in the clojure.core namespace, except map and set. You can then define your own versions of map and set that do not clash with the original definitions in clojure.core.

The :only option is also followed by a list of symbols, but it specifies that only the symbols in the list you specify should be referred into the current namespace. For example, the following code:

(refer 'clojure.core :only '(println prn))

This refers only the two symbols println and prn from clojure.core; other symbols in clojure.core must still be namespace-qualified, like clojure.core/def.

Lastly, refer allows you to rename some symbols when referring them, by including the :rename keyword followed by a map from symbols in the original namespace to symbols in the current namespace.

(refer 'clojure.core :rename {'map 'core-map, 'set 'core-set})

This refers all symbols from clojure.core, but makes the symbol clojure.core/map available in the current namespace as core-map and clojure.core/set available as core-set. This might be useful if you want to define your own version of a built-in function that calls the original version.

As an alternative to copying the mappings from one namespace, you can create a local alias to another namespace, so you can refer to it by a shorter name. Namespace aliases are created with the alias function:

(alias local-name namespace-name)

The arguments local-name and namespace-name are both (quoted) symbols. alias creates an alias in the current namespace to the named namespace. After calling alias, you can reference symbols in the other namespace using local-name, instead of the full namespace name. For example, the following code:

greetings> (alias 'set 'clojure.set)
nil
greetings> (set/union #{1 3 5} #{2 3 4})
#{1 2 3 4 5}

The simplest load function is load-file:

(load-file name)

load-file takes one argument, a file name, and attempts to read and evaluate every Clojure form in the file. The file name is given as a String, including any directories, and is interpreted in the context of the current working directory (the directory in which you started Clojure). On a Unix-like system, it might look like the following:

(load-file "path/to/file.clj")

On Windows, back-slashes must be escaped, because the file name is a String:

(load-file "C:\Documents\file.clj")

If you want to load code from some other source, such as a network connection, you can use the load-reader function, which takes a java.io.Reader as its argument, and reads and evaluates code from the Reader.

The Java Virtual Machine uses a special variable called the classpath, a list of directories from which to load executable code. Clojure programs also use the classpath to search for source files.

The classpath is normally specified on the Java command line as a set of directories and JAR files. The following example, for Unix-like systems, creates a classpath consisting of the Clojure JAR and the / code/sources directory.

java -cp clojure.jar:/code/sources clojure.main

Java development environments and build-management tools usually have their own methods for configuring the classpath; consult your tools' documentation for more information.

(load "/com/example/my_library")

greetings=> (load "hello")

(require 'com.example.lib)

(require '[com.example.lib :as lib])

(require 'com.example.one 'com.example.two 'com.example.three)

(require '(com.example one two three))

(require '(com.example one [two :as t]))

(require 'com.example.one 'com.example.two :reload)

user=> (require '(clojure zip [set :as s]) :verbose)
(clojure.core/load "/clojure/zip")
(clojure.core/load "/clojure/set")
(clojure.core/in-ns 'user)
(clojure.core/alias 's 'clojure.set)
nil

Frequently, you may want to require a namespace and also refer certain symbols in it. The use function makes this a one-step operation. Calling use is equivalent to calling require and then refer. use accepts the :reload, :reload-all, and :verbose flags of require; and also the :exclude, :only, and :rename options of refer, grouped in a vector with the namespace they affect. For example, see the following line of code:

(use '[com.example.library :only (a b c)] :reload-all :verbose)

This (re)loads the namespace com.example.library and refers the three symbols a, b, and c into the current namespace. Note that you do not need to quote the list (a b c) because the entire vector is already quoted.

The last namespace function deals with Java classes. You can always refer to a Java class by its fully-qualified name, such as java.util.Date. To refer to a class without its package, you can import it.

user=> (import 'java.util.Date) nil
user=> (new Date)
#<Date Fri Oct 23 16:31:28 EDT 2009>

In Clojure 1.0, import is a function, so you must quote its arguments, as in the example. Starting with Clojure 1.1, import is a macro, and its arguments do not need to be quoted. import also accepts prefix lists similar to require and use. The prefix must be a complete Java package name; the class name may not contain periods.

(import '(java.util.regex Pattern Matcher))

As a special case, nested Java classes (sometimes called "inner classes") must be imported using their binary class name, which the JVM uses internally. The binary class name of an inner class consists of the outer class name, followed by a $ sign, followed by the inner class name. For example, the binary name of a class Wheel nested inside a class Truck is Truck$Wheel.

In Clojure, a nested Java class cannot be named without its enclosing class. For example, to import the nested class javax.swing.Box.Filler, you must do this:

(import '(javax.swing Box$Filler))

After that import, you can refer to the class as Box$Filler.

Like most Clojure objects, namespaces can have metadata (see Chapter 8) attached to them. You can add metadata to the namespace by placing read-time metadata on the symbol in the ns macro, like this:

(ns #^{:doc "This is my great library."
      :author "Mr. Quux <[email protected]>"
   com.example.my-great-library)

While Clojure does not specify any "official" metadata keys for namespaces (like :tag and :arglists for functions) many Clojure library developers have adopted the convention of using :doc metadata to describe the general purpose of a namespace and :author metadata for the author's name and e-mail address.

The Clojure compiler requires that symbols be defined before they are used. Usually this leads to organizing your source files with simple, low-level functions at the top and more complex functions at the bottom. But sometimes, you need to use a symbol before it can be defined. To prevent the compiler from throwing an Exception, you must use a forward declaration.

(declare & symbols)

A forward declaration is created with the declare macro, which simply tells the compiler, "This symbol exists, it will be defined later." Here is a contrived, and very inefficient, example:

(declare is-even? is-odd?)

(defn is-even? [n]
  (if (= n 2) true
     (is-odd? (dec n))))

(defn is-odd? [n]
  (if (= n 3) true
     (is-even? (dec n))))

As you saw earlier, symbols can be qualified with a namespace. The functions name and namespace return the strings representing each part of the symbol:

user=> (name 'com.example/thing)
"thing"
user=> (namespace 'com.example/thing)
"com.example"

Notice that the symbol is quoted to prevent Clojure from trying to resolve it as a class or Var.

The namespace function returns nil for unqualified symbols, which have no namespace:

user=> (namespace 'stuff)
nil

Keywords, too, can be namespace-qualified; the name and namespace functions work as on symbols:

user=> (name :com.example/mykey)
"mykey"
user=> (namespace :com.example/mykey)
"com.example"
user=> (namespace :unqualified)
nil

As a syntactic convenience, you can create keywords in the current namespace by preceding their names with two colons instead of one. In the "user" namespace, the keyword ::thing expands to :user/thing.

user=> (namespace ::keyword)
"user"

Although not explicitly for this purpose, the backquote ` reader macro can be used to create qualified symbols in the current namespace:

user=> `sym
user/sym

The name and namespace functions convert from symbols or keywords to strings. The symbol and keyword functions go the other way: given Strings for the name and, optionally, a namespace, they construct a symbol or keyword.

user=> (symbol "hello")
hello
user=> (symbol "com.example" "hello")
com.example/hello
user=> (keyword "thing")
:thing
user=> (keyword "user" "goodbye")
:user/goodbye

Note that the name given to the keyword function does not include the leading colon.

By default, all definitions in a namespace are public, meaning they can be referenced from other namespaces and copied with refer or use. But many namespaces can be divided into two parts: one set of "internal" functions that should never be called from any other namespace and another set of "public" functions meant for use by other namespaces. These correspond, loosely, to the private and public methods of object-oriented languages like Java.

Private Vars in Clojure will never be copied by refer or use, and they cannot be referenced with a namespace-qualified symbol. In effect, they can only be used in the namespace in which they were defined.

There are two ways to create a private Var. The first is the defn- macro, which works exactly like defn but creates a private function definition. The second, which works for any definition, is to add :private metadata to the symbol you are defining.

(def #^{:private true} *my-private-value* 123)

Note that private Vars are never truly hidden; any code can get the value of the Var with (deref (var namespace/name)). But private Vars prevent you from inadvertently calling a function that you did not mean to be used by other parts of your application.

The special Var *ns* is always bound to the current namespace. It is changed with in-ns.

The function all-ns takes no arguments and returns a sequence of all namespaces currently defined.

Two functions help you get from a symbol naming a namespace to the namespace object itself. The find-ns function takes a symbol argument and returns the namespace with that name; or nil if no such namespace exists.

Often, you don't care if you're dealing with a namespace object directly or just the symbol naming it. For this purpose, a function called the-ns will accept either a namespace object, in which case it just returns the namespace; or a symbol, in which case it calls find-ns. Unlike find-ns, the-ns throws an Exception if the namespace does not exist. Most of the functions in this section call the-ns on their argument, so they may be called with either a namespace object (such as *ns*) or a quoted symbol.

The ns-name function returns the name of a namespace as a symbol.

The ns-aliases function returns a map, from symbols to namespaces, representing all the namespace aliases defined in a namespace.

The ns-map function returns a map, from symbols to objects (Vars or classes), representing all the mappings in a namespace. Usually, this is more information than you want, so Clojure provides several auxiliary functions that return a subset of the mappings for a namespace. ns-publics returns mappings for all public Vars; ns-interns returns mappings for all Vars (both public and private); ns-refers returns mappings for all symbols referred from other namespaces; and ns-imports returns mappings for all Java classes.

For example, to get a list of all the public symbols in the clojure.core namespace, you can run:

(keys (ns-publics 'clojure.core))

Finally, you may want to find out what a symbol will resolve to when it is encountered in a particular context. The ns-resolve function takes a namespace and a symbol, and returns the Var or class to which that symbol is mapped in the namespace. For example, clojure.core imports the java.math.BigDecimal class, which you can discover by calling:

user> (ns-resolve 'clojure.core 'BigDecimal)
java.math.BigDecimal

As a shortcut, the resolve function is equivalent to ns-resolve for the current namespace.

The in-ns function and ns macro both create a namespace and make it the current namespace. Likewise, def and its relatives all operate in the current namespace. There are some special cases, like code generation, where you want to create a namespace and define things in it without switching to it. You may be tempted to write something like this:

;; Bad code!
(let [original (ns-name *ns*)]
  (ns other)
  (defn f [] (println "Function f")
  (in-ns original)))

That won't work, because Clojure reads the symbol f in the current namespace before evaluating the ns form. You'll end up with f defined in the current namespace, not the other namespace.

Instead, you can use the create-ns function, which takes a symbol argument and returns a new namespace with that name (or returns an existing namespace with that name). Then you can use the intern function to define Vars in that namespace. Here's a version of the previous example that actually works:

(let [other-ns (create-ns 'other)]
  (intern other-ns 'f
          (fn [] (println "Function f"))))

The act of creating a Var and mapping it to a symbol in a namespace is called interning the Var, and that's exactly what the intern function does.

(intern namespace symbol value)

The value is optional; if it is omitted, the Var is created with no root value, similar to a forward declaration. The symbol must be a bare symbol, that is, without a namespace-qualifying prefix. The namespace argument may be either a symbol or a namespace.

The ns-unmap function is the opposite of intern; it removes a mapping from a namespace. For example, every Clojure namespace, regardless of how it is created, starts with mappings for all the classes in the java.lang package. If you wanted a completely empty namespace, you could create one like this:

(let [empty-ns (create-ns 'empty)]
  (doseq [sym (keys (ns-map empty-ns))]
    (ns-unmap empty-ns sym))
  empty-ns)

Finally, the remove-ns function will delete a namespace entirely, including all the Vars interned in it. Note that code in other namespaces may still hold references to those Vars in closures, but the Vars themselves are cleared, so any attempt to use them will throw an "unbound Var" Exception.