Clojure koans are cool

I found another post in the Unboxing series highlighting Clojure Koans.  These are simple learn-by-example snippets of Clojure code hosted by hosted at clojure-koans on GitHub.

While you can download the zipfile and get started with that, I decided to follow the advice on the GitHub homepage and clone the repository in case I wanted to contribute something later on.  Simple install steps (using Fedora 18):

> git clone https://github.com/functional-koans/clojure-koans.git

> cd clojure-koans

> git checkout -b joe   # create a branch "joe" and switch to it

> cd src/koans

In a 2nd window, execute:

> cd clojure-koans

> lein koan run          # assumes you have leiningen 2 installed

The koans are essentially unit-tests, and the lein command in the 2nd window will start an auto-runner, which will run the tests and stop at the first failing one.  You should immediately see the output:

Starting auto-runner...

Considering src/koans/01_equalities.clj...

Now meditate upon src/koans/01_equalities.clj:3

---------------------

Assertion failed!

We shall contemplate truth by testing reality, via equality

(= __ true)

which indicates the first koan/test is failing.  Edit the indicated file src/koans/01_equalities.clj and replace the double-underscore placeholder __ with the answer true, then save the changed file.  The auto-runner then advances to the next koan:

Now meditate upon src/koans/01_equalities.clj:6
---------------------
Assertion failed!
To understand reality, we must compare our expectations against reality
(= __ (+ 1 1))

As you go along, you'll get hands-on practice learning Clojure, and will probably get tripped up at least a bit which will make those details more real and easier to remember (the one with slicing a vector via subvec highlighted a bad assumption I was making).  Since you are making changes to the source code in your new branch joe, you can periodically check your work into git via:

> git status
On branch joe
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   src/koans/01_equalities.clj
#       modified:   src/koans/02_lists.clj
#       modified:   src/koans/03_vectors.clj
#

> git commit -am'First 3 koan levels completed'

<output elided>

The reason you created and worked in the Git branch joe is that you can now use "git pull" to grab updates from the clojure-koans repo on GitHub without getting conflicts in your completed koans.  You can do a git merge later if you wish.

Enjoy!
Joe Cooljure


Below I have copied the original Unboxing post in case it ever disappears from the internet:
--------------------------------------------------------------------------------

Unboxing: Clojure Koans

Overview

In our latest Unboxing post Principal Developer Gavin Davies explores functional programming using Clojure Koans.

Author

Gavin Davies

Date

01 May 2013

About Unboxing

Unboxing is our regular feature where someone at Box UK spends a few hours playing with a new framework, library, tool or technique and blogs about his or her experience. You can read more Unboxing features here.

Clojure Koans

Over the last 18 months there's been a growing buzz in the Box UK developer community about functional programming. While I’ve done a bit of “functional-ish” stuff in JavaScript and used closures and first-order functions, most of my experience has been in the Object Oriented world, so I decided to learn a bit more about the functional programming paradigm.

Having seen two of our coders give tech talks on Clojure, I had a good idea of what I was aiming at but still wasn’t sure where to start. Dayle Rees recommended Clojure Koans to me so I got stuck in!

What is it?

Clojure Koans is a series of tiny steps towards learning Clojure. You learn by doing - each step is a tiny problem and you tackle them one at a time.

Getting to grips

I installed Clojure with the usual “sudo apt-get install clojure” routine then installed Leiningen, and started the project with a simple:

lein koan run

This ran a program in my console that automatically runs the tests every time I change anything in the directory. The first run showed that a test was failing:

gavin@GAV-UBUNTU ~/koans [master] % lein koan run

Starting auto-runner...

Considering ~/koans/src/koans/01_equalities.clj...

Now meditate upon ~/koans/src/koans/01_equalities.clj:3

---------------------

Assertion failed!

We shall contemplate truth by testing reality, via equality

(= __ true)

All I needed to do was open the source files and fix the steps! I created a project using Eclipse’s CounterClockwise plugin and opened the specified file:

(/opt/BoxUK/koans/src/koans/01_equalities.clj)

