Living Clojure

Preface

The inspiration for this book comes from two things. The first and most direct one is from my years of learning, exploring, and finally working professionally in Clojure. The second, more indirect one, is from my experience of taking up running for the first time. My first attempt on my own was an utter failure. I thought that maybe I just wasn’t cut out to run. Luckily, I was introduced to a great program called Couch to 5k. The creators of the app realized that the most common reason people failed to achieve their fitness goals was because they were trying to do too much, too fast. To solve this problem, a gradual, 8-week training program was developed to help users achieve the goal of running for 30 minutes without stopping. Although it wasn’t easy, I managed to successfully complete the program and could run for a 30-minute stretch.

A few weeks later, I was with a group of fellow developers after attending a community user group. The conversation turned to Clojure. A few of us were discussing how much we enjoyed using the language, although one of our friends complained how he had tried to learn Clojure, but just couldn’t get it. I found out that he had tried to cram in learning it all in one weekend. Too much, too soon. The problems of learning how to run did not seem that much different from the problem of learning a new language. The process of learning a new language also involves learning a new way to think—training the brain to process inputs and solve problems in a new way. This doesn’t happen overnight. It comes, like training for running, after building up with practice.

This book combines these inspirations. The result is both a primer on learning Clojure and a structured training program to build up your brain to think a new way.

Who This Book Is For

Are you looking for a gentle introduction to Clojure? Do you already have a background in another programming language? Perfect! This book is for you. We will be covering programming concepts as they relate to Clojure and its unique design. We will also touch on object-oriented programming and concepts in comparison to functional programming. In the dicussion, we will be assuming familiarity with object-oriented development. So, if you are coming from another language like Ruby or Java, you should feel right at home. If you are a newer programmer, this book will be best paired with a more general introduction or reference to programming concepts.

If you are a language expert, or want a deep dive into every nook and cranny of Clojure, this book is most likely not for you. We will be concentrating on the major aspects of the language, not the minutiae, with the goal being to learn how to think Clojure. The same philosophy goes for tools and libraries in the Clojure ecosystem. We are striving for a primer that will present an overall holistic view of the most common and pragmatic parts, so that after finishing the book you will be comfortable and ready to start living Clojure.

How to Use This Book

The structure of this book built around training with knowledge and practice to live Clojure. Just like the inspirations for it, it is composed of two main parts. Part I is a tour of the simplicity and power of the Clojure programming language. It will cover useful libraries and common uses of Clojure. Part II is the Living Clojure Training Program. It will take you through a weekly training program designed to give you the practice, knowledge, and tools you need to get up and running and thriving as a Clojure developer.

The first half of the book will introduce the language, along with some code examples. There are a few important things to keep in mind, as outlined in the following subsections.

Do Try the Examples

I know it is tempting to read through the book as fast as possible. But actually typing in the code examples and seeing the magic for yourself will help your understanding grow. Take the time to try out the new concepts and commands for yourself. We will be walking through setting up your environment to run Clojure later in this Preface.

Don’t Feel Overwhelmed

We are going to cover a lot of material during the first half of the book. It is not all going to sink in right away. That is perfectly fine! In fact, this book was designed for that. The second half of the book is a training program that builds on the overview so that the basic language concepts really sink in with use. Once you start the training program, and questions start to come up, you will have all the tools and general knowledge to know where to look for the solutions.

Again, it takes time to learn to think in a new way. Be patient.

Don’t Worry About the Parens

A common initial concern from people looking at Clojure is about the parentheses.

Don’t worry about the parens.

Really.

After you get into Clojure with a good editor that supports a paredit mode—that is, a mode that always inserts the matching parens for you—they will seem to disappear. We will cover choosing and setting up an editor later on in Chapter 4.

The simplicity and elegance that the parens structure gives to Clojure is one of its main advantages. In fact, some people even come to think of the parens as a hug for their code.

One More Thing—Have Fun!

Clojure is a delightful language to use. Learning a new language is an exciting adventure, full of wonder. Embrace it.

Code examples can sometimes be stodgy, dry, full of meaningless numbers, and quite frankly, boring. This book strives to fight against this by using the power of storytelling to strengthen the code examples. Our brains become more active during stories. In fact, studies have shown that learning actually increases when problems are presented through a narrative. Thus, we are going to call upon a famous story to accompany us through this book: Alice in Wonderland by Lewis Carroll.

As you explore Clojure, the story of Alice in Wonderland will be woven through the code examples as well. Her adventures will remind you to relax, smile, and have fun on your journey.

What You Need to Use This Book

Before starting a journey, we need to pack our suitcases and prepare. Luckily, there is not much we need to get started on our adventure.

Install Java

If your computer doesn’t already have Java installed on it, you will need to get it. You can check to see if it is already set up by opening a command prompt and typing:

java -version

You should see something that looks like this:

java version "1.7.0_60"
Java(TM) SE Runtime Environment (build 1.7.0_60-b19)
Java HotSpot(TM) 64-Bit Server VM (build 24.60-b09, mixed mode)

If you see a version that is 1.6 or greater, you are ready to go. If not, you can download the latest version from the Java site.

Note

Wait. Why do I need Java? I want to learn Clojure.

Clojure runs on the Java virtual machine (JVM), which is a mature and robust platform used by many large enterprises. It is a great environment for running fast, scalable, and dependable programs.

You don’t need to know Java to write Clojure code. However, you can use and interact with Java classes and libraries if you want to. You’ll learn how to do this after we explore the language a bit first.

Now that you have Java installed, there is only one more thing you need before you are ready: a Clojure REPL.

Getting Your Clojure REPL Ready

