Navigating Clojure Libraries

Clojure code is packaged in libraries. Each Clojure library belongs to a namespace, which is analogous to a Java package. You can load a Clojure library with require:

When you require a library named clojure.java.io, Clojure looks for a file named clojure/java/io.clj on the CLASSPATH. Try it:

The leading single quote (’) is required, and it quotes the library name. The nil returned indicates success. While you’re at it, test that you can load the sample code for this chapter, examples.introduction:

The examples.introduction library includes an implementation of the Fibonacci numbers, which is the traditional “Hello World” program for functional languages. We’ll explore the Fibonacci numbers in more detail in ​How to Be Lazy​. For now, just make sure you can execute the sample function fibs. Enter the following line of code at the REPL to take the first 10 Fibonacci numbers:

If you see the first 10 Fibonacci numbers as listed here, you have successfully installed the book samples.

The book samples are all unit tested, with tests located in the examples/test directory. The tests for the samples themselves are not explicitly covered in the book, but you may find them useful for reference.

Often you can find the documentation you need right at the REPL. The most basic helper function (a macro) is doc:

Use doc to print the documentation for str:

The first line of doc’s output contains the fully qualified name of the function. The next line contains the possible argument lists, generated directly from the code. (Some common argument names and their uses are explained in ​Conventions for Parameter Names​.) Finally, the remaining lines contain the function’s doc string, if the function definition included one.

You can add a doc string to your own functions by placing it immediately after the function name:

Sometimes you won’t know the exact name you want documentation for. The find-doc function will search for anything whose doc output matches a regular expression or string you pass in:

Use find-doc to explore how Clojure does reduce:

reduce reduces Clojure collections and is covered in ​Transforming Sequences​. areduce is for interoperation with Java arrays and is covered in ​Using Java Arrays​.

Much of Clojure is written in Clojure, and it is instructive to read the source code. You can view the source of a Clojure function using the repl library.

Try viewing the source of the simple identity function:

Of course, you can also use Java’s Reflection API. You can use methods, such as class, ancestors, and instance?, to reflect against the underlying Java object model and tell, for example, that Clojure’s collections are also Java collections:

Clojure’s complete API is documented at https://clojure.github.io/clojure. The right sidebar links to all functions and macros by name, and you can find a helpful grouping of functions in the Clojure Cheatsheet.^[12]