How to Use this Book

I read some technical books while riding an exercise bike. I read others by carefully working through their exercises on my laptop. This book is designed to support both styles.

Reading-while-riding is adequate for a broad knowledge of a topic. In 2015, I read Saša Jurić’s Elixir In Action on an exercise bike. As a result, I knew what Elixir can do, but I didn’t remember much of how. To be able to actually program in Elixir, much less build a real system, I had to sit down and write code. Typing things at a computer and seeing what it types back really helps memory and comprehension.

Specter API exercises

In order to make Specter features better stick in your mind, I encourage you to try out exercises at the REPL. Such exercises look like this:

Because you might be reading on an exercise bike, I immediately give you the answers to the exercise. They look like this:

That’s executable Clojure for the Midje testing tool. Midje is designed so that tests look like examples in Clojure books: an expression you can type on the left-hand side, a separator—very often some sort of arrow—and then the expected value following. You can think of => expressions as very specific facts from which you can readily deduce a more general fact².

The namespace at the top of the solution is where the executable version lives in the book’s Github repo (https://github.com/marick/specter-book-code). You can run it if you like, using the instructions below.

Specter implementation exercises

As I said in the Preface, I encourage you to learn some of Specter’s design more deeply by implementing it yourself. There are exercises that guide you through that (and, immediately after, my solutions). You can implement your solutions solely in the REPL, but you can also edit files that live under the exercises namespace. They have boilerplate code to save you some typing. They also have tests so that you can know you’ve gotten it right more easily than retyping the same old examples in the REPL.

Because Midje is the bee’s knees³, exercise templates use it. That gives you three ways to check your work. The first is to use the command line to check the specific namespace you’re working in:

$ lein midje exercises.ch1.select-kw
= Namespace exercises.ch1.select-kw

WORK TO DO "Behaves the way specter/select does" at (select_kw.clj:8)
No facts were checked. Is that what you wanted?

The WORK TO DO message is because tests for unfinished code are marked as facts that aren’t yet true:

(future-facts "Behaves the way specter/select does"
  (select-kw [:a] nil) => [nil]

Just delete the “future-“ to see this:

$ lein midje exercises.ch1.select-kw
= Namespace exercises.ch1.select-kw

FAIL "Behaves the way specter/select does" at (select_kw.clj:9)
    Expected: [nil]
      Actual: :unimplemented

FAIL "Behaves the way specter/select does" at (select_kw.clj:10)
    Expected: [nil]
      Actual: :unimplemented
...

I personally am not patient enough to enjoy the amount of time it takes both Clojure and Midje to get loaded and start doing work, so I usually use “autotest”. There are two ways to do that. You can do it from the command line:

$ lein midje :autotest

That will first run all the tests. Thereafter, whenever you save a changed file, it will reload it and thus run the tests again.

In my day-to-day work, I prefer to work in the REPL:

$ lein repl
user=> (use 'midje.repl)
user=> (autotest)

That starts by running all the tests, but then it gives you an ordinary REPL prompt. You can use the REPL as usual, but a background process monitors changed files and reloads them as necessary.

Thanks for the comments and corrections

• Bahadir Cambel
• Beau Fabry
• Jason Felice

Contacting me

Mail me at marick@exampler.com, tweet toward @marick, or write to the book discussion page.

Please include the book’s version number as shown below.

Changelog

Version 3

• Add Chapter 2 on transform.
• Change “selector” to “path” to match the new Specter API docs.

Version 2

• Update to Specter 0.11.X (which has API changes)