Clojure has an important interactive tool called the REPL, which stands for read-eval-print loop. Once you get into the Clojure REPL, you are right there in the language. You will be able to enter Clojure code, hit Return, and the REPL will evaluate and print out the result for you. It is your key for exploring the language.

Let’s try out a Clojure REPL right now. We will be using the REPL all through the book to try out and explore code. In the early chapters, we will be exclusively trying out code in the REPL. As we move into creating projects with Clojure in Chapter 4, we will cover different editors and tooling. Right now, we are going to use the easiest way to try out a REPL, using Leiningen, a popular tool for creating Clojure projects.

Follow these steps to get a REPL up and running:

1. Visit the Leiningen website and follow the instructions to download.

2. Create a new project called wonderland with the following command:

   -> lein new wonderland

3. Go into the newly created project with this command:

   -> cd wonderland

4. Run the following command to start up the Clojure REPL:

   -> lein repl

You will see the following:

nREPL server started on port 65247 on host 127.0.0.1 - nrepl://127.0.0.1:65247
REPL-y 0.3.1
Clojure 1.6.0
    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)
 Results: Stored in vars *1, *2, *3, an exception in *e

user=>

The final line is the REPL prompt waiting for your input. Try typing in the following and pressing Return:

(+ 1 1)

You should see a 2 appear on the next line as the result:

nREPL server started on port 65361 on host 127.0.0.1 - nrepl://127.0.0.1:65361
REPL-y 0.3.1
Clojure 1.6.0
    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)
 Results: Stored in vars *1, *2, *3, an exception in *e

user=> (+ 1 1)
2
user=>

The REPL just read in what you typed, evaluated it, and printed out the result for you.

Throughout the book, this is how we will structure the code, and the return values for the code will be shown with two semicolons followed by an arrow, like this:

(+ 1 1)
;; -> 2

The semicolon signifies a comment in Clojure. When it comes time to evaluate the code, everything after the semicolon on that line is ignored. If you are using an electronic version of this book, this makes it convenient to copy and paste whole examples very easily into your REPL and try them out for yourself.

You now hold the power of the REPL in your hands. We’ll begin our journey to explore Clojure with it in Chapter 1.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This element signifies a tip or suggestion.

Note

This element signifies a general note.

Warning

This element indicates a warning or caution.

Using Code Examples

Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/gigasquid/wonderland-clojure-katas.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Living Clojure by Carin Meier (O’Reilly). Copyright 2015 Carin Meier, 978-1-491-90904-1.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of plans and pricing for enterprise, government, education, and individuals.

Members have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and hundreds more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

• O’Reilly Media, Inc.
• 1005 Gravenstein Highway North
• Sebastopol, CA 95472
• 800-998-9938 (in the United States or Canada)
• 707-829-0515 (international or local)
• 707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://bit.ly/living_clojure.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Writing a book has been one of the most challenging projects I have ever done. I certainly could not have done it alone. I would like to take a moment to call out thanks for everyone who helped, both directly and indirectly.

First is my editor, Meghan Blanchette. Working with a novice author to guide a book’s creation is no simple task. She was patient and encouraging, while always pushing me to express programming concepts clearly and logically. She always has the reader’s best interests at heart. Thank you. You are awesome.

To all the book reviewers, your feedback is invaluable. In particular, thanks to Colin Jones, Gabriel Andretta, Elliot Hauser, and Luigi Montanez.

Everyone who helped make this book possible with their contributions and permissions. In particular, Alan Malloy, Alex McNamara, David Byrne, and Anthony Grimes, who made helping out with my first Clojure Open Source project so enjoyable. Also, a special thanks to them for allowing the reproduction of the 4Clojure problems in the training plan in this book. Special thanks as well to Phil Hagelberg, not only for Leiningen and Clojars, but also for the guidance on Chapter 5. And thanks to Michael Klishin, James Reeves, Francesco Bellomi, Zachary Kim, Reid McKenzie, and everyone else for their kind use of screenshots for the book.

The Cincinnati Functional Programmers Group, and in particular, Creighton Kirkendall, Joe Herbers, and Benjamin Kyrlach, who helped me found the group all those years ago. You helped provide a strong community in our hometown for Clojure and other functional languages. I am so glad that I started on this journey with you.

The developer community in Cincinnati. I call you all my friends and am eternally grateful for your support and encouragement. Also, all of the regulars at the Friday morning coffee group, who likewise helped me keep my sanity.

The Clojure community for making it such a great place to grow and learn Clojure. Rich Hickey, Stu Halloway, Justin Gehtland, and all of Cognitect for creating great software. Alex Miller for being a superb guy and bringing the community together with incredible conferences. Michael Fogus and Chris Houser for The Joy of Clojure, for my first introduction to Clojure and my continued inspiration. All the many people of the Clojure community: David Nolen, Stuart Sierra, Alex Baranosky, Alan Dipert, Ambrose Bonnaire-Sergeant, Jen Smith, Sam Aaron, Jonathan Graham, Eric Normand, Aaron Brooks, Brenton Ashworth, Luke VanderHart, Bodil Stokke, Bruce Durling, Chas Emerick, Tavis Rudd, Chris Ford, Craig Andera, Michael Nygard, Yodit Stanton, David Pollak, Daniel Higginbotham, Ryan Neufeld, Nada Amin, William Byrd, Anna Pawlicka, Kyle Kingsbury, Zach Tellman, Zack Maril, all my Clojure friends at Outpace Systems, and all the other people whose names I missed.

Finally, thanks to my family who put up with me working all those weekends and evenings. I love you madly and I promise it will not be the first part in a trilogy.