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 == Installing Ruby
  24
  25 If you do not have Ruby setup, please visit http://ruby-lang.org/en/downloads/ for
  26 operating specific instructions.  In order to run this you need ruby and rake
  27 installed. To check the installations simply type:
  28
  29 *nix platforms from any terminal window:
  30
  31    [~] $ ruby --version
  32    [~] $ rake --version
  33
  34 Windows from the command prompt (cmd.exe)
  35
  36    c:\ruby --version
  37    c:\rake --version
  38
  39 If you don't have rake installed, just run `gem install rake`
  40
  41 Any response for Ruby with a version number greater than 1.8 is fine (should be
  42 around 1.8.6 or more). Any version of rake will do.
  43
  44 == Generating the Koans
  45
  46 A fresh checkout will not include the koans, you will need to generate
  47 them.
  48
  49     [ruby_koans] $ rake gen                       # generates the koans directory
  50
  51 If you need to regenerate the koans, thus wiping your current `koans`,
  52
  53     [ruby_koans] $ rake regen                     # regenerates the koans directory, wiping the original
  54
  55 == The Path To Enlightenment
  56
  57 You can run the tests through rake or by calling the file itself (rake is the
  58 recommended way to run them as we might build more functionality into this task).
  59
  60 *nix platforms, from the koans directory
  61
  62     [ruby_koans] $ rake                           # runs the default target :walk_the_path
  63     [ruby_koans] $ ruby path_to_enlightenment.rb  # simply call the file directly
  64
  65 Windows is the same thing
  66
  67     c:\ruby_koans\rake                             # runs the default target :walk_the_path
  68     c:\ruby_koans\ruby path_to_enlightenment.rb    # simply call the file directly
  69
  70 === Red, Green, Refactor
  71
  72 In test-driven development the mantra has always been, red, green, refactor.  Write a
  73 failing test and run it (red), make the test pass (green), then refactor it (that is
  74 look at the code and see if you can make it any better).  In this case you will need
  75 to run the koan and see it fail (red), make the test pass (green), then take a
  76 moment and reflect upon the test to see what it is teaching you and improve the
  77 code to better communicate its intent (refactor).
  78
  79 The very first time you run it you will see the following output:
  80
  81     [ ruby_koans ] $ rake
  82     (in /Users/person/dev/ruby_koans)
  83     /usr/bin/ruby1.8 path_to_enlightenment.rb
  84
  85     AboutAsserts#test_assert_truth has damaged your karma.
  86
  87     The Master says:
  88     You have not yet reached enlightenment.
  89
  90     The answers you seek...
  91     <false> is not true.
  92
  93     Please meditate on the following code:
  94     ./about_asserts.rb:10:in `test_assert_truth'
  95     path_to_enlightenment.rb:38:in `each_with_index'
  96     path_to_enlightenment.rb:38
  97
  98     mountains are merely mountains
  99     your path thus far [X_________________________________________________] 0/280
 100
 101 You have come to your first stage. If you notice it is telling you where to look for
 102 the first solution:
 103
 104     Please meditate on the following code:
 105     ./about_asserts.rb:10:in `test_assert_truth'
 106     path_to_enlightenment.rb:38:in `each_with_index'
 107     path_to_enlightenment.rb:38
 108
 109 We then open up the about_asserts.rb file and look at the first test:
 110
 111     # We shall contemplate truth by testing reality, via asserts.
 112     def test_assert_truth
 113       assert false                # This should be true
 114     end
 115
 116 We then change the +false+ to +true+ and run the test again.  After you are
 117 done, think about what you are learning.  In this case, ignore everything except
 118 the method name (+test_assert_truth+) and the parts inside the method (everything
 119 before the +end+).
 120
 121 In this case the goal is for you to see that if you pass a value to the +assert+
 122 method, it will either ensure it is +true+ and continue on, or fail if in fact
 123 the statement is +false+.
 124
 125 == Inspiration
 126
 127 A special thanks to Mike Clark and Ara Howard for inspiring this
 128 project.  Mike Clark wrote an excellent blog post about learning Ruby
 129 through unit testing. This sparked an idea that has taken a bit to
 130 solidify, that of bringing new rubyists into the community through
 131 testing. Ara Howard then gave us the idea for the Koans in his ruby
 132 quiz entry on Meta Koans (a must for any rubyist wanting to improve
 133 their skills).  Also, "The Little Lisper" taught us all the value of
 134 the short questions/simple answers style of learning.
 135
 136 Mike Clark's post ::  http://www.clarkware.com/cgi/blosxom/2005/03/18
 137 Meta Koans        ::  http://rubyquiz.com/quiz67.html
 138 The Little Lisper ::  http://www.amazon.com/Little-LISPer-Third-Daniel-Friedman/dp/0023397632
 139
 140 == Other Resources
 141
 142 The Ruby Language               ::  http://ruby-lang.org
 143 Try Ruby in your browser        ::  http://tryruby.org
 144
 145 Dave Thomas' introduction to Ruby Programming Ruby (the Pick Axe) ::  http://pragprog.com/titles/ruby/programming-ruby
 146
 147 Brian Marick's fantastic guide for beginners Everyday Scripting with Ruby    ::  http://pragprog.com/titles/bmsft/everyday-scripting-with-ruby
 148
 149 = Other stuff
 150
 151 Author         :: Jim Weirich <jim@weirichhouse.org>
 152 Author         :: Joe O'Brien <joe@edgecase.com>
 153 Issue Tracker  :: http://www.pivotaltracker.com/projects/48111
 154 Requires       :: Ruby 1.8.x or later and Rake (any recent version)
 155
 156 = License
 157
 158 http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png
 159
 160 RubyKoans is released under a Creative Commons,
 161 Attribution-NonCommercial-ShareAlike, Version 3.0
 162 (http://creativecommons.org/licenses/by-nc-sa/3.0/) License.