Learn Ruby With the Neo Ruby Koans

The Koans walk you along the path to enlightenment in order to learn Ruby. The goal is to learn the Ruby language, syntax, structure, and some common functions and libraries. We also teach you culture. Testing is not just something we pay lip service to, but something we live. It is essential in your quest to learn and do great things in the language.

The Structure

Ruby Koans files

The koans are broken out into areas by file, hashes are covered in about_hashes.rb, modules are introduced in about_modules.rb, etc. They are presented in order in the path_to_enlightenment.rb file.

Each koan builds up your knowledge of Ruby and builds upon itself. It will stop at the first place you need to correct.

Some koans simply need to have the correct answer substituted for an incorrect one. Some, however, require you to supply your own answer. If you see the method __ (a double underscore) listed, it is a hint to you to supply your own code in order to make it work correctly.

Installing Ruby

These instructions are for Windows. We also have *nix instructions .

You must have a version of Ruby installed in order to run the Koans. Please take the time to download a version of Ruby that best suits your needs. The koans use features that are built into the ruby language so many ports of the Ruby Interpreter will run the koans without additional configuration or hacking. If you're unsure which version of ruby to install, the one click installer of MRI (Matz Ruby Interpreter) in the 1.8 series is probably perfect to get started.

If you're interested in running the Koans (or any other Ruby programs) in multiple Ruby versions then you'll probably want to download "Pik" which is a ruby package manager for windows ( http://github.com/vertiginous/pik ) which is based on the *nix tool RVM ( http://rvm.beginrescueend.com ).

So, follow this link and download any of the 1.8 packages: http://rubyforge.org/frs/?group_id=167&release_id=42563

Download it and double click the installer. This will place all the ruby libraries and executables into a directory on your local machine. If you happen to forget to tick the box that asks if you wish to alter your PATH variable (where the command line looks for programs to run when you're typing commands) then you can do that manually by:

  1. Find where you installed Ruby (usually C:\Ruby)
  2. Right click on My Computer (or the recent windows equal) and click "Properties"
  3. On the advanced tab click the button "Environmental Variables"
  4. Add "PATH-TO-RUBY\bin;" to the beginning (or end, or whereever)

Now open a command prompt and type "ruby -v" if you get a response and no error, then you've done it! Now that you have ruby installed you'll need to pull down the koans.

  1. Unzip to C:\oss\ruby_koans
  2. Open command prompt (start > run > type "cmd" hit enter)
  3. run (based on step 1) "cd C:\oss\ruby_koans"
  4. run "rake"

What Editors Can I Use?

These instructions are for Windows. We also have *nix instructions .

You can really use any editor you'd like, but here are some suggestions:

The Path to Enlightenment

These instructions are for Windows platforms. We also have *nix instructions .

You can run the tests by calling the path_to_enlightenment.rb file.

In your terminal, while in the ruby_koans directory, type:

C:\oss\ruby_koans > ruby path_to_enlightenment.rb

Red, Green, Refactor

In test-driven development (TDD) the mantra has always been red: write a failing test and run it, green: make the test pass, and refactor: look at the code and see if you can make it any better.

With the koans, you will need to run the tests and see it fail (red), make the test pass (green), then take a moment and reflect upon the test to see what it is teaching you and improve the code to better communicate its intent (refactor).

The very first time you run it you will see the following output:

C:\oss\ruby_koans > ruby path_to_enlightenment.rb
(in /Users/person/dev/ruby_koans)
cd koans

Thinking AboutAsserts
test_assert_truth has damaged your karma.

You have not yet reached enlightenment ...
<false> is not true.

Please meditate on the following code:
./about_asserts.rb:10:in `test_assert_truth'
path_to_enlightenment.rb:27

mountains are merely mountains

You have come to the first error. Notice you are told where to look for the error:

Please meditate on the following code:
./about_asserts.rb:10:in `test_assert_truth'
path_to_enlightenment.rb:27

You then open up the about_asserts.rb file in your text editor and look at line 10:

# We shall contemplate truth by testing reality, via asserts.
def test_assert_truth
  assert false # This should be true
end

You then change false to true and run the tests again. You should get a new error.

Before moving on, think about what you are learning.

In this specific case, ignore everything except the method name (test_assert_truth) and the parts inside the method (everything before the end). The goal is for you to see that if you pass a value to the assert method, it will either ensure it is true and continue on, or fail if in fact the statement is false.

Authors

Jim Weirich

@jimweirich

Joe O'Brien

@objo


License

Ruby Koans is released under a Creative Commons, Attribution-NonCommercial-ShareAlike License. @jimweirich


We Provide Private Training

Neo helps organizations access the full potential of the latest technologies and methodologies by offering structured training in areas such as Git, Ruby, Ruby on Rails, and Agile development. We specialize in building better software and staying on top of rapidly changing technologies. Let us bring that expertise to your business.

Inspiration

A special thanks to Mike Clark and Ara Howard for inspiring this project. Mike Clark wrote an excellent blog post about learning Ruby through unit testing. This sparked an idea that has taken a bit to solidify, that of bringing new rubyists into the community through testing. Ara Howard then gave us the idea for the Koans in his ruby quiz entry on Meta Koans (a must for any rubyist wanting to improve their skills). Also, "The Little Lisper" taught us all the value of the short questions/simple answers style of learning.

Mike Clark's post clarkware.com/cgi/blosxom/2005/03/18

Meta Koans rubyquiz.com/quiz67.html

The Little Lisper amazon.com/Little-LISPer-Third-Daniel-Friedman/dp/0023397632

Other Resources

Ruby Koans Issue Tracker pivotaltracker.com/projects/48111

Neo Ruby Koans on Github github.com/neo/ruby_koans

The Ruby Language ruby-lang.org

Try Ruby in your browser tryruby.org

Dave Thomas' introduction to Ruby Programming pragprog.com/titles/ruby/programming-ruby

The Pragmatic Studio Ruby Programming Online Course pragmaticstudio.com/ruby

Brian Marick's fantastic guide for beginners: Everyday Scripting with Ruby pragprog.com/titles/bmsft/everyday-scripting-with-ruby

Mountains are merely mountains