title: Clojure from the ground up: welcome
url: https://aphyr.com/posts/301-clojure-from-the-ground-up-welcome
hash_url: 3e0624e344552c5fe90c30d8c32418dd

<p>This guide aims to introduce newcomers and experienced programmers alike to the
beauty of functional programming, starting with the simplest building blocks of
software. You’ll need a computer, basic proficiency in the command line, a text editor, and an internet connection. By the end of this series, you’ll have a thorough command of the Clojure programming language.</p>

<h2>Who is this guide for?</h2>

<p>Science, technology, engineering, and mathematics are deeply rewarding fields, yet few women enter STEM as a career path. Still more are discouraged by a culture which repeatedly asserts that women lack the analytic aptitude for writing software, that they are not driven enough to be successful scientists, that it’s not cool to pursue a passion for structural engineering. Those few with the talent, encouragement, and persistence to break in to science and tech are discouraged by persistent sexism in practice: the old boy’s club of tenure, being passed over for promotions, isolation from peers, and flat-out assault. This landscape sucks. I want to help change it.</p>

<p><a href="https://twitter.com/WomenWhoCode">Women Who Code</a>, <a href="http://www.pyladies.com/">PyLadies</a>, <a href="http://www.blackgirlscode.com/">Black Girls Code</a>, <a href="http://railsbridge.org/">RailsBridge</a>, <a href="http://www.girlswhocode.com/about-us/">Girls Who Code</a>, <a href="http://www.girldevelopit.com/">Girl Develop It</a>, and <a href="http://www.lambdaladies.com/">Lambda Ladies</a> are just a few of the fantastic groups helping women enter and thrive in software. I wholeheartedly support these efforts.</p>

<p>In addition, I want to help in my little corner of the technical community–functional programming and distributed systems–by making high-quality educational resources available for free. The <a href="/tags/jepsen">Jepsen</a> series has been, in part, an effort to share my enthusiasm for distributed systems with beginners of all stripes–but especially for <a href="http://aphyr.com/posts/275-meritocracy-is-short-sighted">women, LGBT folks, and people of color</a>.</p>

<p>As technical authors, we often assume that our readers are white, that our readers are straight, that our readers are traditionally male. This is the invisible default in US culture, and it’s especially true in tech. People continue to assume on the basis of my software and writing that I’m straight, because well hey, it’s a statistically reasonable assumption.</p>

<p>But I’m <em>not</em> straight. I get called faggot, cocksucker, and sinner. People say they’ll pray for me. When I walk hand-in-hand with my boyfriend, people roll down their car windows and stare. They threaten to beat me up or kill me. Every day I’m aware that I’m the only gay person some people know, and that I can show that not all gay people are effeminate, or hypermasculine, or ditzy, or obsessed with image. That you can be a manicurist or a mathematician or both. Being different, being a stranger in your culture, <a href="http://aphyr.com/posts/274-identity-and-state">comes with all kinds of challenges</a>. I can’t speak to everyone’s experience, but I can take a pretty good guess.</p>

<p>At the same time, in the technical community I’ve found overwhelming warmth and support, from people of <em>all</em> stripes. My peers stand up for me every day, and I’m so thankful–especially you straight dudes–for understanding a bit of what it’s like to be different. I want to extend that same understanding, that same empathy, to people unlike myself. Moreover, I want to reassure everyone that though they may feel different, they <em>do</em> have a place in this community.</p>

<p>So before we begin, I want to reinforce that you <em>can</em> program, that you <em>can</em> do math, that you <em>can</em> design car suspensions and fire suppression systems and spacecraft control software and distributed databases, regardless of what your classmates and media and even fellow engineers think. You don’t have to be white, you don’t have to be straight, you don’t have to be a man. You can grow up never having touched a computer and still become a skilled programmer. Yeah, it’s harder–and yeah, people will give you shit, but that’s not your fault and has nothing to do with your <em>ability</em> or your <em>right</em> to do what you love. All it takes to be a good engineer, scientist, or mathematician is your curiosity, your passion, the right teaching material, and putting in the hours.</p>

<p>There’s nothing in this guide that’s just for lesbian grandmas or just for mixed-race kids; bros, you’re welcome here too. There’s nothing dumbed down. We’re gonna go as deep into the ideas of programming as I know how to go, and we’re gonna do it with everyone on board.</p>

<p>No matter who you are or who people <em>think</em> you are, this guide is for you.</p>

<h2>Why Clojure?</h2>

<p>This book is about how to program. We’ll be learning in Clojure, which is a modern dialect of a very old family of computer languages, called Lisp. You’ll find that many of this book’s ideas will translate readily to other languages; though they may be <a href="http://aphyr.com/posts/266-core-language-concepts">expressed in different ways</a>.</p>

