Learn Clojure - Syntax

Integers are read as fixed precision 64-bit integers when they are in range and arbitrary precision otherwise. A trailing N can be used to force arbitrary precision. Clojure also supports the Java syntax for octal (prefix 0), hexadecimal (prefix 0x) and arbitrary radix (prefix base, then r, e.g. 2r for binary) integers. Ratios are provided as their own type combining a numerator and denominator.

Floating point values are read as double-precision 64-bit floats, or arbitrary precision with an M suffix. Exponential notation is also supported. The special symbolic values ##Inf, ##-Inf, and ##NaN represent positive infinity, negative infinity, and "not a number" values respectively.

Strings are contained in double quotes and may span multiple lines. Individual characters are represented with a leading backslash. There are a few special named characters: \newline \space \tab, etc. Unicode characters can be represented with \uNNNN or in octal with \oNNN.

Literal regular expressions are strings with a leading #. These are compiled to java.util.regex.Pattern objects.

Symbols are composed of letters, numbers, and other punctuation and are used to refer to something else, like a function, value, namespace, etc. Symbols may optionally have a namespace, separated with a forward slash from the name.

There are three special symbols that are read as different types - nil is the null value, and true and false are the boolean values.

Keywords start with a leading colon and always evaluate to themselves. They are frequently used as enumerated values or attribute names in Clojure.

Clojure also includes literal syntax for four collection types:

We’ll talk about these in much greater detail later - for now it’s enough to know that these four data structures can be used to create composite data.

In Java, source code (.java files) are read as characters by the compiler (javac), which produces bytecode (.class files) which can be loaded by the JVM.

In Clojure, source code is read as characters by the Reader. The Reader may read the source either from .clj files or be given a series of expressions interactively. The Reader produces Clojure data. The Clojure compiler then produces the bytecode for the JVM.

There are two important points here:

Consider a Clojure expression:

This diagram illustrates the difference between syntax in green (the Clojure data structure produced by the Reader) and semantics in blue (how that data is understood by the Clojure runtime).

Most literal Clojure forms evaluate to themselves, except symbols and lists. Symbols are used to refer to something else and when evaluated, return what they refer to. Lists (as in the diagram) are evaluated as invocation.

In the diagram, (+ 3 4) is read as a list containing the symbol (+) and two numbers (3 and 4). The first element (where + is found) can be called "function position", that is, a place to find the thing to invoke. While functions are an obvious thing to invoke, there are also a few special operators known to the runtime, macros, and a handful of other invokable things.

Considering the evaluation of the expression above:

Many languages have both statements and expressions, where statements have some stateful effect but do not return a value. In Clojure, everything is an expression that evaluates to a value. Some expressions (but not most) also have side effects.

Now let’s consider how we can interactively evaluate expressions in Clojure.

Sometimes it’s useful to suspend evaluation, in particular for symbols and lists. Sometimes a symbol should just be a symbol without looking up what it refers to:

And sometimes a list should just be a list of data values (not code to evaluate):

One confusing error you might see is the result of accidentally trying to evaluate a list of data as if it were code:

For now, don’t worry too much about quote but you will see it occasionally in these materials to avoid evaluation of symbols or lists.

Most REPL environments support a few tricks to help with interactive use. For example, some special symbols remember the results of evaluating the last three expressions:

In addition, there is a namespace clojure.repl that is included in the standard Clojure library that provides a number of helpful functions. To load that library and make its functions available in our current context, call:

For now, you can treat that as a magic incantation. Poof! We’ll unpack it when we get to namespaces.

We now have access to some additional functions that are useful at the REPL: doc, find-doc, apropos, source, and dir.

The doc function displays the documentation for any function. Let’s call it on +:

The doc function prints the documentation for +, including the valid signatures.

The doc function prints the documentation, then returns nil as the result - you will see both in the evaluation output.

We can invoke doc on itself too:

Not sure what something is called? You can use the apropos command to find functions that match a particular string or regular expression.

You can also widen your search to include the docstrings themselves with find-doc:

If you’d like to see a full listing of the functions in a particular namespace, you can use the dir function. Here we can use it on the clojure.repl namespace:

And finally, we can see not only the documentation but the underlying source for any function accessible by the runtime:

As you go through this workshop, please feel free to examine the docstring and source for the functions you are using. Exploring the implementation of the Clojure library itself is an excellent way to learn more about the language and how it is used.

It is also an excellent idea to keep a copy of the Clojure Cheatsheet open while you are learning Clojure. The cheatsheet categorizes the functions available in the standard library and is an invaluable reference.

Now let’s consider some Clojure basics to get you going…​.

When you are evaluating things at a REPL, it can be useful to save a piece of data for later. We can do this with def:

def is a special form that associates a symbol (x) in the current namespace with a value (7). This linkage is called a var. In most actual Clojure code, vars should refer to either a constant value or a function, but it’s common to define and re-define them for convenience when working at the REPL.

Note the return value above is #'user/x - that’s the literal representation for a var: #' followed by the namespaced symbol. user is the default namespace.

Recall that symbols are evaluated by looking up what they refer to, so we can get the value back by just using the symbol:

One of the most common things you do when learning a language is to print out values. Clojure provides several functions for printing values:

The human-readable forms will translate special print characters (like newlines and tabs) to their printed form and omit quotes in strings. We often use println to debug functions or print a value at the REPL. println takes any number of arguments and interposes a space between each argument’s printed value:

The println function has side-effects (printing) and returns nil as a result.

Note that "What is this:" above did not print the surrounding quotes and is not a string that the Reader could read again as data.

For that purpose, use prn to print as data:

Now the printed result is a valid form that the Reader could read again. Depending on context, you may prefer either the human form or the data form.