It was clear straight away what to do:

  (meditations

    "We shall contemplate truth by testing reality, via equality"

    (= __ true)

    ...

Aware that Lisp languages use a kind of Polish prefix notation, I fixed the code to read (= true true) and immediately the koan runner updated my console with a new job for me:

Considering ~/koans/src/koans/01_equalities.clj...

Now meditate upon ~/koans/src/koans/01_equalities.clj:6

---------------------

Assertion failed!

To understand reality, we must compare our expectations against reality

(= __ (+ 1 1))

I carried on working through the examples and quickly felt like I was starting to get a feel for this unfamiliar language.

Going deeper

It’s pretty much essential to keep a REPL open at all times and to run the little fragments of code.

For example, I got stuck on:

  "Or use the names of existing functions"

  (= __ (map nil? [:a :b nil :c :d]))

So I ran in the REPL:

user=> (map nil? [:a :b nil :c :d])

(false false true false false)

This illustrates more clearly what is going on and allows me to tinker. Actually moving things around is, for me, a much better way of learning than trying to execute unfamiliar code in my head; then, when the syntax makes sense to me, I am better able to mentally execute it.

I found it started getting quite difficult around part 13 which meant I had to do a lot more research, but, thankfully, the Clojure docs are largely example-driven.

I’ve long been eager to get to grips with functional programming and Clojure Koans has been a great springboard for me. It hasn’t made me an expert overnight of course, but it has allowed me to start putting things together. It drove me to the Clojure documentation a fair few times, which is a good thing; this style of learning is not spoon-feeding but is a great way to take small steps towards understanding. It’s an approach I would definitely recommend for learning new languages and techniques.

Want to know more?

“Tell me and I forget, teach me and I may remember, involve me and I learn.” - Benjamin Franklin

The Clojure website is clojure.org

Clojure Koans is available at:

https://github.com/functional-koans/clojure-koans

How to set up a Clojure nREPL using Vim & Fireplace.

One of the cool things about using Clojure is being able to evaluate code interactively in the read-eval-print-loop (REPL).  The  vim-fireplace project on GitHub (aka Foreplay) is the newest & best way to accomplish this from within the Vim/GVim editor, so you don't even have to switch windows to copy/paste code like you would with the normal "lein repl" command.

I recently installed Fedora 18 and was trying to get everything configured for Vim + Fireplace when I got stuck.  Fortunately google lead me to a very nice article from boxuk.com that helped to clear up the sticking points.

I'm pasting the blog contents below in case it ever disappears from the web:

--------------------------------------------------------------------------------------------------------

Unboxing: vim-fireplace

Overview

Rhodri Pugh introduces vim-fireplace, a plugin providing nREPL functionality for Clojure, to see how it compares with Swank and Slime.

Author

Rhodri Pugh

Date

28 May 2013

About Unboxing

Unboxing is our regular feature where someone at Box UK spends a few hours playing with a new framework, library, tool or technique and blogs about his or her experience. You can read more Unboxing features here.

vim-fireplace

I’ve been using Vim for a few years now, and love it. When developing with Clojure, however, I’ve always felt like I’ve been missing out on the tight integration my Emacs-touting colleagues seem to enjoy. I’ve tried picking up Emacs a few times, but have always ended up coming back to Vim as I just feel much more productive with my day-to-day languages.

Until now my setup has involved using a Slime plugin to send functions to a REPL running inside a Screen session. This actually works reasonably well; the plugin just grabs chunks of text and pipes them to the screen session. It’s agnostic to the source and destination, so can be useful for many things, but it does lack the aforementioned tight integration so I’ve always hoped for something better...

What is it?

Over the last year the Clojure community has moved away from using Swank/Slime to the nREPL protocol. For Vim, there is a plugin called vim-fireplace (previously vim-foreplay) which provides this functionality. This post is a little different to ourusual unboxings where the author has no experience of the tech, as I’ve been using this for a little while, but I want to take you through what vim-fireplace is and how nicely it works.

Getting to grips

Installation is pretty straightforward. I use vundle to manage my plugins, so installing vim-fireplace is as easy as adding it to my config:

Bundle ‘guns/vim-clojure-static’

Bundle ‘tpope/vim-fireplace’

I’ve also included the vim-clojure-static plugin which provides syntax highlighting, indentation and filetype settings for Clojure and ClojureScript. If you use Pathogen then you can find the repos to clone on Github.

Unlike with Emacs where (as I’m told, anyway) it’ll start an nREPL server for you when you ‘jack in’, we need to start the REPL that Vim is going to connect to. This is easy of course with Leiningen:

$> lein repl

nREPL server started on port 55983

REPL-y 0.1.10

Clojure 1.5.1

  Exit: Control+D or (exit) or (quit)

Commands: (user/help)

  Docs: (doc function-name-here)

        (find-doc "part-of-name-here")

Source: (source function-name-here)

        (user/sourcery function-name-here)

Javadoc: (javadoc java-object-or-class-here)

Examples from clojuredocs.org: [clojuredocs or cdoc]

        (user/clojuredocs name-here)

        (user/clojuredocs "ns-here" "name-here")

user=>

You’ll see that it prints out the port nREPL is listening on. This has also been written to the file target/repl-port which vim-fireplace will use. There’s no need to start Vim or nREPL before/after each other; any order will work. You can even restart the REPL and vim-fireplace will reconnect to the new one (or even connect to a running application!)

To test that it’s working, open a Clojure file from your project and enter :%Eval, which will evaluate the current namespace. You should see a message on the statusline that will be the result of the last expression in the file (probably a function name).

 

Then you can try executing some code. Type an invocation to one of the functions in your namespace, move the cursor to it, and then type :Eval. You should see the result of the function appear in the message window at the bottom of Vim:

Sweet! Let’s try some other features...

Going Deeper

Using :Eval and :%Eval is fine for a demo, but not for more than a few minutes. So, I added some handy key bindings (ctrl-e, and shift-e, respectively).

nnoremap <C-e> :Eval<CR>

nnoremap E :%Eval<CR>

This makes it really quick and easy to compile and evaluate forms, and error messages will be displayed right there in Vim when they occur (so, no need to switch to another application as I had to do before).

The next useful feature is the ability to access documentation and function source code.  Documentation can be accessed either by using :Doc FUNCTION_NAME, or more handily by using K while the cursor is over a function. This will then display the documentation for that function in a message window at the bottom of the screen. Here’s an example for clojure.core/map.

This isn’t just limited to the clojure.core docs; it’ll work for all your project code and any libraries you’re using. As you can imagine, having this information one keystroke away saves a lot of time. If the docs are not enough, you can also display the source for a function using [d, like...

It’s nice to see good example code from clojure.core, but it’s invaluable when looking up that function you just wrote that you now need to reference.

Want to know more?

After using vim-fireplace for a little while now it is such a massive step-up from my Slime + Screen setup it’s not even funny. I don’t know if this is on a par with Emacs’ nREPL yet (please post a comment if you know better), but to me it feels really, really well integrated, and I love it. The project is reasonably new and very active on Github, so hopefully it’s got a solid future.