README.rdoc

   1 = EdgeCase Ruby Koans
   2
   3 The Ruby Koans walk you along the path to enlightenment in order to learn Ruby.
   4 The goal is to learn the Ruby language, syntax, structure, and some common
   5 functions and libraries. We also teach you culture. Testing is not just something we
   6 pay lip service to, but something we live.  It is essential in your quest to learn
   7 and do great things in the language.
   8
   9 == The Structure
  10
  11 The koans are broken out into areas by file, hashes are covered in about_hashes.rb,
  12 modules are introduced in about_modules.rb, etc.  They are presented in order in the
  13 path_to_enlightenment.rb file.
  14
  15 Each koan builds up your knowledge of Ruby and builds upon itself.  It will stop at
  16 the first place you need to correct.
  17
  18 Some koans simply need to have the correct answer substituted for an incorrect one.
  19 Some, however, require you to supply your own answer.  If you see the method __ (a
  20 double underscore) listed, it is a hint to you to supply your own code in order to
  21 make it work correctly.
  22
  23
  24 == The Path To Enlightenment
  25
  26 In order to achieve enlightenment you need to follow the path_to_enlightenment. This
  27 can be done in two ways
  28
  29 *nix platforms, from the koans directory
  30
  31     [ruby_koans] $ rake                           # runs the default target :walk_the_path
  32     [ruby_koans] $ ruby path_to_enlightenment.rb  # simply call the file directly
  33
  34 Windows is the same thing
  35
  36     c:\ruby_koans\rake                             # runs the default target :walk_the_path
  37     c:\ruby_koans\ruby path_to_enlightenment.rb    # simply call the file directly
  38
  39 === Red, Green, Refactor
  40
  41 In test-driven development the mantra has always been, red, green, refactor.  Write a
  42 failing test and run it (red), make the test pass (green), then refactor it (that is
  43 look at the code and see if you can make it any better.  In this case you will need
  44 to run the koan and see it fail (refactor), make the test pass (green), then take a
  45 moment and reflect upon the test to see what it is teaching you.
  46
  47 The very first time you run it you will see the following output:
  48
  49     [ ruby_koans ] $ rake
  50     (in /Users/person/dev/ruby_koans)
  51     cd koans
  52
  53     Thinking AboutAsserts
  54       test_assert_truth has damaged your karma.
  55
  56     You have not yet reached enlightenment ...
  57     <false> is not true.
  58
  59     Please meditate on the following code:
  60     ./about_basics.rb:10:in `test_assert_truth'
  61     path_to_enlightenment.rb:27
  62
  63     mountains are merely mountains
  64
  65 You have come to your first stage. If you notice it is telling you where to look for
  66 the first solution:
  67
  68     Please meditate on the following code:
  69     ./about_basics.rb:10:in `test_assert_truth'
  70     path_to_enlightenment.rb:27
  71
  72 We then open up the about_basics.rb file and look at the first test:
  73
  74     # We shall contemplate truth by testing reality, via asserts.
  75     def test_assert_truth
  76       assert false                # This should be true
  77     end
  78
  79 We then change the +false+ to +true+ and run the test again.  After you are
  80 done, think about what you are learning.  In this case, ignore everything except
  81 the method name (+test_assert_truth+) and the parts inside the method (everything
  82 before the +end+).
  83
  84 In this case the goal is for you to see that if you pass a value to the +assert+
  85 method, it will either ensure it is +true+ and continue on, or fail if in fact
  86 the statement is +false+.
  87
  88 == Inspiration
  89
  90 A special thanks to Mike Clark and Ara Howard for inspiring this project.  Mike Clark
  91 wrote an excellent blog post about learning Ruby through unit testing. This sparked
  92 an idea that has taken a bit to solidify, that of bringing new rubyists into the
  93 community through testing. Ara Howard then gave us the idea for the Koans in his
  94 ruby quiz entry an Meta Koans (a must for any rubyist wanting to improve their skills).
  95
  96 Mike Clark's post ::  http://www.clarkware.com/cgi/blosxom/2005/03/18
  97 Meta Koans        ::  http://rubyquiz.com/quiz67.html
  98
  99 == Other Resources
 100
 101 The Ruby Language               ::  http://ruby-lang.org
 102
 103 Dave Thomas' introduction to Ruby
 104 Programming Ruby (the Pick Axe) ::  http://pragprog.com/titles/ruby/programming-ruby
 105
 106 Brian Marick's fantastic guide for beginners
 107 Everyday Scripting with Ruby    ::  http://pragprog.com/titles/bmsft/everyday-scripting-with-ruby
 108
 109 Try Ruby in your browser        ::  http://tryruby.hobix.com/