NRuby

1
= 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 by basing the koans on tests.
6
Testing is not just something we pay lip service to, but something we
7
live.  Testing is essential in your quest to learn and do great things in Ruby.
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+, <em>etc</em>.  They are presented in
13
order in the +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 the koans you need +ruby+ and
27
+rake+ installed. To check your 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 <code>gem install rake</code>
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 +ruby_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 <em>red, green, refactor</em>.
73
Write a failing test and run it (<em>red</em>), make the test pass (<em>green</em>),
74
then look at the code and consider if you can make it any better (<em>refactor</em>).
75

76
While walking the path to Ruby enlightenment you will need to run the koan and
77
see it fail (<em>red</em>), make the test pass (<em>green</em>), then take a moment
78
and reflect upon the test to see what it is teaching you and improve the code to
79
better communicate its intent (<em>refactor</em>).
80

81
The very first time you run the koans you will see the following output:
82

83
    [ ruby_koans ] $ rake
84
    (in /Users/person/dev/ruby_koans)
85
    /usr/bin/ruby1.8 path_to_enlightenment.rb
86

87
    AboutAsserts#test_assert_truth has damaged your karma.
88

89
    The Master says:
90
    You have not yet reached enlightenment.
91

92
    The answers you seek...
93
    <false> is not true.
94

95
    Please meditate on the following code:
96
    ./about_asserts.rb:10:in `test_assert_truth'
97
    path_to_enlightenment.rb:38:in `each_with_index'
98
    path_to_enlightenment.rb:38
99

100
    mountains are merely mountains
101
    your path thus far [X_________________________________________________] 0/280 (0%)
102

103
You have come to your first stage. Notice it is telling you where to look for
104
the first solution:
105

106
    Please meditate on the following code:
107
    ./about_asserts.rb:10:in `test_assert_truth'
108
    path_to_enlightenment.rb:38:in `each_with_index'
109
    path_to_enlightenment.rb:38
110

111
Open the +about_asserts.rb+ file and look at the first test:
112

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

118
Change the +false+ to +true+ and re-run the test.  After you are
119
done, think about what you are learning.  In this case, ignore everything except
120
the method name (+test_assert_truth+) and the parts inside the method (everything
121
before the +end+).
122

123
In this case the goal is for you to see that if you pass a value to the +assert+
124
method, it will either ensure it is +true+ and continue on, or fail if
125
the statement is +false+.
126

127
=== Running the Koans automatically
128

129
<em>This section is optional.</em>
130

131
Normally the path to enlightenment looks like this:
132

133
    cd ruby_koans
134
    rake
135
    # edit
136
    rake
137
    # edit
138
    rake
139
    # etc
140

141
If you prefer, you can keep the koans running in the background so that after you
142
make a change in your editor, the koans will immediately run again. This will
143
hopefully keep your focus on learning Ruby instead of on the command line.
144

145
Install the Ruby gem (library) called +observr+ and then ask it to
146
"watch" the koans for changes:
147

148
    cd ruby_koans
149
    rake
150
    # decide to run rake automatically from now on as you edit
151
    gem install observr
152
    observr ./koans/koans.watchr
153

154
== Inspiration
155

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

165
Mike Clark's post ::  http://www.clarkware.com/cgi/blosxom/2005/03/18
166
Meta Koans        ::  http://rubyquiz.com/quiz67.html
167
The Little Lisper ::  http://www.amazon.com/Little-LISPer-Third-Daniel-Friedman/dp/0023397632
168

169
== Other Resources
170

171
The Ruby Language               ::  http://ruby-lang.org
172
Try Ruby in your browser        ::  http://tryruby.org
173

174
Dave Thomas' introduction to Ruby Programming Ruby (the Pick Axe) ::  http://pragprog.com/titles/ruby/programming-ruby
175

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

178
= Other stuff
179

180
Author         :: Jim Weirich <jim@neo.org>
181
Author         :: Joe O'Brien <joe@objo.com>
182
Issue Tracker  :: https://github.com/edgecase/ruby_koans/issues
183
Requires       :: Ruby 1.8.x or later and Rake (any recent version)
184

185
= License
186

187
http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png
188

189
RubyKoans is released under a Creative Commons,
190
Attribution-NonCommercial-ShareAlike, Version 3.0
191
(http://creativecommons.org/licenses/by-nc-sa/3.0/) License.
192