Table of Contents

Important Clojure resources

• The official source code for clojure is on the Clojure GitHub source page.
• Clojure provides a Java API for invoking Clojure from Java. You can browse the javadoc for the API athttps://clojure.github.io/clojure/javadoc.
• Issues related to Clojure and the various pieces of functionality within it are discussed in the Clojure Google group.
• Discussions among Clojure developers take place in the Clojure Dev Google group.
• Development planning, design, and documentation happen in the Confluence Clojure space.
• Issue tracking happens on the the Clojure JIRA site.
• This documentation is maintained in the gh-pages branch of Clojure on GitHub and is always available online GitHub pages for Clojure. If you wish to have a version for off-line use you can use the download button on the gh-pages branch page at GitHub.

clojure.core

Fundamental library of the Clojure language

clojure.data

Non-core data functions.

clojure.datafy

Functions to turn objects into data. Alpha, subject to change

clojure.edn

edn reading.

clojure.inspector

Graphical object inspector for Clojure data structures.

clojure.instant

clojure.java.basis

The lib basis includes which libraries and versions were loaded bothfor direct dependencies and transitive dependencies, as well as theclasspath and possibly other information from the resolution process.This basis will be known if the runtime was started by the Clojure CLI.The Clojure CLI or tools.deps merge a set of deps maps (often fromdeps.edn files). Additional runtime modifications are supplied via argmapkeys, provided via alias maps in the merged deps. Deps maps typically have:paths, :deps, and :aliases keys.The basis is a superset of merged deps.edn files with the followingadditional keys:  :basis-config - params used to configure basis deps sources, can be                  string path, deps map, nil, or :default    :root - default = loaded as a resource from tools.deps)    :user - default = ~/.clojure/deps.edn)    :project - default = ./deps.edn)    :extra - default = nil    :aliases - coll of keyword aliases to include during dep calculation  :argmap - effective argmap (after resolving and merging argmaps from aliases)  :libs - map of lib to coord for all included libraries  :classpath - classpath map, keys are paths (to directory or .jar), values               are maps with source identifier (either :lib-name or :path-key)  :classpath-roots - vector of paths in classpath order (keys of :classpath)

clojure.java.browse

Start a web browser from Clojure

clojure.java.io

This file defines polymorphic I/O utility functions for Clojure.

clojure.java.javadoc

A repl helper to quickly open javadocs.

clojure.java.process

A process invocation API wrapping the Java process API.The primary function is 'start' which starts a process and handles thestreams as directed. It returns the Process object. Use 'exit-ref' to waitfor completion and receive the exit value, and ‘stdout', 'stderr', 'stdin'to access the process streams. The 'exec' function handles the common caseto 'start' a process, wait for process exit, and return stdout.

clojure.java.shell

Conveniently launch a sub-process providing its stdin andcollecting its stdout

clojure.main

Top-level main function for Clojure REPL and scripts.

clojure.math

Clojure wrapper functions for java.lang.Math static methods.Function calls are inlined for performance, and type hinted for primitivelong or double parameters where appropriate. In general, Math methods areoptimized for performance and have bounds for error tolerance. Ifgreater precision is needed, use java.lang.StrictMath directly instead.For more complete information, see:https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html

clojure.pprint

A Pretty Printer for Clojureclojure.pprint implements a flexible system for printing structured datain a pleasing, easy-to-understand format. Basic use of the pretty printer is simple, just call pprint instead of println. More advanced users can use the building blocks provided to create custom output formats. Out of the box, pprint supports a simple structured format for basic data and a specialized format for Clojure source code. More advanced formats, including formats that don't look like Clojure data at all like XML and JSON, can be rendered by creating custom dispatch functions. In addition to the pprint function, this module contains cl-format, a text formatting function which is fully compatible with the format function in Common Lisp. Because pretty printing directives are directly integrated withcl-format, it supports very concise custom dispatch. It also providesa more powerful alternative to Clojure's standard format function.See documentation for pprint and cl-format for more information or complete documentation on the Clojure web site on GitHub.

clojure.reflect