<p>We’re going to explore the nature of syntax, metalanguages, values, references, mutation, control flow, and concurrency. Many languages leave these ideas implicit in the language construction, or don’t have a concept of metalanguages or concurrency at all. Clojure makes these ideas explicit, first-class language constructs.</p>

<p>At the same time, we’re going to defer or omit any serious discussion of static type analysis, hardware, and performance. This is not to say that these ideas aren’t <em>important</em>; just that they don’t fit well within this particular narrative arc. For a deep exploration of type theory I recommend a study in Haskell, and for a better understanding of underlying hardware, learning C and an assembly language will undoubtedly help.</p>

<p>In more general terms, Clojure is a well-rounded language. It offers broad library support and runs on multiple operating systems. Clojure performance is not terrific, but is orders of magnitude faster than Ruby, Python, or Javascript. Unlike some faster languages, Clojure emphasizes <em>safety</em> in its type system and approach to parallelism, making it easier to write correct multithreaded programs. Clojure is <em>concise</em>, requiring very little code to express complex operations. It offers a REPL and dynamic type system: ideal for beginners to experiment with, and well-suited for manipulating complex data structures. A consistently designed standard library and full-featured set of core datatypes rounds out the Clojure toolbox.</p>

<p>Finally, there are some drawbacks. As a compiled language, Clojure is much slower to start than a scripting language; this makes it unsuitable for writing small scripts for interactive use. Clojure is also <em>not</em> well-suited for high-performance numeric operations. Though it is possible, you have to jump through hoops to achieve performance comparable with Java. I’ll do my best to call out these constraints and shortcomings as we proceed through the text.</p>

<p>With that context out of the way, let’s get started by installing Clojure!</p>

<h2>Getting set up</h2>

<p>First, you’ll need a Java Virtual Machine, or JVM, and its associated
development tools, called the JDK. This is the software which <em>runs</em> a Clojure
program. If you’re on Windows, install <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle
JDK 1.7</a>. If you’re on OS X or Linux, you may already have a JDK installed.
In a terminal, try:</p>
<code class="block">which javac
</code>
<p>If you see something like</p>
<code class="block">/usr/bin/javac
</code>
<p>Then you’re good to go. If you don’t see any output from that command, install the appropriate
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle
JDK 1.7</a> for your operating system, or whatever JDK your package manager has available.</p>

<p>When you have a JDK, you’ll need <a href="http://leiningen.org">Leiningen</a>,
the Clojure build tool. If you’re on a Linux or OS X computer, the instructions below
should get you going right away. If you’re on Windows, see the Leiningen page
for an installer. If you get stuck, you might want to start with a
<a href="http://blog.teamtreehouse.com/command-line-basics">primer on command line basics</a>.</p>
<code class="block">mkdir -p ~/bin
<span class="nb">cd</span> ~/bin
curl -O https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein
chmod a+x lein
</code>
<p>Leiningen automatically handles installing Clojure, finding libraries from the
internet, and building and running your programs. We’ll create a new Leiningen
project to play around in:</p>
<code class="block"><span class="nb">cd</span>
lein new scratch
</code>
<p>This creates a new directory in your homedir, called <code>scratch</code>. If you see <code>command not found</code> instead, it means the directory <code>~/bin</code> isn’t registered with your terminal as a place to search for programs. To fix this, add the line</p>
<code class="block"><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"$PATH"</span>:~/bin
</code>
<p>to the file <code>.bash_profile</code> in your home directory, then run <code>source ~/.bash_profile</code>. Re-running <code>lein new scratch</code> should work.</p>

<p>Let’s enter that directory, and start using Clojure itself:</p>
<code class="block"><span class="nb">cd </span>scratch
lein repl
</code>
<h2>The structure of programs</h2>

<p>When you type <code>lein repl</code> at the terminal, you’ll see something like this:</p>
<code class="block">aphyr@waterhouse:~/scratch$ lein repl
nREPL server started on port 45413
REPL-y 0.2.0
Clojure 1.5.1
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)

user=&gt;</code>
<p>This is an interactive Clojure environment called a REPL, for “Read, Evaluate,
Print Loop”. It’s going to <em>read</em> a program we enter, run that program, and
print the results. REPLs give you quick feedback, so they’re a great way to
explore a program interactively, run tests, and prototype new ideas.</p>

