Skip to content
LumenaryAcademy
Foundations 50 min

First steps: Lisp syntax, the REPL and the Clojure CLI

Where Clojure came from, how to install and run it, and how to read the parentheses.

Code tested · 4AI-draftedAwaiting review by a computer scientist
MotivationH

Why learn a Lisp in 2026?

Most popular languages share a family resemblance. Statements end with semicolons or newlines, operators sit between their arguments, and a program is a series of instructions that change variables in place. Clojure looks different from the first line. Everything is written in parentheses, the operator always comes first, and the values you work with almost never change once they exist.

That strangeness buys three things that working programmers value.

The first is simplicity of syntax. Clojure has essentially one grammatical rule: a list in parentheses is a call, with the thing being called in first position. There is no operator precedence table to memorise and no special syntax for loops, assignments or method calls. Once you can read one form, you can read them all.

The second is immutable data. A Clojure vector or map cannot be changed after it is created. "Adding" an element gives you a new collection and leaves the old one exactly as it was, and the language makes that cheap. A whole category of bugs (a function quietly modifying a list that its caller was still using, two threads stepping on the same object) simply cannot happen.

The third is the REPL, the read-eval-print loop. Clojure programmers do not write a file, compile it, run it and read the output. They keep a program running and evaluate one function at a time from their editor into it, seeing results in milliseconds. Programs grow by small, tested steps, and you rarely restart anything.

This lesson gets you installed, running programs, and reading the parentheses fluently. Every later lesson builds on the three evaluation rules you meet here.

History & global context

Where Clojure came from

Clojure was created by Rich Hickey, an experienced C++, Java and C# programmer who had built scheduling and broadcast systems for years. He began working on it in 2005, largely self-funded, and announced it publicly in October 2007. Version 1.0 followed in May 2009.

Hickey's starting point was frustration with the state of everyday programming. Object-oriented languages, he argued, tangle together things that should be separate: identity (this is the customer), state (the customer's address right now) and value (a particular address). When every object can change at any moment, concurrent programs become very hard to reason about. At the same time he admired Lisp, the family of languages descended from John McCarthy's 1958 design, for its tiny syntax and its ability to extend itself with macros. Classic Lisps, though, lived apart from the libraries and platforms where business software was written.

So Clojure was designed as a hosted language. It compiles to Java bytecode and runs on the Java Virtual Machine (JVM), uses Java's strings, numbers and exceptions directly, and can call any Java library with no wrappers. ClojureScript (2011) brought the same language to JavaScript engines, and smaller projects target .NET (ClojureCLR) and other hosts. Being hosted meant Clojure had a mature garbage collector, a fast just-in-time compiler and decades of libraries on its first day.

Some milestones since then:

  • 2010s: Leiningen (2009) becomes the standard build tool; Clojars becomes the community's library repository; the Datomic database (2012), written in Clojure, shows the "facts that never change" philosophy applied to storage.
  • 2017: Clojure 1.9 adds spec, a library for describing the shape of data, and the official Clojure CLI with its deps.edn file appears alongside it.
  • 2020: Cognitect, the company that stewarded Clojure, joins the Brazilian digital bank Nubank, one of the largest Clojure users in the world, which continues to fund the core team.
  • 2024: Clojure 1.12 makes Java interop smoother (Java methods can be used directly as functions) and lets you add libraries to a running REPL.

This course uses Clojure 1.12 on Java 21, the versions every program here was run with. Clojure changes slowly and carefully: code written for 1.0 almost always still runs, and the core team treats breaking changes as something to avoid, not a cost of progress.

DefinitionsH

The toolchain: Java, the Clojure CLI and deps.edn

You need two things installed: a Java runtime and the Clojure command-line tools.

Definition— JDK (Java Development Kit)

The Java platform that runs Clojure. Any current long-term-support release works; Java 21 and 25 are common choices in 2026. Free builds are available from several vendors, for example Eclipse Temurin. Clojure itself is just a Java library (a single .jar file plus its dependencies) that the CLI downloads for you.

Definition— Clojure CLI

The official command-line tool, installed by following the install guide (Homebrew on macOS, an install script on Linux, and instructions for Windows). It provides two commands. clj starts an interactive REPL with line editing. clojure runs programs and tasks; clojure -M main.clj runs a file from top to bottom.

Definition— deps.edn

A file at the root of a project that lists where source code lives (:paths), which libraries it uses (:deps) and named sets of extra options (:aliases). It is written in EDN, Clojure's own data notation, so it is just a Clojure map.

A minimal project looks like this:

text
hello/
  deps.edn
  src/
    hello/
      core.clj

with a deps.edn such as:

clojure
{:paths ["src"]
 :deps  {org.clojure/clojure {:mvn/version "1.12.6"}}}

The library coordinates name a group (org.clojure), an artifact (clojure) and a version from Maven Central, the same repository Java uses; Clojure libraries are also published to Clojars. When you run clojure in that directory, the CLI reads the file, downloads anything missing into a cache under your home directory, builds a classpath and starts the JVM.

You will also meet Leiningen, the older project tool, in many existing codebases. It uses a project.clj file and commands like lein repl, lein test and lein uberjar. Both tools are healthy and widely used; new projects increasingly start with the official CLI, and lesson 8 compares them in detail.

To check your installation:

bash
java -version
clojure --version
clj                     # starts a REPL; type (+ 1 2) and press Enter, Ctrl-D to quit

Clojure has no official online playground. Every complete program in this course is a single file you can save as main.clj and run with clojure -M main.clj from any directory; no deps.edn is needed because the CLI falls back to a default Clojure version.

Worked examplesH

First programs

Hello, world

clojure
(println "Hello, world!")
(println "Habari, dunia!" "Ola, mundo!" "Merhaba, dunya!")
(println "Clojure" (clojure-version))
text
Hello, world!
Habari, dunia! Ola, mundo! Merhaba, dunya!
Clojure 1.12.6

Each line is a form, a piece of code the reader turns into data and the compiler then evaluates. (println "Hello, world!") is a list of two things: the symbol println and a string. Because it is a list, Clojure calls the function named by the first element with the rest as arguments. println prints its arguments separated by spaces and ends the line. In the third form, (clojure-version) is itself a call with no arguments, evaluated first, and its result is passed to println. Your version number may be newer.

Note

The greetings above are written without accents (Ola rather than Olá) on purpose. Clojure strings are full Unicode, but when the JVM's output goes to a terminal or a container whose locale is not set to UTF-8, characters outside ASCII can print as question marks. If that happens to you, set a UTF-8 locale (for example LANG=C.UTF-8) or pass -J-Dstdout.encoding=UTF-8 to clojure.

Arithmetic in prefix position