Reflection on Host TypesAlpha - subject to change.Two main entry points: * type-reflect reflects on something that implements TypeReference.* reflect (for REPL use) reflects on the class of an instance, or  on a class if passed a classKey features:* Exposes the read side of reflection as pure data. Reflecting  on a type returns a map with keys :bases, :flags, and :members.* Canonicalizes class names as Clojure symbols. Types can extend  to the TypeReference protocol to indicate that they can be  unambiguously resolved as a type name. The canonical format  requires one non-Java-ish convention: array brackets are <>  instead of [] so they can be part of a Clojure symbol.* Pluggable Reflectors for different implementations. The default  JavaReflector is good when you have a class in hand, or use  the AsmReflector for "hands off" reflection without forcing  classes to load.Platform implementers must:* Create an implementation of Reflector.* Create one or more implementations of TypeReference.* def default-reflector to be an instance that satisfies Reflector.

clojure.repl

Utilities meant to be used interactively at the REPL

clojure.set

Set operations such as union/intersection.

clojure.stacktrace

Print stack traces oriented towards Clojure, not Java.

clojure.string

Clojure String utilitiesIt is poor form to (:use clojure.string). Instead, use requirewith :as to specify a prefix, e.g.(ns your.namespace.here  (:require [clojure.string :as str]))Design notes for clojure.string:1. Strings are objects (as opposed to sequences). As such, the   string being manipulated is the first argument to a function;   passing nil will result in a NullPointerException unless   documented otherwise. If you want sequence-y behavior instead,   use a sequence.2. Functions are generally not lazy, and call straight to host   methods where those are available and efficient.3. Functions take advantage of String implementation details to   write high-performing loop/recurs instead of using higher-order   functions. (This is not idiomatic in general-purpose application   code.)4. When a function is documented to accept a string argument, it   will take any implementation of the correct *interface* on the   host platform. In Java, this is CharSequence, which is more   general than String. In ordinary usage you will almost always   pass concrete strings. If you are doing something unusual,   e.g. passing a mutable implementation of CharSequence, then   thread-safety is your responsibility.

clojure.template

Macros that expand to repeated copies of a template expression.

clojure.test