<p>Let’s write a simple program. The simplest, in fact. Type “nil”, and hit enter.</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="nv">nil</span>
<span class="nv">nil</span>
</code>
<p><code>nil</code> is the most basic value in Clojure. It represents emptiness,
nothing-doing, not-a-thing. The absence of information.</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="nv">true</span>
<span class="nv">true</span>
<span class="nv">user=&gt;</span> <span class="nv">false</span>
<span class="nv">false</span>
</code>
<p><code>true</code> and <code>false</code> are a pair of special values called <em>Booleans</em>. They mean
exactly what you think: whether a statement is true or false. <code>true</code>, <code>false</code>, and <code>nil</code> form the three poles of the Lisp logical system.</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="mi">0</span>
<span class="mi">0</span>
</code>
<p>This is the number zero. Its numeric friends are <code>1</code>, <code>-47</code>, <code>1.2e-4</code>, <code>1/3</code>,
and so on. We might also talk about <em>strings</em>, which are chunks of text surrounded by double quotes:</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="s">"hi there!"</span>
<span class="s">"hi there!"</span>
</code>
<p><code>nil</code>, <code>true</code>, <code>0</code>, and <code>"hi there!"</code> are all different types of <em>values</em>; the
nouns of programming. Just as one could say “House.” in English, we can write a
program like <code>"hello, world"</code> and it evaluates to itself: the string <code>"hello
world"</code>. But most sentences aren’t just about stating the existence of a thing; they involve <em>action</em>. We need <em>verbs</em>.</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="nv">inc</span>
<span class="o">#</span><span class="nv">&lt;core$inc</span> <span class="nv">clojure.core$inc</span><span class="o">@</span><span class="mi">6</span><span class="nv">f7ef41c&gt;</span>
</code>
<p>This is a verb called <code>inc</code>–short for “increment”. Specifically, <code>inc</code> is a
<em>symbol</em> which <em>points</em> to a verb: <code>#&lt;core$inc clojure.core$inc@6f7ef41c&gt;</code>–
just like the word “run” is a <em>name</em> for the <em>concept</em> of running.</p>

<p>There’s a key distinction here–that a signifier, a reference, a label, is not
the same as the signified, the referent, the concept itself. If you write the
word “run” on paper, the ink means nothing by itself. It’s just a symbol. But
in the mind of a reader, that symbol takes on <em>meaning</em>; the idea of running.</p>

<p>Unlike the number 0, or the string “hi”, symbols are references to other
values. when Clojure evaluates a symbol, it looks up that symbol’s meaning.
Look up <code>inc</code>, and you get <code>#&lt;core$inc clojure.core$inc@6f7ef41c&gt;</code>.</p>

<p>Can we refer to the symbol itself, <em>without</em> looking up its meaning?</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="ss">'inc</span>
<span class="nv">inc</span>
</code>
<p>Yes. The single quote <code>'</code> <em>escapes</em> a sentence. In programming languages, we call sentences <code>expressions</code> or <code>statements</code>. A quote says “Rather than <em>evaluating</em> this expression’s text, simply return the text itself, unchanged.” Quote a symbol, get a symbol. Quote a number, get a number. Quote anything, and get it back exactly as it came in.</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="ss">'123</span>
<span class="mi">123</span>
<span class="nv">user=&gt;</span> <span class="o">'</span><span class="s">"foo"</span>
<span class="s">"foo"</span>
<span class="nv">user=&gt;</span> <span class="o">'</span><span class="p">(</span><span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span><span class="p">)</span>
<span class="p">(</span><span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span><span class="p">)</span>
</code>
<p>A new kind of value, surrounded by parentheses: the <em>list</em>. LISP originally stood for LISt Processing, and lists are still at the core of the language. In fact, they form the most basic way to compose expressions, or sentences. A list is a single expression which has <em>multiple parts</em>. For instance, this list contains three elements: the numbers 1, 2, and 3. Lists can contain anything: numbers, strings, even other lists:</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="o">'</span><span class="p">(</span><span class="nf">nil</span> <span class="s">"hi"</span><span class="p">)</span>
<span class="p">(</span><span class="nf">nil</span> <span class="s">"hi"</span><span class="p">)</span>
</code>
<p>A list containing two elements: the number 1, and a second list. That list
contains two elements: the number 2, and another list. <em>That</em> list contains two
elements: 3, and an empty list.</p>
<code class="block">user=&gt; '(1 (2 (3 ())))
(1 (2 (3 ())))</code>
<p>You could think of this structure as a tree–which is a provocative idea,
because <em>languages</em> are like trees too: sentences are comprised of clauses, which can be nested, and each clause may have subjects modified by adjectives, and verbs modified by adverbs, and so on. “Lindsay, my best friend, took the dog which we found together at the pound on fourth street, for a walk with her mother Michelle.”</p>
<code class="block">Took
  Lindsay
    my best friend
  the dog
    which we found together
      at the pound
        on fourth street
    for a walk
      with her mother
        Michelle</code>
<p>But let’s try something simpler. Something we know how to talk about.
“Increment the number zero.” As a tree:</p>
<code class="block">Increment
  the number zero</code>
