clojure-koans/README.md

146 lines
4.8 KiB
Markdown
Raw Normal View History

# Clojure Koans
The Clojure Koans are a fun and easy way to get started with Clojure - no
experience assumed or required. Just follow the instructions below to start
making tests pass!
2010-01-15 01:13:17 +00:00
2010-01-15 01:13:17 +00:00
### Getting Started
The easiest and fastest way to get the koans up and running is to [download the
latest zip file from Github](https://github.com/functional-koans/clojure-koans/downloads).
This way, you'll have all the dependencies you need, including Clojure itself
and JLine, and you can skip the rest of this section (skip to "Running the
Koans").
If you're starting from a cloned or forked repo, that's cool too. This way
you'll be able to track your progress in Git, and see how your answers compare
to others, by checking out the project's Network tab. You might want to create your
own branch - that way if you pull back the latest koans from master, it'll be a bit
easier to manage the inevitable conflicts if we make changes to exercises you've already
completed.
The only things you'll need to run the Clojure Koans are:
- JRE 1.5 or higher
2011-02-11 02:58:17 +00:00
- [clojure-1.3.0-alpha4.jar](https://github.com/downloads/clojure/clojure/clojure-1.3.0-alpha4.zip)
2011-02-11 02:58:17 +00:00
clojure-1.3.0-alpha4.jar needs to be in a directory `lib` under this project.
2011-01-06 23:10:47 +00:00
You can use [Leiningen](http://github.com/technomancy/leiningen) to
automatically install the Clojure jar in the right place. Leiningen will also
get you a couple more jarfiles, including JLine, which allows you some of the
functionality of readline (command-line history, for example).
After you have leiningen installed, run
2010-01-15 01:13:17 +00:00
`lein deps`
2010-11-01 18:13:48 +00:00
which will download all dependencies you need to run the Clojure koans.
2010-01-15 01:13:17 +00:00
### Running the Koans
2010-01-15 01:13:17 +00:00
To run the koans, simply run
2010-11-02 01:09:15 +00:00
`script/run` on Mac/\*nix
2010-11-02 01:09:15 +00:00
`script\run` on Windows
2010-10-29 15:07:11 +00:00
2010-11-01 18:13:48 +00:00
You'll see something like this:
FAIL in clojure.lang.PersistentList$EmptyList@1 (equalities.clj:1)
We shall contemplate truth by testing reality, via equality.
expected: (= __ true)
actual: (not (= :fill-in-the-blank true))
2010-11-01 18:13:48 +00:00
The output is telling you that you have a failing test in equalities.clj.
So open that file up and make it pass! In general, you just fill in the
blanks to make tests pass. Sometimes there are several (or even an infinite
number) of correct answers: any of them will work in these cases.
The koans differ from normal TDD in that the tests are already written for you,
so you'll have to pay close attention to the failure messages, because up until
the very end, making a test pass just means that the next failure message comes
up.
While it's very easy (especially at first) to just fill in the blanks making
things pass, you should work slowly, making sure you understand why the answer
is what it is. Enjoy your path to Clojure enlightenment!
2010-10-29 15:43:32 +00:00
2010-11-02 01:12:00 +00:00
### Trying more things out
There's a REPL (Read-Evaluate-Print Loop) included in the Clojure Koans. Just
run:
`script/repl` on Mac/\*nix
`script\repl` on Windows
Here are some interesting commands you might try, once you're in a running REPL:
(find-doc "vec")
(find-doc #"vec$")
(doc vec)
And if those still don't make sense:
(doc doc)
(doc find-doc)
will show you what those commands mean.
You can exit the REPL with `CTRL-d` on any OS.
2010-10-29 15:43:32 +00:00
### Contributing
2010-11-10 03:12:14 +00:00
Patches are encouraged! Make sure the answer sheet still passes (`script/test`,
or `script\test` on Windows), and send a pull request.
2010-10-29 15:43:32 +00:00
The file ideaboard.txt has lots of good ideas for new koans to start, or things
to add to existing koans. So write some fun exercises, add your answers to
`src/path_to_answer_sheet.clj`, and we'll get them in there!
Feel free to contact me (Colin Jones / trptcolin) on Github or elsewhere if you
have any questions or want more direction before you start pitching in.
2010-10-29 15:43:32 +00:00
### Contributors (in order of appearance)
- Aaron Bedra
- Colin Jones (maintainer)
- Eric Lavigne
- Nuno Marquez
- Micah Martin
2011-01-03 22:29:09 +00:00
- Michael Kohl
2011-01-12 22:41:39 +00:00
- Ben Lickly
2011-02-03 17:21:52 +00:00
- Alex Robbins
- Jaskirat Singh Veen
2011-03-29 23:41:19 +00:00
- Mark Simpson
2011-04-29 20:34:17 +00:00
- Mike Jansen
### Credits
These exercises were started by [Aaron Bedra](http://github.com/abedra) of
[Relevance, Inc.](http://github.com/relevance) in early 2010, as a learning
tool for newcomers to functional programming. Aaron's macro-fu makes these
2010-11-02 01:24:43 +00:00
koans extremely simple and fun to use, and to improve upon, and without
Relevance's initiative, this project would not exist.
Using the [koans](http://en.wikipedia.org/wiki/koan) metaphor as a tool for
learning a programming language started with the
[Ruby Koans](http://rubykoans.com) by [EdgeCase](http://github.com/edgecase).
### License
The use and distribution terms for this software are covered by the
Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
which can be found in the file epl-v10.html at the root of this distribution.
By using this software in any fashion, you are agreeing to be bound by
the terms of this license.