= EdgeCase Ruby Koans
-The Ruby 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
+The Ruby 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.
+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
-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.
+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.
+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.
+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
+
+If you do not have Ruby setup, please visit http://ruby-lang.org/en/downloads/ for
+operating specific instructions. In order to run this you need ruby and rake
+installed. To check the installations simply type:
+
+*nix platforms from any terminal window:
+
+ [~] $ ruby --version
+ [~] $ rake --version
+
+Windows from the command prompt (cmd.exe)
+
+ c:\ruby --version
+ c:\rake --version
+
+If you don't have rake installed, just run `gem install rake`
+
+Any response for Ruby with a version number greater than 1.8 is fine (should be
+around 1.8.6 or more). Any version of rake will do.
+
+== Generating the Koans
+
+A fresh checkout will not include the koans, you will need to generate
+them.
+
+ [ruby_koans] $ rake gen # generates the koans directory
+
+If you need to regenerate the koans, thus wiping your current `koans`,
+
+ [ruby_koans] $ rake regen # regenerates the koans directory, wiping the original
== The Path To Enlightenment
-In order to achieve enlightenment you need to follow the path_to_enlightenment. This
-can be done in two ways
+You can run the tests through rake or by calling the file itself (rake is the
+recommended way to run them as we might build more functionality into this task).
*nix platforms, from the koans directory
- [koans] $ rake # runs the default target :walk_the_path
- [koans] $ ruby path_to_enlightenment.rb # simply call the file directly
-
+ [ruby_koans] $ rake # runs the default target :walk_the_path
+ [ruby_koans] $ ruby path_to_enlightenment.rb # simply call the file directly
+
Windows is the same thing
- c:\dev\koans\rake # runs the default target :walk_the_path
- c:\dev\koans\ruby path_to_enlightenment.rb # simply call the file directly
-
+ c:\ruby_koans\rake # runs the default target :walk_the_path
+ c:\ruby_koans\ruby path_to_enlightenment.rb # simply call the file directly
+
+=== Red, Green, Refactor
+
+In test-driven development the mantra has always been, red, green, refactor. Write a
+failing test and run it (red), make the test pass (green), then refactor it (that is
+look at the code and see if you can make it any better. In this case you will need
+to run the koan 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:
+
+ [ ruby_koans ] $ rake
+ (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 your first stage. If you notice it is telling you where to look for
+the first solution:
+
+ Please meditate on the following code:
+ ./about_asserts.rb:10:in `test_assert_truth'
+ path_to_enlightenment.rb:27
+
+We then open up the about_asserts.rb file and look at the first test:
+
+ # We shall contemplate truth by testing reality, via asserts.
+ def test_assert_truth
+ assert false # This should be true
+ end
+
+We then change the +false+ to +true+ and run the test again. After you are
+done, think about what you are learning. In this case, ignore everything except
+the method name (+test_assert_truth+) and the parts inside the method (everything
+before the +end+).
+
+In this case 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+.
+
+== 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 :: http://www.clarkware.com/cgi/blosxom/2005/03/18
+Meta Koans :: http://rubyquiz.com/quiz67.html
+The Little Lisper :: http://www.amazon.com/Little-LISPer-Third-Daniel-Friedman/dp/0023397632
+
+== Other Resources
+
+The Ruby Language :: http://ruby-lang.org
+Try Ruby in your browser :: http://tryruby.org
+
+Dave Thomas' introduction to Ruby Programming Ruby (the Pick Axe) :: http://pragprog.com/titles/ruby/programming-ruby
+
+Brian Marick's fantastic guide for beginners Everyday Scripting with Ruby :: http://pragprog.com/titles/bmsft/everyday-scripting-with-ruby
+
+= Other stuff
+
+Author :: Jim Weirich <jim@weirichhouse.org>
+Author :: Joe O'Brien <joe@edgecase.com>
+Issue Tracker :: http://www.pivotaltracker.com/projects/48111
+Requires :: Ruby 1.8.x or later and Rake (any recent version)
+
+= License
+
+http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png
+
+RubyKoans is released under a Creative Commons,
+Attribution-NonCommercial-ShareAlike, Version 3.0
+(http://creativecommons.org/licenses/by-nc-sa/3.0/) License.