clojure
(println (+ 1 2 3 4))
(println (* 2 (+ 3 4)))
(println (- 10) (- 10 4 3))
(println (/ 10 4) (/ 10.0 4) (/ 9 3))
(println (quot 17 5) (rem 17 5) (mod -7 3))
(println (max 3 9 4) (min 3 9 4))
(println (< 1 2 3) (< 1 3 2))
(println (= 2 2 2) (= 1 1.0) (== 1 1.0))
(println (inc 41) (dec 43) (* 1000000 1000000 1000000))
(println (*' 1000000 1000000 1000000 1000000))
text
10
14
-10 3
5/2 2.5 3
3 2 2
9 3
true false
true false true
42 42 1000000000000000000
1000000000000000000000000N

Read it slowly; several lines hold a surprise for newcomers.

  • Operators are ordinary functions, and most take any number of arguments. (+ 1 2 3 4) is 10; (< 1 2 3) asks "is this sequence strictly increasing?"
  • Nesting replaces precedence. (* 2 (+ 3 4)) can only mean one thing, so there is nothing to remember about which operator binds tighter.
  • Dividing two integers that do not divide evenly gives a ratio, 5/2, an exact fraction. Use a floating-point argument (10.0) when you want 2.5, or quot for whole-number division.
  • rem keeps the sign of the dividend; mod keeps the sign of the divisor, so (mod -7 3) is 2.
  • = compares values, and an integer is never = to a floating-point number. == compares numbers by numeric value across types.
  • Integers are 64-bit Java longs. The product of three millions fits; a fourth would not, and plain * throws an ArithmeticException on overflow instead of wrapping around silently. The primed operators +', -', *' promote to arbitrary-precision integers, printed with an N suffix.

Values and their types

Every value in Clojure has a type you can ask for. This program walks through the literals you will use daily. Read the doseq loop for its shape only; it runs its body once for each element of the vector.

clojure
(def samples
  [42 3.14 22/7 12345678901234567890N 0.1M
   "text" \x :status 'total nil true
   [1 2 3] '(1 2 3) {:id 7} #{:a :b}])

(doseq [v samples]
  (println (pr-str v) "=>" (type v)))
text
42 => java.lang.Long
3.14 => java.lang.Double
22/7 => clojure.lang.Ratio
12345678901234567890N => clojure.lang.BigInt
0.1M => java.math.BigDecimal
"text" => java.lang.String
\x => java.lang.Character
:status => clojure.lang.Keyword
total => clojure.lang.Symbol
nil => nil
true => java.lang.Boolean
[1 2 3] => clojure.lang.PersistentVector
(1 2 3) => clojure.lang.PersistentList
{:id 7} => clojure.lang.PersistentArrayMap
#{:b :a} => clojure.lang.PersistentHashSet

Notice how many are plain Java types: numbers, strings, characters and booleans are the JVM's own, which is why interop is so smooth. The rest come from Clojure itself:

LiteralMeaning
22/7an exact ratio
123N, 0.1Man arbitrary-precision integer, an exact decimal (use M for money)
\xa single character
:statusa keyword: a name that evaluates to itself, used as map keys and labels
'totala symbol: a name that normally refers to something; the quote stops it being looked up
nil"nothing", the same as Java's null
[1 2 3]a vector, the everyday ordered collection
'(1 2 3)a list, quoted so it is not treated as a call
{:id 7}a map from keys to values
#{:a :b}a set, which prints in no particular order

Commas are treated as whitespace, so {:a 1, :b 2} and {:a 1 :b 2} are the same map. Use them only where they help a human reader.

Printing for humans and for programs

clojure
(def city "Lima")
(def celsius 19.5)

(println "City:" city "temperature:" celsius)
(prn "City:" city "temperature:" celsius)
(println (str "In " city " it is " celsius " degrees."))
(println (format "%-8s|%6.1f|%4d" city celsius 7))

(def answer (println "printing is a side effect"))
(prn answer)

(def form '(+ 1 2 3))
(println "first:" (first form) "rest:" (rest form))
(println "evaluated:" (eval form))
text
City: Lima temperature: 19.5
"City:" "Lima" "temperature:" 19.5
In Lima it is 19.5 degrees.
Lima    |  19.5|   7
printing is a side effect
nil
first: + rest: (1 2 3)
evaluated: 6
  • println is for people: strings appear without quotes. prn is for programs: it prints values the way you would type them, so the output can be read back as data. While debugging, prn tells you whether that 7 is a number or a string.
  • str glues values together into a single string. format uses Java's String.format directives (%s, %d, %.1f, widths and alignment).
  • def gives a name to a value in the current namespace. It is not a variable you will keep reassigning; lesson 6 shows how Clojure handles values that change.
  • println returns nil. Printing is something a function does, not something it produces.
  • The last three lines show the famous Lisp property: code is data. '(+ 1 2 3) is an ordinary list whose first element is the symbol +. You can take it apart with first and rest, and eval runs it as code. Lesson 7 uses this to write macros.
IntuitionH

Three rules for reading any form

Clojure's syntax is small enough to state completely in three rules. When the compiler meets a form:

  1. Most literals evaluate to themselves. 42, "text", :status, nil and true mean exactly what they say. Vectors, maps and sets evaluate each of their elements and build a collection from the results, so [1 (+ 1 1)] is [1 2].
  2. A symbol is looked up. city evaluates to the value it was defined as; println evaluates to a function. An unknown symbol is an error: Unable to resolve symbol.
  3. A list is a call. Evaluate the first element to find out what to call, evaluate the remaining elements to get the arguments, then call. (* 2 (+ 3 4)) evaluates (+ 3 4) first because it is an argument.

There is one exception to rule 3: a small set of special forms such as def, if, do, let, fn, quote and loop control how (and whether) their arguments are evaluated. (if test a b) evaluates only one of a and b; (quote x), written 'x, does not evaluate x at all. Macros, which you will write in lesson 7, are user-defined forms that get the same privilege.

Example— Evaluating a form by hand

Take (str "Total: " (+ 40 (* 2 1))).

  • It is a list, so it is a call. The first element, str, is a symbol; look it up: a function.
  • Argument one, "Total: ", is a literal string.
  • Argument two is a list, so it is a call: look up +, then evaluate its arguments 40 and (* 2 1). The inner call gives 2, so + gets 40 and 2 and returns 42.
  • Now str is called with "Total: " and 42 and returns "Total: 42".

Inner forms are evaluated before outer ones, left to right. That is the whole story for ordinary function calls.

Misconception

"All those parentheses must make Clojure harder to read than other languages." A Clojure call has the same number of parentheses as the equivalent call elsewhere; they have just moved. max(a, b) becomes (max a b). What disappears are the semicolons, braces, commas and precedence rules. Experienced Clojure programmers read code by its indentation, not by counting brackets, and let their editor keep the parentheses balanced (structural editing tools such as paredit or parinfer make an unbalanced form almost impossible to type).

ExplanationH

How Clojure programmers actually work: the REPL

In many languages a "REPL" is a toy for trying one-liners. In Clojure it is the centre of the workflow. Here is what a typical session looks like in a terminal:

text
$ clj
Clojure 1.12.6
user=> (def prices [12.5 8.0 30.25])
#'user/prices
user=> (reduce + prices)
50.75
user=> (count prices)
3
user=> (/ (reduce + prices) (count prices))
16.916666666666668
user=> (doc count)
-------------------------
clojure.core/count
([coll])
  Returns the number of items in the collection. (count nil) returns
  0.  Also works on strings, arrays, and Java Collections and Maps
nil

The prompt user=> names the current namespace (user is the default). #'user/prices is a var, the named box def created. doc prints a function's documentation, and source shows its source code; *1, *2 and *3 hold the last three results, and *e the last exception.

Professionals rarely type into a bare terminal REPL, though. They start a REPL connected to their editor (Calva in VS Code, CIDER in Emacs, Cursive in IntelliJ, Conjure in Neovim, usually over a protocol called nREPL) and then:

  1. write a function in a source file;
  2. put the cursor on it and press a key to evaluate it into the running program;
  3. call it from a scratch form right below, and see the result inline;
  4. adjust, re-evaluate, repeat.

Many source files end with a rich comment block for exactly this purpose:

clojure
(comment
  (average [12.5 8.0 30.25])   ; evaluate this line from the editor
  (average [])                 ; what happens on empty input?
  )

comment ignores its body and returns nil, so the experiments never run when the file is loaded, yet they sit beside the code as living notes. Because the program keeps running, any state you have built up (a database connection, a loaded data set, a web server) survives each change. Restarting the JVM takes seconds; re-evaluating a function takes milliseconds, and that difference shapes how Clojure programmers think.

Running a whole file with clojure -M main.clj, as this course's examples do, is the other half: it is how scripts, tests and production programs start. Get comfortable with both.

Common misconceptionsH

Common first-day mistakes

Misconception

Writing a list of numbers as (1 2 3). By rule 3 that is a call, and since 1 is not a function you get ClassCastException: class java.lang.Long cannot be cast to class clojure.lang.IFn. "IFn" is Clojure's interface for things that can be called. Use a vector, [1 2 3], or quote the list: '(1 2 3).

Misconception

Expecting = to assign. = is a function that tests equality and returns true or false. Names are introduced with def (at the top level) and let (locally, next lesson).

Misconception

Expecting (= 1 1.0) to be true. Clojure's = treats integers and floating-point numbers as different kinds of value, partly because floating-point arithmetic is approximate. Compare numbers across types with ==.

Misconception

Using the result of println. It prints and returns nil. If you want a string, build it with str or format and print it at the edge of your program.

Exercises

Exercises

1. First steps: Lisp syntax, the REPL and the Clojure CLI

Warm-upComputational

What does this program print?

(println (- 20 (* 3 4)) (/ 12 8))

2. First steps: Lisp syntax, the REPL and the Clojure CLI

Warm-upHuman

You type (1 2 3) at the REPL, hoping to see a list of three numbers. What happens?

Choose one

3. First steps: Lisp syntax, the REPL and the Clojure CLI

CoreComputational

Which of these forms evaluate to true? List their letters.

  • A: (< 1 2 2)
  • B: (<= 1 2 2)
  • C: (= 2 2.0)
  • D: (== 2 2.0)
  • E: (= "a" "a")
  • F: (not= 3 4)

Write elements separated by commas. Order and repeats don’t matter — just like in a set!

4. First steps: Lisp syntax, the REPL and the Clojure CLI

CoreComputational

What does this program print? Type the line exactly.

(prn "7" 7 :seven)

5. First steps: Lisp syntax, the REPL and the Clojure CLI

CoreComputational

What does (count [1 [2 3] {:a 1 :b 2} "four"]) return?

6. First steps: Lisp syntax, the REPL and the Clojure CLI

StretchComputational

What does this program print?

(println (* 2 (+ 1 2)) (str 1 2 3) (str "a" nil "b"))

7. First steps: Lisp syntax, the REPL and the Clojure CLI

Warm-upHuman

You open a Clojure project and want to see which libraries the official Clojure CLI will put on the classpath. Which file do you read?

Choose one

8. First steps: Lisp syntax, the REPL and the Clojure CLI

CoreHuman

Why do Clojure source files often end with a (comment ...) block full of example calls?

Choose one

Further reading and resources