A unit testing framework.ASSERTIONSThe core of the library is the "is" macro, which lets you makeassertions of any arbitrary expression:(is (= 4 (+ 2 2)))(is (instance? Integer 256))(is (.startsWith "abcde" "ab"))You can type an "is" expression directly at the REPL, which willprint a message if it fails.    user> (is (= 5 (+ 2 2)))    FAIL in  (:1)    expected: (= 5 (+ 2 2))      actual: (not (= 5 4))    falseThe "expected:" line shows you the original expression, and the"actual:" shows you what actually happened.  In this case, itshows that (+ 2 2) returned 4, which is not = to 5.  Finally, the"false" on the last line is the value returned from theexpression.  The "is" macro always returns the result of theinner expression.There are two special assertions for testing exceptions.  The"(is (thrown? c ...))" form tests if an exception of class c isthrown:(is (thrown? ArithmeticException (/ 1 0))) "(is (thrown-with-msg? c re ...))" does the same thing and alsotests that the message on the exception matches the regularexpression re:(is (thrown-with-msg? ArithmeticException #"Divide by zero"                      (/ 1 0)))DOCUMENTING TESTS"is" takes an optional second argument, a string describing theassertion.  This message will be included in the error report.(is (= 5 (+ 2 2)) "Crazy arithmetic")In addition, you can document groups of assertions with the"testing" macro, which takes a string followed by any number ofassertions.  The string will be included in failure reports.Calls to "testing" may be nested, and all of the strings will bejoined together with spaces in the final report, in a stylesimilar to RSpec <http://rspec.info/>(testing "Arithmetic"  (testing "with positive integers"    (is (= 4 (+ 2 2)))    (is (= 7 (+ 3 4))))  (testing "with negative integers"    (is (= -4 (+ -2 -2)))    (is (= -1 (+ 3 -4)))))Note that, unlike RSpec, the "testing" macro may only be usedINSIDE a "deftest" or "with-test" form (see below).DEFINING TESTSThere are two ways to define tests.  The "with-test" macro takesa defn or def form as its first argument, followed by any numberof assertions.  The tests will be stored as metadata on thedefinition.(with-test    (defn my-function [x y]      (+ x y))  (is (= 4 (my-function 2 2)))  (is (= 7 (my-function 3 4))))As of Clojure SVN rev. 1221, this does not work with defmacro.Seehttp://code.google.com/p/clojure/issues/detail?id=51The other way lets you define tests separately from the rest ofyour code, even in a different namespace:(deftest addition  (is (= 4 (+ 2 2)))  (is (= 7 (+ 3 4))))(deftest subtraction  (is (= 1 (- 4 3)))  (is (= 3 (- 7 4))))This creates functions named "addition" and "subtraction", whichcan be called like any other function.  Therefore, tests can begrouped and composed, in a style similar to the test framework inPeter Seibel's "Practical Common Lisp"<http://www.gigamonkeys.com/book/practical-building-a-unit-test-framework.html>(deftest arithmetic  (addition)  (subtraction))The names of the nested tests will be joined in a list, like"(arithmetic addition)", in failure reports.  You can use nestedtests to set up a context shared by several tests.RUNNING TESTSRun tests with the function "(run-tests namespaces...)":(run-tests 'your.namespace 'some.other.namespace)If you don't specify any namespaces, the current namespace isused.  To run all tests in all namespaces, use "(run-all-tests)".By default, these functions will search for all tests defined ina namespace and run them in an undefined order.  However, if youare composing tests, as in the "arithmetic" example above, youprobably do not want the "addition" and "subtraction" tests runseparately.  In that case, you must define a special functionnamed "test-ns-hook" that runs your tests in the correct order:(defn test-ns-hook []  (arithmetic))Note: test-ns-hook prevents execution of fixtures (see below).OMITTING TESTS FROM PRODUCTION CODEYou can bind the variable "*load-tests*" to false when loading orcompiling code in production.  This will prevent any tests frombeing created by "with-test" or "deftest".FIXTURESFixtures allow you to run code before and after tests, to set upthe context in which tests should be run.A fixture is just a function that calls another function passed asan argument.  It looks like this:(defn my-fixture [f]   Perform setup, establish bindings, whatever.  (f)  Then call the function we were passed.   Tear-down / clean-up code here. )Fixtures are attached to namespaces in one of two ways.  "each"fixtures are run repeatedly, once for each test function createdwith "deftest" or "with-test".  "each" fixtures are useful forestablishing a consistent before/after state for each test, likeclearing out database tables."each" fixtures can be attached to the current namespace like this:(use-fixtures :each fixture1 fixture2 ...)The fixture1, fixture2 are just functions like the example above.They can also be anonymous functions, like this:(use-fixtures :each (fn [f] setup... (f) cleanup...))The other kind of fixture, a "once" fixture, is only run once,around ALL the tests in the namespace.  "once" fixtures are usefulfor tasks that only need to be performed once, like establishingdatabase connections, or for time-consuming tasks.Attach "once" fixtures to the current namespace like this:(use-fixtures :once fixture1 fixture2 ...)Note: Fixtures and test-ns-hook are mutually incompatible.  If youare using test-ns-hook, fixture functions will *never* be run.SAVING TEST OUTPUT TO A FILEAll the test reporting functions write to the var *test-out*.  Bydefault, this is the same as *out*, but you can rebind it to anyPrintWriter.  For example, it could be a file opened withclojure.java.io/writer.EXTENDING TEST-IS (ADVANCED)You can extend the behavior of the "is" macro by defining newmethods for the "assert-expr" multimethod.  These methods arecalled during expansion of the "is" macro, so they should returnquoted forms to be evaluated.You can plug in your own test-reporting framework by rebindingthe "report" function: (report event)The 'event' argument is a map.  It will always have a :type key,whose value will be a keyword signaling the type of event beingreported.  Standard events with :type value of :pass, :fail, and:error are called when an assertion passes, fails, and throws anexception, respectively.  In that case, the event will also havethe following keys:  :expected   The form that was expected to be true  :actual     A form representing what actually occurred  :message    The string message given as an argument to 'is'The "testing" strings will be a list in "*testing-contexts*", andthe vars being tested will be a list in "*testing-vars*".Your "report" function should wrap any printing calls in the"with-test-out" macro, which rebinds *out* to the current valueof *test-out*.For additional event types, see the examples in the code.

clojure.tools.deps.interop

Functions for invoking Java processes and invoking tools via the Clojure CLI.

clojure.walk

This file defines a generic tree walker for Clojure datastructures.  It takes any data structure (list, vector, map, set,seq), calls a function on every element, and uses the return valueof the function in place of the original.  This makes it fairlyeasy to write recursive search-and-replace functions, as shown inthe examples.Note: "walk" supports all Clojure data structures EXCEPT mapscreated with sorted-map-by.  There is no (obvious) way to retrievethe sorting function.

clojure.xml

XML reading/writing.

clojure.zip

Functional hierarchical zipper, with navigation, editing,and enumeration.  See Huet