<p>We have a symbol for incrementing, and we know how to write the number zero.
Let’s combine them in a list:</p>
<code class="block"><span class="nv">clj=&gt;</span> <span class="o">'</span><span class="p">(</span><span class="nb">inc </span><span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="nb">inc </span><span class="mi">0</span><span class="p">)</span>
</code>
<p>A basic sentence. Remember, since it’s quoted, we’re talking about the tree,
the text, the expression, by itself. Absent interpretation. If we remove the
single-quote, Clojure will <em>interpret</em> the expression:</p>
<code class="block"><span class="nv">user=&gt;</span> <span class="p">(</span><span class="nb">inc </span><span class="mi">0</span><span class="p">)</span>
<span class="mi">1</span>
</code>
<p>Incrementing zero yields one. And if we wanted to increment <em>that</em> value?</p>
<code class="block">Increment
  increment
    the number zero</code><code class="block"><span class="nv">user=&gt;</span> <span class="p">(</span><span class="nb">inc </span><span class="p">(</span><span class="nb">inc </span><span class="mi">0</span><span class="p">))</span>
<span class="mi">2</span>
</code>
<p>A sentence in Lisp is a list. It starts with a verb, and is followed by zero or
more objects for that verb to act on. Each part of the list can <em>itself</em> be
another list, in which case that nested list is evaluated first, just like a
nested clause in a sentence. When we type</p>
<code class="block"><span class="p">(</span><span class="nb">inc </span><span class="p">(</span><span class="nb">inc </span><span class="mi">0</span><span class="p">))</span>
</code>
<p>Clojure first looks up the meanings for the symbols in the code:</p>
<code class="block"><span class="p">(</span><span class="o">#</span><span class="nv">&lt;core$inc</span> <span class="nv">clojure.core$inc</span><span class="o">@</span><span class="mi">6</span><span class="nv">f7ef41c&gt;</span>
  <span class="p">(</span><span class="o">#</span><span class="nv">&lt;core$inc</span> <span class="nv">clojure.core$inc</span><span class="o">@</span><span class="mi">6</span><span class="nv">f7ef41c&gt;</span>
    <span class="mi">0</span><span class="p">))</span>
</code>
<p>Then evaluates the innermost list <code>(inc 0)</code>, which becomes the number 1:</p>
<code class="block"><span class="p">(</span><span class="o">#</span><span class="nv">&lt;core$inc</span> <span class="nv">clojure.core$inc</span><span class="o">@</span><span class="mi">6</span><span class="nv">f7ef41c&gt;</span>
 <span class="mi">1</span><span class="p">)</span>
</code>
<p>Finally, it evaluates the outer list, incrementing the number 1:</p>
<code class="block"><span class="mi">2</span>
</code>
<p>Every list starts with a verb. Parts of a list are evaluated from left to
right. Innermost lists are evaluated before outer lists.</p>
<code class="block"><span class="p">(</span><span class="nb">+ </span><span class="mi">1</span> <span class="p">(</span><span class="nb">- </span><span class="mi">5</span> <span class="mi">2</span><span class="p">)</span> <span class="p">(</span><span class="nb">+ </span><span class="mi">3</span> <span class="mi">4</span><span class="p">))</span>
<span class="p">(</span><span class="nb">+ </span><span class="mi">1</span> <span class="mi">3</span>       <span class="p">(</span><span class="nb">+ </span><span class="mi">3</span> <span class="mi">4</span><span class="p">))</span>
<span class="p">(</span><span class="nb">+ </span><span class="mi">1</span> <span class="mi">3</span>       <span class="mi">7</span><span class="p">)</span>
<span class="mi">11</span>
</code>
<p>That’s it.</p>

<p>The entire grammar of Lisp: the structure for every expression in the language.
We transform expressions by <em>substituting</em> meanings for symbols, and obtain
some result. This is the core of the <a href="http://en.wikipedia.org/wiki/Lambda_calculus">Lambda Calculus</a>, and it is the theoretical basis for almost all computer languages.
Ruby, Javascript, C, Haskell; all languages express the text of their programs in different ways, but internally all construct a <em>tree</em> of expressions. Lisp simply makes it explicit.</p>

<h2>Review</h2>

<p>We started by learning a few basic nouns: numbers like <code>5</code>, strings like
<code>"cat"</code>, and symbols like <code>inc</code> and <code>+</code>. We saw how quoting makes the
difference between an <em>expression</em> itself and the thing it <em>evaluates</em> to.  We
discovered symbols as <em>names</em> for other values, just like how words represent
concepts in any other language. Finally, we combined lists to make trees, and
used those trees to represent a program.</p>

<p>With these basic elements of syntax in place, it’s time to expand our
vocabulary with new verbs and nouns; learning to <a href="http://aphyr.com/posts/302-clojure-from-the-ground-up-basic-types">represent more complex values and transform them in different ways</a>.</p>
