For a more flexible way of iterating over multidimensional arrays you could use nested for loops. An outer loop iterates over each row (subarray) and an inner loop iterates over each item in the current row. This technique works even when subarrays have varying numbers of items:
for row in multiarr for item in row
puts(item) end
end
INDEXING INTO ARRAYS
As with strings (see Chapter Three) , you can index from the end of an array using minus figures, where -1 is the index of the last element; and you can also use ranges:
arr = ['h','e','l','l','o',' ','w','o','r','l','d']
print( arr[0,5] ) print( arr[-5,5 ] ) print( arr[0..4] ) print( arr[-5..-1] )
#=> „hello‟ #=> „world‟ #=> „hello‟ #=> „world‟
Notice that, as with strings, when provide two integers in order to return a number of contiguous items from an array, the first integer is the start index while the second is a count of the number of items (not an index):
arr[0,5] # returns 5 chars - ["h", "e", "l", "l", "o"]
You can also make assignments by indexing into an array. Here, for example, I first create an empty array then put items into indexes 0, 1 and 3. The ‘empty’ slot at number 2 will be filled with a nil value:
CHAPTER FOUR
array_index.rb
array_assign.rb
55

THE BOOK OF RUBY
arr = []
arr[0] = [0]
arr[1] = ["one"] arr[3] = ["a", "b", "c"]
# arr now contains:
# [[0], ["one"], nil, ["a", "b", "c"]]
Once again, you can use start-end indexes, ranges and negative index values:
arr2 = ['h','e','l','l','o',' ','w','o','r','l','d']
arr2[0] = 'H'
arr2[2,2] = 'L', 'L' arr2[4..6] = 'O','-','W' arr2[-4,4] = 'a','l','d','o'
# arr2 now contains:
# ["H", "e", "L", "L", "O", "-", "W", "a", "l", "d", "o"]
COPYING ARRAYS
Note that when you use the assignment operator, =, to assign one array variable to another variable, you are actually assigning a reference to the array itself – you are not making a copy. You can use the clone method to make a new copy of the array:
arr1=['h','e','l','l','o',' ','w','o','r','l','d'] arr2=arr1
# arr2 is now the same as arr1. Change arr1 and arr2 changes too! arr3=arr1.clone
# arr3 is a copy of arr1. Change arr1 and arr2 is unaffected
56
array_copy.rb

TESTING ARRAYS FOR EQUALITY
A few words need to be said about the comparison operator <=>. This compares two arrays – let’s call them arr1 and arr2; it returns -1 if arr1 is less than arr2; it returns 0 if arr1 and arr2 are equal; it returns 1 if arr2 is greater than arr1. But how does Ruby determine if one array is ‘greater than’ or ‘less than’ another? It turns out that it compares each item in one array with the corresponding item in the other. When two values are not equal, the result of their comparison is returned. In other words if this comparison were made:
[0,10,20] <=> [0,20,20] . This operator is defined for many Ruby classes, including Array, String, Float, Date and Fixnum. The sort operator is not, however, defined for all classes (that is to say that it is not defined for the Object class from which all other classes are derived). One of the unfortunate consequences of this is that it cannot be used to sort arrays containing nil values. It is, however, possible to get around this limitation by defining your own sorting routine. This is done by sending a block to the sort method. We’ll look at blocks in detail in Chapter 10. For now, it is enough to know that the block here is a chunk of code which determines the comparison used by the sort method.
CHAPTER FOUR
array_compare.rb
array_sort.rb
57

THE BOOK OF RUBY
This is my sort routine:
arr.sort{ |a,b|
a.to_s <=> b.to_s }
Here arr is an array object and the variables a and b represent two contiguous array elements. I’ve converted each variable to a string using the to_s method; this converts nil to an empty string which will be sorted ‘low’. Note that, while my sorting block defines the sort order of the array items, it does not change the array items themselves. So nil will remain as nil and integers will remain as integers. The string conversion is only used to implement the comparison, not to change the array items.
COMPARING VALUES
The comparison ‘operator’ <=> (which is, in fact, a method) is defined in the Ruby module named Comparable. For now, you can think of a module as a sort of reusable ‘code library’. We’ll be looking more closely at modules in Chapter 12.
You can ‘include’ the Comparable module in your own classes. When this is done, you can override the <=> method to enable you to define exactly how comparisons will be made between specific types of object. For example, you may want to subclass Array so that comparisons are made based purely on the length of two Arrays rather than on the values of each item in the Array (which is the default, as explained earlier). This is how to might do this:
class MyArray < Array include Comparable def <=> ( anotherArray )
self.length <=> anotherArray.length
end end
58
comparisons.rb

Now, you can initialize two MyArray objects like this:
myarr1 = MyArray.new([0,1,2,3]) myarr2 = MyArray.new([1,2,3,4])
And you can use the <=> method defined in MyArray in order to make compari- sons:
# Two MyArray objects myarr1 <=> myarr2 # returns 0
This returns 0 which indicates that the two arrays are equal (since our <=> method evaluates equality according to length alone). If, on the other hand, we were to initialise two standard Arrays with exactly the same integer values, the Array class’s own <=> method would perform the comparsion:
# Two Array objects arr1 <=> arr2 # returns -1
Here -1 indicates that the first array evaluates to ‘less than’ the second array since the Array class’s <=> method compares the numerical values of each item in arr1 and these are less than the values of the items at the same indexes in arr2.
But what if you want to make ‘less than’, ‘equal to’ and ‘greater than’ compari- sons using the traditional programming notation:
< # less than == # equal to > # greater than
In the MyArray class, we can make comparisons of this sort without writing any additional code. This is due to the fact that the Comparable module, which has been included in the MyArray class, automatically supplies these three compari- son methods; each method makes its comparison based on the definition of the <=> method. Since our <=> makes its evaluation based on the number of items in an array, the < method evaluates to true when the first array is shorter than the second, == evaluates to true when both arrays are of equal length and > evaluates to true when the second array is longer than the first:
CHAPTER FOUR
59

THE BOOK OF RUBY
p( myarr1 < myarr2 ) #=> false p( myarr1 == myarr2 ) #=> true
The standard Array, class, however, does not include the Comparable module so, if you try to compare two ordinary arrays using <, == or >, Ruby will display an error message telling you that the method is undefined.
It turns out that it is easy to add these three methods to a subclass of Array. All you have to do is include Comparable, like this:
class Array2 < Array include Comparable end The Array2 class will now perform its comparisons based on the <=> method of Array – that is, by testing the values of the items stored in the array rather than merely testing the length of the array. Assuming the Array2 objects, arr1 and arr2, to be initialized with the same arrays which we previously used for myarr1 and myarr2, we would now see these results:
p( arr1 < arr2 ) #=> true p( arr1 > arr2 ) #=> false
ARRAY METHODS
Several of the standard array methods modify the array itself rather than return- ing a modified copy of the array. These include not only those methods marked with a terminating exclamation such as flatten! and compact! but also the method << which modifies the array to its left by adding to it the array on its right; the clear which removes all the elements from the array and delete and delete_at remove selected elements. 60 array_methods.rb HASHES While arrays provide a good way of indexing a collection of items by number, there may be times when it would be more convenient to index them in some other way. If, for example, you were creating a collection of recipes, it would be more meaningful to have each recipe indexed by name such as ‚Rich Chocolate Cake‛ and ‚Coq au Vin‛ rather than by numbers: 23, 87 and so on. Ruby has a class that lets you do just that. It’s called a Hash. This is the equiva- lent of what some other languages call a Dictionary. Just like a real dictionary, the entries are indexed by some unique key (in a dictionary, this would be a word) which is associated with a value (in a dictionary, this would be the defini- tion of the word). CREATING HASHES Just like an array, you can create a hash by creating a new instance of the Hash class: h1 = Hash.new h2 = Hash.new("Some kind of ring") Both the examples above create an empty Hash. A Hash object always has a default value – that is, a value that is returned when no specific value is found at a given index. In these examples, h2 is initialized with the default value, ‚Some kind of ring‛; h1 is not initialized with a value so its default value will be nil. Having created a Hash object, you can add items to it using an array-like syntax – that is, by placing the index in square brackets and using = to assign a value. The obvious difference here being that, with an array, the index (the ‘key’) must be an integer; with a Hash, it can be any unique data item: CHAPTER FOUR hash1.rb 61 THE BOOK OF RUBY h2['treasure1'] = 'Silver ring' h2['treasure2'] = 'Gold ring' h2['treasure3'] = 'Ruby ring' h2['treasure4'] = 'Sapphire ring' Often, the key may be a number or, as in the code above, a string. In principle, however, a key can be any type of object. Unique Keys? Take care when assigning keys to Hashes. If you use the same key twice in a Hash, you will end up overwriting the original value. This is just like assigning a value twice to the same index in an array. Con- sider this example: h2['treasure1'] = 'Silver ring' h2['treasure2'] = 'Gold ring' h2['treasure3'] = 'Ruby ring' h2['treasure1'] = 'Sapphire ring' Here the key ‘treasure1’ has been used twice. As a consequence, the original value, ‘Silver ring’ has been replaced by ‘Sapphire ring’, re- sulting in this Hash: {"treasure1"=>"Sapphire ring", "treasure2"=>"Gold ring", "treas- ure3"=>"Ruby ring"}
Given some class, X, the following assignment is perfectly legal: x1 = X.new('my Xobject')
h2[x1] = 'Diamond ring'
There is a shorthand way of creating Hashes and initializing them with key- value pairs. Just add a key followed by => and its associated value; each key- value pair should be separated by a comma and the whole lot placed inside a pair of curly brackets:
62

h1 = { 'room1'=>'The Treasure Room', 'room2'=>'The Throne Room',
'loc1'=>'A Forest Glade', 'loc2'=>'A Mountain Stream' }
INDEXING INTO A HASH
To access a value, place its key between square brackets:
puts(h1['room2']) #=> „The Throne Room‟
If you specify a key that does not exist, the default value is returned. Recall that we have not specified a default value for h1 but we have for h2:
p(h1['unknown_room']) #=> nil p(h2['unknown_treasure']) #=> 'Some kind of ring'
Use the default method to get the default value and the default= method to set it (see Chapter 2 for more information on get and set ‘accessor’ methods):
p(h1.default)
h1.default = 'A mysterious place'
COPYING A HASH
As with an array, you can assign one Hash variable to another, in which case both variables will refer to the same Hash and a change made using either variable will affect that Hash:
h4 = h1
h4['room1']=‟A new Room' puts(h1['room1']) #=> „A new Room‟
CHAPTER FOUR
hash2.rb
63

THE BOOK OF RUBY
If you want the two variables to refer to the same items in different Hash objects, use the clone method to make a new copy:
h5 = h1.clone
h5['room1'] = 'An even newer Room'
puts(h1['room1']) #=> „A new room' (i.e. its value is unchanged)
SORTING A HASH
As with the Array class, you may find a slight problem with the sort method of Hash. It expects to be dealing with keys of the same data type so if, for example, you merge two arrays, one of which uses integer keys and another of which uses strings, you won’t be able to sort the merged Hash. The solution to this problem is, as with Array, to write some code to perform a custom type of comparison and pass this to the sort method. You might give it a method, like this:
def sorted_hash( aHash ) return aHash.sort{
|a,b|
a.to_s <=> b.to_s
} end
This performs the sort based on the string representation (to_s) of each key in the Hash. In fact, the Hash sort method converts the Hash to a nested array of [key, value] arrays and sorts them using the Array sort method.
64
hash_sort.rb

HASH METHODS
The Hash class has numerous built-in methods. For example, to delete an item using its key ( someKey ) from a hash, aHash, use aHash.delete( someKey ). To test if a key or value exists use aHash.has_key?( someKey ) and aHash.has_value?( someValue ). To return a new hash created using the original hash’s values as keys, and its keys as values use aHash.invert; to return an array populated with the hash’s keys or with its values use aHash.keys and aHash.values, and so on.
The hash_methods.rb program demonstrates a number of these methods.
CHAPTER FOUR
hash_methods.rb
65

THE BOOK OF RUBY
p( h1.keys & h2.keys )
#=> ["key1", "key3", "key4"]
p( h1.values & h2.values ) #=> ["val1", "val2", "val4"]
# set intersection (keys) # set intersection (values) # concatenation
Digging Deeper
TREATING HASHES AS ARRAYS
The keys and values methods of Hash each return an array so you can use various Array methods to manipulate them. Here are a few simple examples:
h1 = {'key1'=>'val1', 'key2'=>'val2', 'key3'=>'val3', 'key4'=>'val4'} h2 = {'key1'=>'val1', 'KEY_TWO'=>'val2', 'key3'=>'VALUE_3', 'key4'=>'val4'}
p( h1.keys+h2.keys )
#=> [ "key1", "key2", "key3", "key4", "key1", "key3", "key4", "KEY_TWO"]
p( h1.values-h2.values ) # difference #=> ["val3"]
p( (h1.keys << h2.keys) ) # append #=> ["key1", "key2", "key3", "key4", ["key1", "key3", "key4", "KEY_TWO"]]
p( (h1.keys << h2.keys).flatten.reverse ) # „un-nest‟ arrays and reverse #=> ["KEY_TWO", "key4", "key3", "key1", "key4", "key3", "key2", "key1"]
APPENDING AND CONCATENATING
Be careful to note the difference between concatenating using + to add the values from the second array to the first and appending using << to add the second array as the final element of the first: 66 hash_ops.rb a =[1,2,3] b =[4,5,6] c=a+b #=>c=[1,2,3,4,5,6] a=[1,2,3] a << b #=> a=[1, 2, 3, [4, 5, 6]]
In addition << modifies the first (the ‘receiver’) array whereas + returns a new array but leaves the receiver array unchanged. Receivers, Messages and Methods In Object Oriented terminology, the object to which a method belongs is called the receiver. The idea is that instead of ‘calling functions’ as in procedural languages, ‘messages’ are sent to objects. For example, the message + 1 might be sent to an integer object while the message reverse might be sent to a string object. The object which ‘receives’ a message tries to find a way (that is a ‘method’) of responding to the message. A string object, for example, has a reverse method so is able to respond to the reverse message whereas an integer object has no such method so cannot respond. If, after appending an array with << you decide that you’d like to add the ele- ments from the appended array to the receiver array rather than have the ap- pended array itself ‘nested’ inside the receiver, you can do this using the flatten method: a=[1, 2, 3, [4, 5, 6]] a.flatten #=> [1, 2, 3, 4, 5, 6]
MATRICES AND VECTORS
Ruby provides the Matrix class which may contain rows and columns of values each of which can be represented as a vector (Ruby also supplies a Vector class). Matrices allow you to perform matrix arithmetic. For example, give two Matrix
CHAPTER FOUR
append_concat.rb
67

THE BOOK OF RUBY
objects, m1 and m2, you can add the values of each corresponding cell in the matrices like this:
m3 = m1+m2
SETS
The Set class implements a collection of unordered values with no duplicates. You can initialize a Set with an array of values in which case, duplicates are ignored:
Examples:
s1 = Set.new( [1,2,3, 4,5,2] )
s2 = Set.new( [1,1,2,3,4,4,5,1] )
s3 = Set.new( [1,2,100] )
weekdays = Set.new( %w( Monday, Tuesday, Wednesday, Thursday,
Friday, Saturday, Sunday ) ) You can add new values using the add method:
s1.add( 1000 )
The merge method combines values of one Set with another:
s1.merge(s2)
You can use == to test for equality. Two sets which contain the same values (remembering that duplicates will be removed when a Set is created) are consid- ered to be equal:
p( s1 == s2 ) #=> true
68
matrix.rb
sets.rb

CHAPTER FIVE Loops and Iterators
Much of programming is concerned with repetition. Maybe you want your program to beep ten times, read lines from a file just so long as there are more lines to read or display a warning until the user presses a key. Ruby provides a number of ways of performing this kind of repetition.
FOR LOOPS
In many programming languages, when you want to run a bit of code a certain number of times you can just put it inside a for loop. In most languages, you give a for loop a variable initialized with a starting value which is incremented by 1 on each turn through the loop until it meets some specific ending value. When the ending value is met, the for loop stops running. Here’s a version of this traditional type of for loop written in Pascal:
(* This is Pascal code, not Ruby! *) for i := 1 to 3 do
writeln( i );
You may recall from the last chapter that Ruby’s for loop doesn’t work like this at all! Instead of giving it a starting and ending value, we give the for loop a list of items and it iterates over them, one by one, assigning each value in turn to a loop variable until it gets to the end of the list.
for_loop.rb
69

THE BOOK OF RUBY
For example, here is a for loop that iterates over the items in an array, displaying each in turn:
# This is Ruby code... for i in [1,2,3] do
puts( i ) end
The for loop is more like the ‘for each’ iterator provided by some other pro- gramming languages. The items over which the loop iterates don’t have to be integers. This works just as well...
for s in ['one','two','three'] do puts( s )
end
The author of Ruby describes for as ‚syntax sugar‛ for the each method which is implemented by collection types such as Arrays, Sets, Hashes and Strings (a String being, in effect, a collection of characters). For the sake of comparison, this is one of the for loops shown above rewritten using the each method:
[1,2,3].each do |i| puts( i )
end
As you can see, there isn’t really all that much difference. To convert the for loop to an each iterator, all I’ve had to do is delete for and in and append .each to the array. Then I’ve put the iterator variable, i, between a pair of upright bars after do. Compare these other examples to see just how similar for loops are to each iterators:
# --- Example 1 ---
# i) for
for s in ['one','two','three'] do
puts( s ) end
70
each_loop.rb
for_each.rb

# ii) each ['one','two','three'].each do |s|
puts( s ) end
# --- Example 2 ---
# i) for
for x in [1, "two", [3,4,5] ] do puts( x ) end
# ii) each
[1, "two", [3,4,5] ].each do |x| puts( x ) end
Note, incidentally, that the do keyword is optional in a for loop that spans multiple lines but it is obligatory when it is written on a single line:
# Here the „do‟ keyword can be omitted for s in ['one','two','three']
puts( s ) end
# But here it is required
for s in ['one','two','three'] do puts( s ) end
How to write a ‘normal’ for loop...
If you miss the traditional type of for loop, you can always ‘fake’ it in Ruby by using a for loop to iterate over the values in a range. For ex- ample, this is how to use a for loop variable to count up from 1 to 10, displaying its value at each turn through the loop:
for i in (1..10) do puts( i )
end
CHAPTER FIVE
for_to.rb
71

THE BOOK OF RUBY
This example shows how both for and each can be used to iterate over the values in a range:
# for
for s in 1..3
puts( s ) end
# each (1..3).each do |s|
puts(s) end
Note, incidentally, that a range expression such as 1..3 must be enclosed between round brackets when used with the each method, otherwise Ruby assumes that you are attempting to use each as a method of the final integer (a Fixnum) rather than of the entire expression (a Range). The brackets are optional when a range is used in a for loop.
MULTIPLE ITERATOR ARGUMENTS
You may recall that in the last chapter we used a for loop with more than one loop variable. We did this in order to iterate over a multi-dimensional array. On each turn through the for loop, a variable was assigned one row (that is, one ‘sub-array’) from the outer array:
# Here multiarr is an array containing two „rows‟ # (sub-arrays) at index 0 and 1
multiarr = [ ['one','two','three','four'],
[1,2,3,4] ]
72
for_each2.rb
multi_array.rb

# This for loop runs twice (once for each „row‟ of multiarr) for (a,b,c,d) in multiarr
print("a=#{a}, b=#{b}, c=#{c}, d=#{d}\n" ) end
The above loop prints this:
a=one, b=two, c=three, d=four a=1, b=2, c=3, d=4
We could use the each method to iterate over this four-item array by passing four ‘block parameters’ - a, b, c, d – into the block delimited by do and end at each iteration:
multiarr.each do |a,b,c,d|
print("a=#{a}, b=#{b}, c=#{c}, d=#{d}\n" )
end
Block Parameters
In Ruby the body of an iterator is called a ‘block’ and any variables declared between upright bars at the top of a block are called ‘block parameters’. In a way, a block works like a function and the block pa- rameters work like a function’s argument list. The each method runs the code inside the block and passes to it the arguments supplied by a collection (such as the array, multiarr). In the example above, the each method repeatedly passes an array of four elements to the block and those elements initialize the four block parameters, a, b, c, d. Blocks can be used for other things, in addition to iterating over col- lections. I’ll have more to say on blocks in Chapter 10.
CHAPTER FIVE
73

THE BOOK OF RUBY
BLOCKS
Ruby has an alternative syntax for delimiting blocks. Instead of using do..end, you can use curly braces {..} like this:
# do..end [[1,2,3],[3,4,5],[6,7,8]].each do
|a,b,c|
puts( "#{a}, #{b}, #{c}" )
end
# curly braces {..} [[1,2,3],[3,4,5],[6,7,8]].each{
|a,b,c|
puts( "#{a}, #{b}, #{c}" )
}
No matter which block delimiters you use, you must ensure that the opening delimiter, ‘{‘ or ‘do‟, is placed on the same line as the each method. Inserting a line break between each and the opening block delimiter is a syntax error.
WHILE LOOPS
Ruby has a few other loop constructs too. This is how to do a while loop:
while tired sleep
end
Or, to put it another way:
sleep while tired
Even though the syntax of these two examples is different they perform the same function. In the first example, the code between while and end (here a call to a method named sleep) executes just as long as the Boolean condition (which, in 74
block_syntax.rb

this case, is the value returned by a method called tired) evaluates to true. As in for loops the keyword do may optionally be placed between the test condition and the code to be executed when these appear on separate lines; the do keyword is obligatory when the test condition and the code to be executed appear on the same line.
WHILE MODIFIERS
In the second version of the loop (sleep while tired), the code to be executed (sleep) precedes the test condition (while tired). This syntax is called a ‘while modifier’. When you want to execute several expressions using this syntax, you can put them between the begin and end keywords:
begin sleep
snore
end while tired
This is an example showing the various alternative syntaxes:
$hours_asleep = 0
def tired
if $hours_asleep >= 8 then
$hours_asleep = 0
return false else
$hours_asleep += 1
return true end
end
def snore puts('snore....')
end
CHAPTER FIVE
1loops.rb
75

THE BOOK OF RUBY
def sleep
puts("z" * $hours_asleep )
end
while tired do sleep end
while tired sleep
end
sleep while tired
begin sleep
snore
end while tired
# a single-line while loop # a multi-line while loop
# single-line while modifier # multi-line while modifier
The last example above (the multi-line while modifier) needs close consideration as it introduces some important new behaviour. When a block of code delimited by begin and end precedes the while test, that code always executes at least once. In the other types of while loop, the code may never execute at all if the Boolean condition initially evaluates to true.
Ensuring a Loop Executes At Least Once
Usually a while loops executes 0 or more times since the Boolean test is evaluated before the loop executes; if the test returns false at the outset, the code inside the loop never runs.
However, when the while test follows a block of code enclosed be- tween begin and end, the loop executes 1 or more times as the Boo- lean expression is evaluated after the code inside the loop executes.
76

CHAPTER FIVE
2loops.rb
To appreciate the differences in behaviour of these two types of while loop, run 2loops.rb.
These examples should help to clarify:
x = 100
# The code in this loop never runs while (x < 100) do puts('x < 100') end # The code in this loop never runs puts('x < 100') while (x < 100) # But the code in loop runs once begin puts('x < 100') end while (x < 100) UNTIL LOOPS Ruby also has an until loop which can be thought of as a ‘while not’ loop. Its syntax and options are the same as those applying to while – that is, the test condition and the code to be executed can be placed on a single line (in which case the do keyword is obligatory) or then can be placed on separate lines (in which case do is optional). There is also an until modifier which lets you put the code before the test condi- tion and an option to enclose the code between begin and end in order to ensure that the code block is run at least once. 77 THE BOOK OF RUBY Here are some simple examples of until loops: i = 10 until i == 10 do puts(i) end # never executes until i == 10 puts(i) i += 1 end puts(i) until i == 10 begin puts(i) end until i == 10 # never executes # never executes # executes once Both while and until loops can, just like a for loop, be used to iterate over arrays and other collections. For example, this is how to iterate over all the elements in an array: while i < arr.length puts(arr[i]) i += 1 end until i == arr.length puts(arr[i]) i +=1 end 78 until.rb LOOP The examples in 3loops.rb should all look pretty familiar – with the exception of the last one: loop { puts(arr[i]) i+=1 if (i == arr.length) then break end } This uses the loop method repeatedly to execute the block enclosed by curly braces. This is just like the iterator blocks we used earlier with the each method. Once again, we have a choice of block delimiters – either curly braces or do and end: puts( "\nloop" ) i=0 loop do puts(arr[i]) i+=1 if (i == arr.length) then break end end This code iterates through the array, arr, by incrementing a counter variable, i, and breaking out of the loop when the (i == arr.length) condition evaluates to true. You have to break out of a loop in this way since, unlike while or until, the loop method does not evaluate a test condition to determine whether or not to continue looping. Without a break it would loop forever. CHAPTER FIVE 3loops.rb 79 THE BOOK OF RUBY Digging Deeper Hashes, Arrays, Ranges and Sets all include a Ruby module called Enumerable. A module is a sort of code library (I’ll have more to say about modules in Chap- ter 12). In Chapter 4, I used the Comparable module to add comparison methods such as < and > to an array. You may recall that I did this by subclassing the Array class and ‘including’ the Comparable module into the subclass:
class Array2 < Array include Comparable end THE ENUMERABLE MODULE The Enumerable module is already included into the Ruby Array class and it provides arrays with a number of useful methods such as include? which returns true if a specific value is found in an array, min which returns the smallest value, max which returns the largest and collect which creates a new array made up of values returned from a block: 80 arr = [1,2,3,4,5] y = arr.collect{ |i| i } z=arr.collect{|i|i*i} arr.include?( 3 ) arr.include?( 6 ) arr.min arr.max #=> y = [1, 2, 3, 4] #=>z=[1,4,9,16,25]
#=> true #=> false #=> 1 #=> 5
These same methods are available to other collection classes just as long as those classes include Enumerable. Hash is such a class. Remember, however, that the items in a Hash are not indexed in sequential order so when you use the min and max methods these return the items that are lowest and highest according to
enum.rb
enum2.rb

their numerical value – here the items are strings and the numerical value is determined by the ASCII codes of the characters in the key.
CUSTOM COMPARISONS
But let’s suppose you would prefer min and max to return items based on some other criterion (say the length of a string)? The easiest way to do this would be to define the nature of the comparison inside a block. This is done in a similar manner to the sorting blocks I defined in Chapter 4. You may recall that we sorted a Hash (here the variable h) by passing a block to the sort method like this:
h.sort{ |a,b| a.to_s <=> b.to_s }
The two parameters, a and b, represent two items from the Hash which are compared using the <=> comparison method. We can similarly pass blocks to the max and min methods:
h.min{ |a,b| a[0].length <=> b[0].length } h.max{|a,b| a[0].length <=> b[0].length }
When a Hash passes items into a block it does so in the form of arrays, each of which contains a key-value pair. So, if a Hash contains items like this< {„one‟=>‟for sorrow‟, „two‟=>‟for joy‟} b[0].length
This ensures that the comparisons are based on the keys in the Hash.
CHAPTER FIVE
81

THE BOOK OF RUBY
If you want to compare the values rather than the keys, just set the array indexes to 1:
p( h.min{|a,b| a[1].length <=> b[1].length } ) p( h.max{|a,b| a[1].length <=> b[1].length } )
You could, of course, define other types of custom comparisons in your blocks. Let’s suppose, for example, that you want the strings ‘one’, ‘two’, ‘three’ and so on, to be evaluated in the order in which we would speak them. One way of doing this would be to create an ordered array of strings:
str_arr=['one','two','three','four','five','six','seven']
Now, if a Hash, h, contains these strings as keys, a block can use str_array as a
reference in order to determine the minimum and maximum values:
h.min{|a,b| str_arr.index(a[0]) <=> str_arr.index(b[0])} #=> ["one", "for sorrow"]
h.max{|a,b| str_arr.index(a[0]) <=> str_arr.index(b[0])} #=> ["seven", "for a secret never to be told"]
All the examples above, use the min and max methods of the Array and Hash classes. Remember that these methods are provided to those classes by the Enumerable module.
There may be occasions when it would be useful to be able to apply Enumerable methods such as max, min and collect to classes which do not descend from existing classes (such as Array) which implement those methods. You can do that by including the Enumerable module in your class and then writing an iterator method called each like this:
82
enum3.rb

class MyCollection include Enumerable
def initialize( someItems ) @items = someItems
end
def each @items.each{ |i|
yield( i ) }
end end
Here you could initialize a MyCollection object with an array, which will be stored in the instance variable, @items. When you call one of the methods provided by the Enumerable module (such as min, max or collect) this will, ‘behind the scenes’, call the each method in order to obtain each piece of data one at a time.
Now you can use the Enumerable methods with your MyCollection objects:
things = MyCollection.new(['x','yz','defgh','ij','klmno'])
p( things.min ) #=> "defgh" p( things.max ) #=> "yz"
p( things.collect{ |i| i.upcase } )
#=> ["X", "YZ", "DEFGH", "IJ", "KLMNO"]
You could similarly use your MyCollection class to process arrays such as the keys or values of Hashes. Currently the min and max methods adopt the default behaviour of performing comparisons based on numerical values so ‘xy’ will be considered to be ‘higher’ than ‘abcd’ on the basis of the characters’ ASCII values. If you want to perform some other type of comparison – say, by string length, so
CHAPTER FIVE
include_enum1.rb
include_enum2.rb
83

THE BOOK OF RUBY
that ‘abcd’ would be deemed to be higher than ‘xz’ - you can just override the min and max methods:
def min
@items.to_a.min{|a,b| a.length <=> b.length }
end
def max
@items.to_a.max{|a,b| a.length <=> b.length }
end
Each and Yield...
So what is really going on when a method from the Enumerable module makes use of the each method that you’ve written? It turns out that the Enumerable methods (min, max, collect and so forth) pass to the each method a block of code. This block of code expects to receive one piece of data at a time (namely each item from a collec- tion of some sort). Your each method supplies it with that item in the form of a block parameter, such as the parameter i here:
def each @items.each{ |i|
yield( i ) }
end
The keyword yield is a special bit of Ruby magic which here tells the code to run the block that was passed to the each method – that is, to run the code supplied by the Enumerator module’s min, max or col- lect methods. This means that the code of those methods can be used with all kinds of different types of collection. All you have to do is, i) include the Enumerable module into your class and ii) write an each method which determines which values will be used by the Enumer- able methods.
include_enum3.rb
84

CHAPTER SIX Conditional Statements
Computer programs, like Life Itself, are full of difficult decisions waiting to be made. Things like: If I stay in bed I will get more sleep, else I will have to go to work; if I go to work I will earn some money, else I will lose my job - and so on< We’ve already performed a number of if tests in previous programs. To take a simple example, this is from the Tax calculator in chapter one: if (subtotal < 0.0) then subtotal = 0.0 end In this program, the user was prompted to enter a value, subtotal, which was then used in order to calculate the tax due on it. If the user, in a fit of madness, enters a value less than 0, the if test spots this since the test (subtotal < 0.0) evaluates to true, which causes the body of the code between the if test and the end keyword to be executed; here, this sets the value of subtotal to 0. Equals once = or equals twice == ? In common with many other programming languages, Ruby uses one equals sign to assign a value = and two to test a value ==. 85 THE BOOK OF RUBY IF..THEN..ELSE A simple test like this has only one of two possible results. Either a bit of code is run or it isn’t, depending on whether the test evaluates to true or not. Often, you will need to have more than two possible outcomes. Let’s suppose, for example, that your program needs to follow one course of action if the day is a weekday and a different course of action if it is a weekend. You can test these conditions by adding an else section after the if section, like this: if aDay == 'Saturday' or aDay == 'Sunday' daytype = 'weekend' else daytype = 'weekday' end The if condition here is straightforward. It tests two possible conditions: 1) if the value of the variable aDay is equal to the string ‘Saturday’ or 2) if the value of aDay is equal to the string ‘Sunday’. If either of those conditions is true then the next line of code executes: daytype = 'weekend'; in all other cases, the code after else executes: daytype = 'weekday'. When an if test and the code to be executed are placed on separate lines, the then keyword is optional. When the test and the code are placed on a single line, the then keyword (or, if you prefer really terse code, a colon character) is obligatory: 86 if x == 1 then puts( 'ok' ) end if x == 1 : puts( 'ok' ) end if x == 1 puts( 'ok' ) end # with 'then' # with colon # syntax error! if_else.rb if_then.rb An if test isn’t restricted to evaluating just two conditions. Let’s suppose, for example, that your code needs to work out whether a certain day is a working day or a holiday. All weekdays are working days; all Saturdays are holidays but Sundays are only holidays when you are not working overtime. This is my first attempt to write a test to evaluate all these conditions: working_overtime = true if aDay == 'Saturday' or aDay == 'Sunday' and not working_overtime daytype = 'holiday' puts( "Hurrah!" ) else daytype = 'working day' end Unfortunately, this doesn’t have quite the effect intended. Remember that Saturday is always a holiday. But this code insists that ‘Saturday’ is a working day. This is because Ruby takes the test to mean: ‚If the day is Saturday and I am not working overtime, or if the day is Sunday and I am not working overtime‛ whereas what I really meant was ‚If the day is Saturday; or if the day is Sunday and I am not working overtime‛. The easiest way to resolve this ambiguity is to put brackets around any code to be evaluated as a single unit, like this: if aDay == 'Saturday' or (aDay == 'Sunday' and not working_overtime) AND..OR..NOT Incidentally, Ruby has two different syntaxes for testing Boolean (true/false) conditions. In the above example, I’ve used the English-language style operators: and, or and not. If you prefer you could use alternative operators similar to those used in many other programming languages, namely: && (and), || (or) and ! (not). Be careful, though, the two sets of operators aren’t completely interchangeable. For one thing, they have different precedence which means that when multiple operators are used in a single test the parts of the test may be evaluated in different orders depending on which operators you use. For example, look at this test: CHAPTER SIX and_or_wrong.rb and_or.rb 87 THE BOOK OF RUBY if aDay == 'Saturday' or aDay == 'Sunday' and not working_overtime daytype = 'holiday' end Assuming that the Boolean variable, working_overtime, is true, would this test succeed if the variable, aDay, were initialised with the string, ‘Saturday’? In other words, would daytype be assigned the value ‘holiday’ if aDay is ‘Saturday’? The answer is: no, it wouldn’t. The test will only success if aDay is either ‘Saturday’ or ‘Sunday’ and working_overtime is not true. Now consider this test: if aDay == 'Saturday' || aDay == 'Sunday' && !working_overtime daytype = 'holiday' end On the face of it, this is the same test as the last one; the only difference being that this time I’ve used the alternative syntax for the operators. However, the change is more than cosmetic since, if aDay is ‘Saturday’ this test evaluates to true and daytype is initialized with the value, ‘holiday’. This is because the || operator has a higher precedence than the or operator. So this test succeeds either if aDay is ‘Saturday’ or if aDay is ‘Sunday’ and working_overtime is not true. Refer to the Digging Deeper section at the end of this chapter for more on this. As a general principle, you would do well to decide which set of operators you prefer, stick to them and use brackets to avoid ambiguity. IF..ELSIF There will no doubt be occasions when you will need to take multiple different actions based on several alternative conditions. One way of doing this is by evaluating one if condition followed by a series of other test conditions placed after the keyword elsif. The whole lot must then be terminated using the end keyword. 88 days.rb For example, here I am repeatedly taking input from a user inside a while loop; an if condition tests if the user enters ‘q’ (I’ve used chomp() to remove the carriage return from the input); if ‘q’ is not entered the first elsif condition tests if the integer value of the input (input.to_i) is greater than 800; if this test fails the next elsif condition tests if it is less than or equal to 800: while input != 'q' do puts("Enter a number between 1 and 1000 (or 'q' to quit)") print("?- ") input = gets().chomp() if input == 'q' puts( "Bye" ) elsif input.to_i > 800
puts( "That's a high rate of pay!" ) elsif input.to_i <= 800 puts( "We can afford that" ) end end The problem with this program is that, even though it asks the user to enter a value between 1 and 1000, it accepts values less than 1 (incidentally, if you really want a salary in minus figures, I’ll be glad to offer you a job!) and greater than 1000 (in which case, don’t look to me for employment!). We can fix this by rewriting the two elsif conditions and adding an else section which executes if all the preceding tests fail: if input == 'q' puts( "Bye" ) elsif input.to_i > 800 && input.to_i <= 1000 puts( "That's a high rate of pay!" ) elsif input.to_i <= 800 && input.to_i > 0 puts( "We can afford that" )
else
puts( "I said: Enter a number between 1 and 1000!" )
end
CHAPTER SIX
if_elsif.rb
if_elsif2.rb
89

THE BOOK OF RUBY
if_else_alt.rb
Ruby also has a short-form notation for if..then..else in which a question mark ? replaces the if..then part and a colon : acts as else< < Test Condition > ? :
For example:
x == 10 ? puts("it's 10") : puts( "it's some other number" )
When the test condition is complex (if it uses ands and ors) you should enclose it in brackets. If the tests and code span several lines the ? must be placed on the same line as the preceding condition and the : must be placed on the same line as the code immediately follow- ing the ?. In other words, if you put a newline before the ? or the : you will generate a syntax error. This is an example of a valid multi- line code block:
(aDay == 'Saturday' or aDay == 'Sunday') ? daytype = 'weekend' :
daytype = 'weekday'
Here’s another example of a longer sequence of if..elsif sections followed by a catch-all else section. This time the trigger value, i, is an integer:
def showDay( i )
if i == 1 then puts("It's Monday" )
elsif i == 2 then puts("It's Tuesday" )
elsif i == 3 then puts("It's Wednesday" )
elsif i == 4 then puts("It's Thursday" )
elsif i == 5 then puts("It's Friday" )
elsif (6..7) === i then puts( "Yippee! It's the weekend! " ) else puts( "That's not a real day!" )
end
end
90
days2.rb

Notice that I’ve used a range (6..7) to match the two integer values for Saturday and Sunday. The === method (that is, three = characters) tests whether a value (here i) is a member of the range. In the above example, this< (6..7) === i 10000 && season == 'summer':
puts( "Yes, I really am happy!" )
'Very happy' #=> This value is „returned‟
when salary > 500000 && season == 'spring' : 'Pretty happy'
else puts( 'miserable' ) end
puts( happy ) #=> “Very happy”
96
case4.rb

Digging Deeper
BOOLEAN CONDITIONS
and &&
These operators evaluate the left-hand side then, only if the result is true, they evaluate the right-hand side; and has lower precedence than &&
or ||
These operators evaluate the left-hand side then, if the result is false, they evalu- ate the right-hand side; or has lower precedence than ||
not !
This negates a Boolean value – i.e. returns true when false and false when true.
Be careful when using the alternative Boolean operators. Due to the difference in precedence, conditions will be evaluated in different orders and may yield different results.
Consider the following:
# Example 1
if ( 1==3 ) and (2==1) || (3==3) then
puts('true') else
puts('false') end
# Example 2
if ( 1==3 ) and (2==1) or (3==3) then
puts('true') else
puts('false') end
CHAPTER SIX
boolean_ops.rb
97

THE BOOK OF RUBY
These may look the same at first sight. In fact, Example 1 prints ‘false’ while example 2, prints true. This is entirely due to the fact that or has lower prece- dence than ||. As a consequence, Example 1 tests: ‚if 1 equals 3 *false] and (either 2 equals 1 or 3 equals 3) [true+‛. As one of these two necessary conditions is false, the entire test returns false.
Now look at Example 2. This tests: ‚(if 1 equals 3 and 2 equals 1) *false] or 3 equals 3 [true+‛. This time, we only need one of the two tests to succeed; the second test evaluates to true so the entire tests returns true.
The side-effects of operator precedence in this kind of test can lead to very obscure bugs. You can avoid these by clarifying the meaning of the test using brackets. Here, I have rewritten Examples 1 and 2 above; in each case the addi- tion of one pair of brackets has inverted the initial Boolean value returned by the test:
# Example 1 (b) – now returns true if (( 1==3 ) and (2==1)) || (3==3) then
puts('true') else
puts('false') end
# Example 2 (b) – now returns false if ( 1==3 ) and ((2==1) or (3==3)) then
puts('true') else
puts('false') end
NEGATION
The negation operator, !, can be used at the start of an expression or, as an alternative, you can use the != (‘not equals’) operator between the left and right hand side of an expression:
98

!(1==1) #=> false 1!=1 #=> false
Alternatively, you can use not instead of ! not( 1==1 )
ECCENTRICITIES OF BOOLEAN OPERATORS
Be warned that Ruby’s Boolean operators can sometimes behave in a curious and unpredictable manner. For example< puts( (not( 1==1 )) ) puts( not( 1==1 ) ) puts( true && true && !(true) ) puts( true && true and !(true) ) puts( ((true) and (true)) ) puts( true && true ) puts( true and true ) # This is ok # This is a syntax error # This is ok # This is a syntax error # This is ok # This is ok # This is a syntax error In many cases, problems can be avoided by sticking to one style of operator (that is – either and, or, not or &&, ||, !) rather than mixing the two. In addition, the generous use of brackets is to be recommended! CATCH AND THROW Ruby provides a pair of methods, catch and throw, which can be used to break out of a block of code when some condition is met. This is Ruby’s nearest equiva- lent to a goto in some other programming languages. The block must begin with catch followed by a symbol (i.e. a unique identifier preceded by a colon), such as :done or :finished. The block itself may either be delimited by curly brackets or by the keywords do and end, like this: CHAPTER SIX eccentricities.rb 99 THE BOOK OF RUBY # think of this as a block called :done catch( :done ){ # some code here } # and this is a block called :finished catch( :finished ) do # some code here end Inside the block, you can call throw with a symbol as an argument. Normally you would call throw when some specific condition is met which makes it desirable to skip all the remaining code in the block. For instance, let’s assume the block contains some code that prompts the user to enter a number, divides some value by that number then goes on to do a multitude of other complex calculations with the result. Obviously, if the user enters 0 then none of the calculations that follow can be completed so you would want to skip them all by jumping right out of the block and continuing with any code that follows it. This is one way of doing that: catch( :finished) do print( 'Enter a number: ' ) num = gets().chomp.to_i if num == 0 then throw :finished # if num is 0, jump out of the block end # Here there may be hundreds of lines of # calculations based on the value of num # if num is 0 this code will be skipped end # the throw method causes execution to # jump to here – outside of the block puts( "Finished" ) 100 catch_throw.rb You can, in fact, have a call to throw outside the block, like this: def dothings( aNum ) i=0 while true puts( "I'm doing things..." ) i += 1 throw( :go_for_tea ) if (i == aNum ) end end catch( :go_for_tea ){ dothings(5) } # throws to end of go_to_tea block # this is the :go_to_tea block And you can have catch blocks nested inside other catch blocks, like this: catch( :finished) do print( 'Enter a number: ' ) num = gets().chomp.to_i if num == 0 then throw :finished end puts( 100 / num ) catch( :go_for_tea ){ dothings(5) } puts( "Things have all been done. Time for tea!" ) end As with gotos and jumps in other programming languages, catch and throw in Ruby should be used with great care as they break the logic of your code and can, potentially, introduce hard-to-find bugs. CHAPTER SIX 101 THE BOOK OF RUBY 102 CHAPTER SEVEN Methods We’ve used numerous methods throughout this book. On the whole, they aren’t particularly complicated things – so you may wonder why the present chapter, which is all about methods, is so long. As we shall discover, there is much more to methods than meets the eye. CLASS METHODS The methods we’ve been using so far have been ‘instance methods’. An instance method belongs to a specific instance of a class – in other words, to an individual object. It is also possible to write ‘class methods’. A class method belongs to the class itself. In order to define a class method you may precede the method name with the class name and a full stop: class MyClass def MyClass.classMethod puts( "This is a class method" ) end def instanceMethod puts( "This is an instance method" ) end end class_methods1.rb 103 THE BOOK OF RUBY You should use the class name when calling a class method: MyClass.classMethod A specific object cannot call a class method. Nor can a class call an instance method: MyClass.instanceMethod #=> Error! This is an „undefined method‟ ob.classMethod #=> Error! This is an „undefined method‟
CLASS VARIABLES
Class methods may remind you of the class variables (that is, variables whose names begin with @@). You may recall that we previously used class variables in a simple adventure game (see: 2adventure.rb in Chapter 2) to keep a tally of the total number of objects in the game; each time a new Thing object was created, 1 was added to the @@num_things class variable:
class Thing @@num_things = 0
def initialize( aName, aDescription ) @@num_things +=1
end end
Unlike an instance variable (in an object derived from a class), a class variable must be given a value when it is first declared:
@@classvar = 1000 # class variables must be initialized
Initialization of either instance or class variables within the body of the class only affect the values stored by the class itself. Class variables are available both to the class itself and to objects created from that class. However, each instance variable is unique; each object has its own copy of any instance variables – and the class itself may also have its own instance variables.
104

Instance variables begin with @ @myinstvar # instance variable
Class variables begin with @@ @@myclassvar # class variable
Instance methods are defined by: def def anInstanceMethod
# some code end
Class methods are defined by: def . def MyClass.aClassMethod
# some code end
To understand how a class may have instance variables, take a look at the class_methods2.rb program. This declares and initializes a class variable and an instance variable:
@@classvar = 1000 @instvar = 1000
It defines a class method, classMethod, which increments both these variables by 10 and an instance method, instanceMethod, which increments both va- riables by 1. Notice that I have also given a value to the instance variable, @instvar. I said earlier that initial values are not normally assigned to instance variables in this way. The exception to the rule is when you assign a value to an instance variable of the class itself rather than to an object derived from that class. The distinction should become clearer shortly.
I’ve written a few lines of code which create three instances of MyClass (the ob variable is initialized with a new instance on each turn through the loop), then calls both the class and instance methods:
CHAPTER SEVEN
Class and Instance Variables and Methods: Summary
class_methods2.rb
105

THE BOOK OF RUBY
for i in 0..2 do
ob = MyClass.new MyClass.classMethod ob.instanceMethod
puts( MyClass.showVars ) puts( ob.showVars )
end
I’ve also written another class method, MyClass.showVars, and an instance method, showVars, to display the values of @instvar and @@classvar at each turn through the loop. When you run the code, these are the values that are displayed:
(class method) @instvar = 1010, @@classvar = 1011 (instance method) @instvar = 1, @@classvar = 1011 (class method) @instvar = 1020, @@classvar = 1022 (instance method) @instvar = 1, @@classvar = 1022 (class method) @instvar = 1030, @@classvar = 1033 (instance method) @instvar = 1, @@classvar = 1033
You may need to look at these results carefully in order to see what is going on here. In summary, this is what is happening: the code in both the class method, MyClass.classMethod and the instance method, instanceMethod, increments both the class and instance variables, @@classvar and @instvar.
You can see clearly that the class variable is incremented by both these methods (the class method adds 10 to @@classvar whenever a new object is created while the instance method adds 1 to it). However, whenever a new object is created its instance variable is initialized to 1 by the instanceMethod. This is the expected behavior – since each object has its own copy of an instance variable but all objects share a unique class variable.
Perhaps less obvious is the fact that the class itself also has its own instance variable, @instvar. This is because, in Ruby, a class is an object and therefore, can contain instance variables, just like any other object. The MyClass variable, @instvar, is incremented by the class method, MyClass.classMethod:
@instvar += 10
106

Notice when the instance method, showVars, prints the value of @instvar, it prints the value stored in a specific object, ob; the value of ob’s @instvar is initially nil (not the value 1000 with which the MyClass variable, @instvar, was initialized) and this value is incremented by 1 in instanceMethod.
When the class method, MyClass.showVars, prints the value of @instvar, it prints the value stored in the class itself (in other words, MyClass’s @instvar is a different variable from ob’s @instvar). But when either method prints the value of the class variable, @@classvar, the value is the same.
Just remember that there is only ever one copy of a class variable but there may be many copies of instance variables. If this is still confusing, take a look at the inst_vars.rb program:
class MyClass @@classvar = 1000 @instvar = 1000
def MyClass.classMethod if @instvar == nil then
@instvar = 10 else
@instvar += 10 end
end
def instanceMethod
if @instvar == nil then
@instvar = 1 else
@instvar += 1 end
end end
ob = MyClass.new
puts MyClass.instance_variable_get(:@instvar)
CHAPTER SEVEN
inst_vars.rb
107

THE BOOK OF RUBY
puts( '--------------' ) for i in 0..2 do
# MyClass.classMethod
ob.instanceMethod
puts( "MyClass @instvar=#{MyClass.instance_variable_get(:@instvar)}") puts( "ob @instvar= #{ob.instance_variable_get(:@instvar)}" )
end
This time, instead of creating a new object instance at each turn through the loop, we create a single instance (ob) at the outset. When the ob.instanceMethod is called, @instvar is incremented by 1.
Here I’ve used a little trick to look inside the class and method and retrieve the value of @instvar using Ruby’s instance_get_variable method:
puts( "MyClass @instvar= #{MyClass.instance_variable_get(:@instvar)}" ) puts( "ob @instvar= #{ob.instance_variable_get(:@instvar)}" )
As we only ever increment the @instvar which belongs to the object ob, the value of its @instvar goes up from 1 to 3 as the for loop executes. But the @instvar which belongs to the MyClass class is never incremented; it remains at its initial value (1000)...
1000
--------------
MyClass @instvar= 1000 ob @instvar= 1
MyClass @instvar= 1000 ob @instvar= 2
MyClass @instvar= 1000 ob @instvar= 3
But now, uncomment this line...
MyClass.classMethod
This now calls a class method which increments @instvar by 10. This time when
you run the program you see that, as before, the @instvar variable of ob is 108

incremented by 1 on each turn through the loop while the @instvar variable of MyClass is incremented by 10...
1000
--------------
MyClass @instvar= 1010 ob @instvar= 1
MyClass @instvar= 1020 ob @instvar= 2
MyClass @instvar= 1030 ob @instvar= 3
A Class Is An Object
To understand this, just remember that a class is an object (actually, it’s an instance of the Class class!). The MyClass ‘class object’ has its own instance variable (@instvar) just as the ob object has its own instance variable (which, here, also happens to be called @instvar). Instance variables are always unique to an object instance – so no two objects (not even an object like MyClass which also happens to be a class!) can ever share a single instance variable.
WHAT ARE CLASS METHODS FOR?
But why, one may reasonably ask, would you ever want to create a class method rather than the more usual instance method? There are two main reasons: first, a class method can be used as a ‘ready-to-run function’ without having to go to the bother of creating an object just to use it and, secondly, it can be used on those occasions when you need to run a method before an object has been created.
For a few examples of using methods as ‘ready to run functions’, take a look at the File class. Many of its methods are class methods. This is because, most of the time you will be using them to do something to or return information on an existing file. You don’t need to create a File object to do that; instead you pass the file name as an argument to the class methods. Here are a few examples:
CHAPTER SEVEN
109

THE BOOK OF RUBY
fn = 'file_methods.rb' if File.exist?(fn) then
puts(File.expand_path(fn)) puts(File.basename(fn)) puts(File.dirname(fn)) puts(File.extname(fn)) puts(File.mtime(fn)) puts("#{File.size(fn)} bytes")
else
puts( "Can't find file!")
end
The other occasion when a class method is vital is when you need to use a method before an object has been created. The most important example of this is the new method.
You call the new method every time you create an object. Until the object has been created, you clearly cannot call one of its instance methods – because you can only call instance methods from an object that already exists. When you use new you are calling a method of the class itself and telling the class to create a new instance of itself.
RUBY CONSTRUCTORS – NEW OR INITIALIZE?
The method responsible for bringing an object into being is called the construc- tor. In Ruby, the constructor method is called new. The new method is a class method which, once it has created an object, will run an instance method named initialize if such a method exits.
In brief then, the new method is the constructor and the initialize method is used to initialize the values of any variables immediately after an object is created. But why can’t you just write your own new method and initialize variables in it? Well, let’s try that:
file_methods.rb
110

class MyClass
def initialize( aStr )
@avar = aStr end
def MyClass.new( aStr ) super
@anewvar = aStr.swapcase end
end
ob = MyClass.new( "hello world" ) puts( ob )
puts( ob.class )
Here, I’ve called the default new constructor using the super keyword to invoke the method of the super class. Then I’ve created a string instance variable, . So what do I end up with? Not, as you might suppose, a new MyClass object containing a couple of string variables. Remember that the last expression evaluated by a method in Ruby is the value returned by that method. The last expression evaluated by the new method here is a string. So when I
evaluate this< ob = MyClass.new( "hello world" ) Class #=> Class #=> Class #=> Class #=> Class
Now, some classes also have class methods – that is, methods which belong to the Class object itself. In that sense these are singleton methods of the Class object. Indeed, if you evaluate the following, you will be shown an array of method names which match the names of IO class methods:
p( IO.singleton_methods )
As explained earlier, when you write your own class methods you do so by prefacing the method name with the name of the class:
def MyClass.classMethod
It turns out that you can use a similar syntax when creating singleton classes for specific objects. This time you preface the method name with the name of the object:
def myObject.objectMethod
112
class_classes.rb

All Ruby objects are descendents of the Object class...
...and that includes the Class class! Curious as it may at first seem, each class from which an object is created is itself an object which de- scends from the Object class. To prove this, try out the class_hierarchy.rb program:
def showFamily( aClass ) if (aClass != nil) then
puts( "#{aClass} :: about to recurse with aClass.superclass = #{aClass.superclass}" )
showFamily( aClass.superclass ) end
end
Let’s look at a concrete example. Suppose you have a program containing Creature objects of many different species (maybe you are a veterinarian, the head keeper or a zoo or, like the author of this book, an enthusiastic player of adventure games); each creature has a method called talk which displays the vocal noise which each creature usually makes.
Here’s my Creature class and a few creature objects:
class Creature
def initialize( aSpeech )
@speech = aSpeech end
def talk
puts( @speech )
end end
cat = Creature.new( "miaow" ) dog = Creature.new( "woof" )
CHAPTER SEVEN
class_hierarchy.rb
singleton_meth1.rb
113

THE BOOK OF RUBY
budgie = Creature.new( "Who's a pretty boy, then!" ) werewolf = Creature.new( "growl" )
Then you suddenly realize that one of those creatures, and one alone, has addi- tional special behavior. On the night of a full moon the werewolf not only talks (‚growl‛); it also howls ("How-oo-oo-oo-oo!"). It really needs a howl method.
You could go back and add such a method to the Creature class but then you’d end up with howling dogs, cats and budgies too – which is not what you want. You could create a new Werewolf class which descends from Creature, but you will only ever have one werewolf (they are, alas, an endangered species) so why do you want a whole class for just that? Wouldn’t it make more sense to have a werewolf object which is the same as every other creature object apart from the fact that it also has a howl method? OK, so let’s do that by giving the werewolf its very own singleton method. Here goes:
def werewolf.howl
puts( "How-oo-oo-oo-oo!" )
end
Heck, we can do better than that! It only howls on a full moon so let’s make sure that, if asked to howl when the moon is new, it just growls. Here’s my finished method:
def werewolf.howl
if FULLMOON then
puts( "How-oo-oo-oo-oo!" ) else
talk end
end
Notice that, even though this method has been declared outside of the Creature class, it is able to call the instance method, talk. That’s because the howl method now lives ‘inside’ the werewolf object so has the same scope within that object as the talk method. It does not, however, live inside any of the werewolf’s fellow creatures; the howl method belongs to him and him alone. Try to make the budgie.howl and Ruby will inform you that howl is an undefined method.
114

Now, if you are debugging your code for your own use, having your program blow up thanks to an undefined method may be acceptable; but if your program does so out in the big, bad world of the ‘end user’, it is definitely not acceptable.
If you think undefined methods are likely to be a problem, you can take avoid- ance measures by testing if a singleton method exists before trying to use it. The Object class has a singleton_methods method which returns an array of single- ton method names. You can test a method name for inclusion using the Array class’s include? method. In singleton_meth2.rb, for example, I’ve programmed an ‘open the box’ game which has a number of Box objects only one of which, when opened, contains the star prize. I’ve named this special Box object star- prize and given it a singleton method called congratulate:
starprize = Box.new( "Star Prize" ) def starprize.congratulate
puts( "You've won a fabulous holiday in Grimsby!" ) end
The congratulate method should be called when the starprize box is opened. This bit of code (in which item is a Box object) ensures that this method (which does not exist in any other object) is not called when some other box is opened:
if item.singleton_methods.include?("congratulate") then item.congratulate
end
An alternative way of checking the validity of a method would be to pass that method name as a symbol (an identifier preceded by a colon) to the Object class’s respond_to? method:
if item.respond_to?( :congratulate ) then item.congratulate
end
We’ll look at another way of handling non-existent methods in Chap- ter 20.
CHAPTER SEVEN
singleton_meth2.rb
115

THE BOOK OF RUBY
SINGLETON CLASSES
A singleton method is a method which belongs to a single object. A singleton class, on the other hand, is a class which defines a single object. Confused? Me too. So let’s take a closer look at the darn’ things< Let’s suppose you create a few dozen objects, each of which is an instance of the Object class. Naturally they all have access to the usual Object class’s methods such as inspect and class. But now you decide that you want just one special object (for the sake of variety, let’s call him ob) which has one special method (let’s call it blather). You don’t want to define a whole new class for this one object since you will never again create any more objects with the blather method. So you create a class especially for little ob. You don’t need to name this class. You just tell it to attach itself to ob by putting a << between the keyword class and the name of the object. Then you add code to the class in the usual way: ob = Object.new # singleton class class << ob def blather( aStr ) puts("blather, blather #{aStr}") end end Now ob, and only ob, not only has all the usual methods of the Object class; it also has the methods (here just the blather method but there could, in principle, be many more) of its own special anonymous class: ob.blather( "weeble" ) #=> “blather, blather weeble”
If you’ve been paying close attention, you might have noticed that the singleton class seems to be doing something rather similar to a singleton method. With a singleton class, I can create an object and then add on extra methods packaged
116
singleton_class.rb

up inside an anonymous class. With singleton methods, I can create an object then add on methods one by one:
ob2 = Object.new
def ob2.blather( aStr ) # <= this is a singleton method puts( "grippity, grippity #{aStr}" ) end ob2.blather( "ping!" ) #=> grippity, grippity ping!
Similarly, I could rewrite the ‘star prize’ program. In the previous version I added on a singleton method, congratulate, to an object named starprize. I could just as easily have created a singleton class containing the congratulate method:
starprize = MyClass.new( "Star Prize" )
class << starprize def congratulate puts( "You've won a fabulous holiday in Grimsby!" ) end end In fact, the similarity is more than skin deep. The end result of the code above is that congratulate becomes a singleton method of starprize and I’ve been able to verify that using this test: if item.singleton_methods.include?("congratulate") Singleton Method, Singleton Class – What’s The Difference...? The short answer is: not a lot. These two syntaxes provide different ways of adding methods to a specific object rather than building those methods into its defining class. CHAPTER SEVEN singleton_class2.rb 117 THE BOOK OF RUBY OVERRIDING METHODS There are times when you may want to redefine a method that already exists in some class. We’ve done this before when, for example, we created classes with their own to_s methods to return a string representation. Every Ruby class, from Object downwards, has a to_s method. The to_s method of the Object class returns the class name and a hexadecimal representation of the object’s unique identifier. However, many Ruby classes have their own special versions of to_s. For example, Array.to_s concatenates and returns the values in the array. When a method in one class replaces a method of the same name in an ancestor class, it is said to ‘override’ that method. You can override methods that are defined in the standard class library such as to_s as well as methods defined in your own classes. If you need to add new behavior to an existing method, remember to call the superclass’s method using the super keyword at the start of the overridden method. Here is an example: class MyClass def sayHello return "Hello from MyClass" end def sayGoodbye return "Goodbye from MyClass" end end class MyOtherClass < MyClass def sayHello #overrides (and replaces) MyClass.sayHello return "Hello from MyOtherClass" end # overrides MyClass.sayHello but first calls that method # with super. So this version "adds to" MyClass.sayHello def sayGoodbye return super << " and also from MyOtherClass" end 118 override.rb # overrides default to_s method def to_s return "I am an instance of the #{self.class} class" end end PUBLIC, PRIVATE AND PROTECTED In some cases, you may want to restrict the ‘visibility’ of your methods to ensure that they cannot be called by code outside the class in which the methods occur. This may be useful when your class defines various ‘utility’ methods which it requires in order to perform certain functions which it does not intend for public consumption. By imposing access restrictions on those methods you can prevent programmers from using them for their own nefarious purposes. This means that you will be able to change the implementation of those methods at a later stage without having to worry that you are going to break somebody else’s code. Ruby provides three levels of method accessibility: public protected private As the name suggests, public methods are the most accessible and private methods are the least accessible. All your methods are public unless you specify otherwise. When a method is public, it is available to be used by the world outside the object in whose class it is defined. When a method is private, it can only be used by other methods inside the object in whose class it is defined. A protected method generally works in the same way as a private method with one tiny, but important difference: in addition to being visible to the methods of the current object, a protected method is also visible to objects of the same type when the second object is within the scope of the first object. CHAPTER SEVEN 119 THE BOOK OF RUBY The distinction between private and protected methods will probably be easier to understand when you see a working example. Consider this class: class MyClass private def priv puts( "private" ) end protected def prot puts( "protected" ) end public def pub puts( "public" ) end def useOb( anOb ) anOb.pub anOb.prot anOb.priv end end I’ve declared three methods, one for each level of accessibility. These levels are set by putting private, protected or public prior to one or more methods. The specified accessibility level remains in force for all subsequent methods until some other access level is specified. Note: public, private and protected may look like keywords. But they are, in fact, methods of the Module class. Finally, my class has a public method, useOb, which takes a MyOb object as an argument and calls the three methods, pub, prot and priv of that object. Now 120 pub_prot_priv.rb let’s see how a MyClass object can be used. First of all, I’ll create two instances of the class: myob = MyClass.new myob2 = MyClass.new Now, I try to call each of the three methods in turn< myob.pub myob.prot myob.priv # This works! Prints out “public” # This doesn‟t work! I get a „NoMethodError‟ # This doesn‟t work either - another „NoMethodError‟ From the above, it would seem that the public method is (as expected) visible from the world outside the object to which it applies. But both the private and the protected methods are invisible. This being so, what is the protected method for? Another example should help to clarify this: myob.useOb( myob2 ) This time, I am calling the public method useOb of the myob object and I am passing to it a second object, myob2, as an argument. The important thing to note is that myob and myob2 are instances of the same class. Now, recall what I said earlier: in addition to being visible to the methods of the current object, a protected method is also visible to objects of the same type when the second object is within the scope of the first object. This may sound like gobbledygook. Let’s see if we can start to make some sense out of it. In the program, the first MyClass object (here myob) has a second MyClass object within its scope when myob2 is passed as an argument to a method of myob. When this happens, you can think of myob2 are being present ‘inside’ myob. Now myob2 shares the scope of the ‘containing’ object, myob. In this special circumstance – when two objects of the same class are within the scope defined by that class – the protected methods of any objects of this class become visible. CHAPTER SEVEN 121 THE BOOK OF RUBY In the present case, the protected method, prot, of myob2 (or, at any rate, of the argument - here called anob - which ‘receives’ myob2) becomes visible and can be executed. Its private arguments, however, are not visible: def useOb( anOb ) anOb.pub anOb.prot # protected method can be called anOb.priv # but calling a private method results in an error end 122 Digging Deeper PROTECTED AND PRIVATE IN DESCENDENT CLASSES The same access rules apply when calling the methods of ancestor and descen- dent objects. That is, when you pass to a method an object (as an argument) which has the same class as the receiver object (i.e. the object to which the method belongs), the argument object can call the public and protected methods of the class but not its private methods. For an example of this, take a look at the protected.rb program. Here I have created a MyClass object called myob and a MyOtherClass object, myotherob, where MyOtherClass descends from MyClass. I try to pass myotherob as an argument to the myob public method, shout: myob.shout( myotherob ) But the shout method calls the private method, priv on the argument object: def shout( anOb ) # calls a private method puts( anOb.priv( "This is a #{anOb.class} - hurrah" ) ) end This won’t work! Ruby complains that the priv method is private. Similarly, were I to do it the other way around – that is, by passing the ancestor object, myob, as the argument and invoking the method shout on the descendent object, I would encounter the same error: myotherob.shout( myob ) The MyClass class also has another public method, exclaim. This one calls a protected method, prot: def exclaim( anOb ) # calls a protected method puts( anOb.prot( "This is a #{anOb.class} - hurrah" ) ) end CHAPTER SEVEN protected.rb 123 THE BOOK OF RUBY Now, I can pass either the MyClass object, myob, or the MyOtherClass object, myotherob, as an argument to the exclaim method and no error will occur when the protected method is called: myob.exclaim( myotherob ) # This is OK myotherob.exclaim( myob ) # And so is this... Needless to say, this only works when the two objects (the receiver and the argument) share the same line of descent. If you send an unrelated object as an argument, you would not be able to call methods of the receiver class, no matter what their protection levels. INVADING THE PRIVACY OF PRIVATE METHODS The whole point of a private method is that it cannot be called from outside the scope of the object to which it belongs. So this won’t work: class X private def priv( aStr ) puts("I'm private, " << aStr) end end ob = X.new ob.priv( "hello" ) # This fails However, it turns out that Ruby provides a ’get out clause’ (or maybe I should say a ‘get in’ clause?) in the form of a method called send. The send method invokes the method whose name matches that of a symbol (an identifier beginning with a colon such as :priv), which is passed as the first argument to send like this: ob.send( :priv, "hello" ) # This succeeds 124 send.rb Any arguments supplied after the symbol (like the string, ‚hello‛) are passed in the normal way to the specified method. Suffice to say that using send to gain public access to a private method is not generally a good idea (else, why would you have made the method private in the first place), so should be used with caution or not at all< SINGLETON CLASS METHODS Earlier on, we created class methods by appending a method name to the name of the class like this: def MyClass.classMethod There is a ‘shortcut’ syntax for doing this. Here is an example: class MyClass def MyClass.methodA puts("a") end class << self def methodB puts("b") end def methodC puts("c") end end end Here, methodA, methodB and methodC are all class methods of MyClass; methodA is declared using the syntax we used previously: CHAPTER SEVEN class_methods3.rb 125 THE BOOK OF RUBY def .
But methodB and methodC are declared using the syntax of instance methods:
def
So how come they end up as class methods? It’s all down to the fact that the method declarations have been placed inside this code:
class << self # some method declarations end This may remind you of the syntax used for declaring singleton classes. For example, in the singleton_class.rb program, you may recall that we first created an object named ob and then gave it its very own method, blather: class << ob def blather( aStr ) puts("blather, blather #{aStr}") end end The blather method here is singleton method of the ob object. Similarly, in the class_methods3.rb program, the methodB and methodC methods are singleton methods of self – and self happens to be the MyClass class. We can similarly add singleton methods from outside the class definition by using << followed by the class name, like this: class << MyClass def methodD puts( "d" ) end end 126 NESTED METHODS You can nest methods (have one method nested inside another). This gives you a way of dividing up a long method into reusable chunks. So, for example, if method x needs to do calculation y at several different points, you can put the y method inside the x method: class X def x print( "x:" ) def y print("ha! ") end def z print( "z:" ) y end y z end end Nested methods are not initially visible outside of the scope in which they are defined. So, in the above example, while y and z may be called from inside x, they may not be called by any other code: ob = X.new ob.y #<= error ob.z # <= error CHAPTER SEVEN nested_methods.rb 127 THE BOOK OF RUBY However, when you run a method that encloses nested methods, those nested methods will be brought into scope outside that method! class X def x print( "x:" ) def y print("y:") end def z print( "z:" ) y end end end ob = X.new ob.x puts ob.y puts ob.z 128 #=> x: #=> y: #=> z:y:
nested_methods2.rb

METHOD NAMES
As a final point, it’s worth mentioning that method names in Ruby almost always begin with a lowercase character like this:
def fred
However, that is a convention, not an obligation. It is also permissible to begin method names with capital letters, like this:
def Fred
Since the Fred method looks like a constant (it starts with a capital letter), you
would need to tell Ruby that it is a method when calling it by adding brackets:
Fred # <= Ruby complains „uninitialized constant Fred() # <= Ruby calls the Fred method On the whole it is better to stick to the convention of using method names that begin with a lowercase character. CHAPTER SEVEN method_names.rb 129 THE BOOK OF RUBY 130 CHAPTER EIGHT Passing Arguments and Returning Values In this chapter we’ll be looking at many of the effects and side-effects of passing arguments and returning values to and from methods. First, though, let’s take a moment to summarise the types of method which we’ve used up to now: 1. INSTANCE METHODS An instance method is declared inside a class definition and is intended for use by a specific object or ‘instance’ of the class, like this: class MyClass # declare instance method def instanceMethod puts( "This is an instance method" ) end end # create object ob = MyClass.new # use instance method ob.instanceMethod methods.rb 131 THE BOOK OF RUBY 2. CLASS METHODS A class method may be declared inside a class definition, in which case, a) the method name may be preceded by the class name or b) a class << self block may contain a ‘normal’ method definition; either way, a class method is intended for use by the class itself, not by a specific object, like this: class MyClass # a class method def MyClass.classmethod1 puts( "This is a class method" ) end # another class method class << self def classmethod2 puts( "This is another class method" ) end end end # call class methods from the class itself MyClass.classmethod1 MyClass.classmethod2 132 3. SINGLETON METHODS Singleton methods are methods which are added to a single object and cannot be used by other objects. A singleton method may be defined by appending the method name to the object name followed by a dot or by placing a ‘normal’ method definition inside an << self block like this: # create object ob = MyClass.new # define a singleton method def ob.singleton_method1 puts( "This is a singleton method" ) end # define another singleton method class << ob def singleton_method2 puts( "This is another singleton method" ) end end # use the singleton methods ob.singleton_method1 ob.singleton_method2 RETURNING VALUES In many programming languages, a distinction is made between functions or methods which return a value to the calling code and those which do not. In Pascal, for example, a function returns a value but a procedure does not. No such distinction is made in Ruby. All methods always return a value though you are not, of course, obliged to use it. CHAPTER EIGHT 133 THE BOOK OF RUBY When no return value is specified, Ruby methods return the result of the last expression evaluated. Consider this method: def method1 a=1 b=2 c=a+b #returns3 end The last expression evaluated is a + b which happens to return 3, so that is the value returned by this method. There may often be times when you don’t want to return the last expression evaluated. In such cases, you can specify the return value using the return keyword: def method2 a=1 b=2 c=a+b return b # returns 2 end A method is not obliged to make any assignments in order to return a value. A simple piece of data (that is, something that evaluates to itself), if this happens to be the last thing evaluated in a method, will be the value returned. When nothing is evaluated, nil is returned: def method3 "hello" # returns “hello” 134 end def method4 a=1+2 "goodbye" end # returns “goodbye” def method5 end # returns nil return_vals.rb My own programming prejudice is to write code that is clear and unambiguous whenever possible. For that reason, whenever I plan to use the value returned by a method, I prefer to specify it using the return keyword; only when I do not plan to use the returned value do I omit this. However, this is not obligatory – Ruby leaves the choice to you. RETURNING MULTIPLE VALUES But what about those occasions when you need a method to return more than one value? In other program languages you may be able to ‘fake’ this by passing arguments by reference (pointers to the original data items) rather than by value (a copy of the data); when you alter the values of ‘by reference’ arguments, you alter the original values without explicitly having to return any values to the calling code. Ruby doesn’t make a distinction between ‘by reference’ and ‘by value’ so this technique is not available to us (most of the time, anyway, though we shall see some exceptions to the rule shortly). However, Ruby is capable of returning multiple values all in one go, as shown here: def ret_things greeting = "Hello world" a=1 b = 2.0 return a, b, 3, "four", greeting, 6 * 10 end Multiple return values are placed into an array. If you were to evaluate ret_things.class, Ruby would inform you that the returned object is an Array. You could, however, explicitly return a different collection type such as a Hash: def ret_hash return {'a'=>'hello', 'b'=>'goodbye', 'c'=>'fare thee well'}
end
CHAPTER EIGHT
return_many.rb
135

THE BOOK OF RUBY
DEFAULT AND MULTIPLE ARGUMENTS
Ruby lets you specify default values for arguments. Default values can be as- signed in the parameter list of a method using the usual assignment operator:
def aMethod( a=10, b=20 )
If an unassigned variable is passed to that method, the default value will be assigned to it. If an assigned variable is passed, however, the assigned value takes precedence over the default:
def aMethod( a=10, b=20 ) return a, b
end
p( aMethod )
p( aMethod( 1 ))
p( aMethod( 1, 2 ))
#=> displays: [10, 20] #=> displays: [1, 20] #=> displays: [1, 2]
In some cases, a method may need to be capable of receiving an uncertain number of arguments – say, for example, a method which processes a variable length list of items. In this case, you can ‘mop up’ any number of trailing items by preceding the final argument with an asterisk:
def aMethod( a=10, b=20, c=100, *d ) return a, b, c, d
end
p( aMethod( 1,2,3,4,6 ) ) #=> displays: [1, 2, 3, [4, 6]]
ASSIGNMENT AND PARAMETER PASSING
Most of the time, Ruby methods come with two access points – like the doors into and out of a room. The argument list provides the way in; the return value provides the way out. Modifications made to the input arguments do not affect the original data for the simple reason that, when Ruby evaluates an expression, 136
default_args.rb

the result of that evaluation creates a new object – so any changes made to an argument only affect the new object, not the original piece of data. But there are exceptions to this rule, which we’ll look at presently.
Let’s start by looking at the simplest case: a method which takes one value as a named parameter and returns another value:
def change( x ) x += 1
return x end
On the face of it, you might think that we are dealing with a single object, x, here: the object, x, goes into the change method and the same object x is re- turned. In fact, that is not the case. One object goes in (the argument) and a different object comes out (the return value). You can easily verify this using the object_id method to show a number which uniquely identifies each object in your program:
num = 10
puts( "num.object_id=#{num.object_id}" ) num = change( num )
puts( "num.object_id=#{num.object_id}" )
The identifier of the variable, num, is different before and after we call the change method. This shows that, even though the variable name remains the same, the num object which is returned by the change method is different from the num object which was sent to it.
The method-call itself has nothing to do with the change of the object. You can verify this by running method_call.rb. This simply passes the num object to the change method and returns it:
def nochange( x ) return x
end
CHAPTER EIGHT
in_out.rb
method_call.rb
137

THE BOOK OF RUBY
In this case, the object_id is the same after num is returned as it was before num was sent to the method. In other words, the object that went into the method is exactly the same object as the one that came out again. Which leads to the inevi- table conclusion that there is something about the assignment in the change method (x += 1) that caused the creation of a new object.
But assignment itself isn’t the whole explanation. If you simply assign a variable to itself, no new object is created< num = 10 num = num # a new num object is not created So what if you assign to the object the same value which it already has? num = 10 num = 10 # a new num object is not created This demonstrates that assignment alone does not necessarily create a new object. Now let’s try assigning a new value< num = 10 num += 1 # this time a new num object is created By checking the object_id we are able to determine that when a new value is assigned to an existing variable, a new object is created. Most data items are treated as unique so one string ‚hello‛ is considered to be different from another string ‚hello‛ and one float 10.5 is considered to be different from another float 10.5. Thus, any string or float assignment will create a new object. But when working with integers, only when the assignment value is different from the previous value is a new object created. You can do all kinds of compli- cated operations on the right-hand part of the assignment but if the yielded value is the same as the original value, no new object is created< num = (((num + 1 - 1) * 100) / 100) # a new object is not created! 138 assignment.rb INTEGERS ARE SPECIAL In Ruby an integer (Fixnum) has a fixed identity. Every instance of the number 10 or every variable to which the value 10 is assigned will have the same ob- ject_id. The same can not be said of other data types. Each instance of a floating point number such as 10.5 or of a string such as ‚hello world‛ will be a different object with a unique object_id. Be aware that when you assign an integer to a variable, that variable will have the object_id of the integer itself. But when you assign some other type of data to a variable, a new object will be created even if the data itself is the same at each assignment: # 10 and x after each assignment are the same object puts( 10.object_id ) x = 10 puts( x.object_id ) x = 10 puts( x.object_id ) # 10.5 and x after each assignment are 3 different objects! puts( 10.5.object_id ) x = 10.5 puts( x.object_id ) x = 10.5 puts( x.object_id ) But why does all this matter? The answer is that it matters because of a few rare exceptions to the rule. As I said earlier, most of the time, a method has a well-defined way in and a well- defined way out. Once an argument goes inside a method, it enters a closed room. Any code outside that method has no way of learning about any changes that have been made to the argument until it comes out again in the form of a returned value. This is, in fact, one of the deep secrets of ‘pure’ object orientation. The implementation details of methods should, in principle, be hidden away – ‘encapsulated’. This ensures that code outside an object cannot be dependent on things that happen inside that object. CHAPTER EIGHT object_ids.rb 139 THE BOOK OF RUBY THE ONE-WAY-IN, ONE-WAY-OUT PRINCIPLE In most modern OOP languages such as Java and C#, encapsulation and informa- tion hiding are not rigorously enforced. In Smalltalk, on the other hand - that most famous and influential of OOP languages - encapsulation and information hiding are fundamental principles: if you send a variable, x, to a method y and the value of x is changed inside y, you cannot obtain the changed value of x from outside the method – unless the method explicitly returns that value. ‘Encapsulation’ or ‘Information Hiding’? Often these two terms are used interchangeably. To be nit-picking, however, there is a difference. Encapsulation refers to the grouping together of an object’s ‘state’ (its data) and the operations which may alter or interrogate its state (its methods). Information hiding refers to the fact that data is sealed off and can only be accessed using well-defined routes in and out – in object oriented terms this implies ‘accessor methods’ to get or return values. In procedural languages, information hiding may take other forms - for example, you might have to define interfaces to retrieve data from code ‘units’ or ‘modules’ rather than from objects. In OOP terms, encapsulation and information hiding are almost syn- onymous – true encapsulation necessarily implies that the internal data of an object is hidden. However, many modern ‘OOP languages’ such as Java, C#, C++ and Object Pascal are quite permissive in the degree to which information hiding is enforced (if at all). 140 Usually, Ruby adheres to this principle: arguments go into a method but any changes made inside the method cannot be accessed from the outside unless Ruby returns the changed value: def hidden( aStr, anotherStr ) anotherStr = aStr + " " + anotherStr return aStr + anotherStr.reverse end str1 = "dlrow" str2 = "olleh" str3 = hidden(str1, str2) puts( str1 ) puts( str2 ) puts( str3 ) # str3 receives returned value # input args: original values unchanged # returned value ( “dlrowhello world” ) It turns out that there are occasions when arguments passed to a Ruby method can be used like the ‘by reference’ arguments of other languages (that is, changes made inside the method may affect variables outside the method). This is due to the fact that some Ruby methods modify the original object rather than yielding a value and assigning this to a new object. For example, there are some methods ending with an exclamation mark which alter the original object. Similarly the String append method << concatenates the string on its right to the string on its left but does not create a new string object in the process: so the value of the string on the left is modified but the string object itself retains its original object_id. The consequence of this is that, if you use the << operator instead of the + opera- tor in a method, your results will change: CHAPTER EIGHT hidden.rb 141 THE BOOK OF RUBY def nothidden( aStr, anotherStr ) anotherStr = aStr << " " << anotherStr return aStr << anotherStr.reverse end str1 = "dlrow" str2 = "olleh" str3 = nothidden(str1, str2) puts( str1 ) world”) puts( str2 ) puts( str3 ) # input arg: changed (“dlrow ollehhello # unchanged # returned value(“dlrow ollehhello world”) The str_reverse.rb sample program should help to clarify this. This shows that when you use the reverse method, for example, no change is made to the ‘receiver object’ (that is, an object such as str1 here: str1.reverse). But when you use the reverse! method a change is made to the object (its letters are reversed). Even so, no new object is created: str1 is the same object before and after the reverse! method is called. Here reverse operates like most Ruby methods – it yields a value and, in order to use that value, you must assign it to a new object. So... str1 = "hello" str1.reverse Here, str1 is unaffected by calling reverse. It still has the value ‚hello‛ and it still has its original object_id. But... str1 = "hello" str1.reverse! 142 not_hidden.rb str_reverse.rb This time, str1 is changed (it becomes ‚olleh‛). Even so, no new object is created: str1 has the same object_id with which it started. Then again... str1 = "hello" str1 = str1.reverse This time, the value yielded by str1.reverse is assigned to str1. The yielded value is a new object, so str1 is now assigned the reversed string (‚olleh‛) and it now has a new object_id. Refer to the sample program, concat.rb, for an example of the string concatena- tion method, <<, which, just like those methods that end with !, modifies the receiver object without creating a new object: str1 = "hello" str2 = "world" str3 = "goodbye" str3 = str2 << str1 In this example, str1 is never modified so it has the same object_id throughout; str2 is modified through concatenation. However, the << operator does not create a new object so str2 also retains its original object_id. But str3 is a different object at the end than at the beginning: that is because it is assigned the value yielded by this expression: str2 << str1. This value happens to be the str2 object itself so the object_id of str3 is now identical with that of str2 (i.e. str2 and str3 now reference the same object). In summary, then, methods ending with a ! such as reverse!, plus some other methods such as the << concatenation method, change the value of the receiver object itself. Most other methods do not change the value of the receiver object and in order to make use of any new value yielded as a result of calling a method, you have to assign that value to a variable (or pass the yielded value as an argument to a method). CHAPTER EIGHT concat.rb 143 THE BOOK OF RUBY Modifying The Receiver Object Breaks Encapsulation The fact that a few methods modify the receiver object whereas most do not may seem harmless enough – but beware: this behaviour pro- vides you with the ability to retrieve the values of arguments ‘by ref- erence’ rather than retrieving values which are explicitly returned. Doing so breaks encapsulation by allowing your code to rely upon the internal implementation details of a method. This can potentially lead to unpredictable side-effects and, in my view, should be avoided. For a simple (but, in real-world programming, potentially serious) example of how the reliance on the modified values of arguments rather than on explicit return values can introduce undesirable dependencies on implementation details, see side_effects.rb. Here we have a method called stringProcess which takes two string arguments, messes about with them and returns the results. Let’s assume that the object of the exercise is to take two lowercase strings and return a single string which combines these two strings, separated by a space and with the first and last letters capitalized. So the two original strings might be ‚hello‛ and ‚world‛ and the returned string is ‚Hello worlD‛. But now we have an impatient programmer who can’t be bothered with return values. He notices that the modifications made inside the method change the values of the ingoing arguments. So, heck! (he decides) he might as well use the arguments themselves! He then goes away and writes a fabulously complicated text processing system with thousands of bits of code reliant on the changed values of those two arguments. But now the programmer who originally wrote the stringProcess method decides that the original implementation was inefficient or inelegant and so rewrites the code confident in the knowledge that the return value is unchanged (if ‚hello‛ and ‚world‛ are sent as arguments, ‚Hello worlD‛ will be returned). Aha! But the new implementation cause the values of the input arguments to be changed inside the body of the method. So the impatient programmer’s text processing system, which relies on those arguments rather than on the return value, is now filled with bits of text saying ‚hello Dlrow‛ instead of the ‚Hello 144 side_effects.rb worlD‛ he was expecting (actually, it turns out that his program was processing the works of Shakespeare so a generation of actors will end up declaiming: ‚To eb or ton to eb, that si the noitseuq...‛). This is the kind of unexpected side-effect which can easily be avoided by following the one-way-in and one-way-out principle< PARALLEL ASSIGNMENT I mentioned earlier that it is possible for a method to return multiple values, separated by commas. Often you will want to assign these returned values to a set of matching variables. In Ruby, this can be done in a single operation by parallel assignment. This means that you can have several variables to the left or an assignment operator and several values to the right. The values to the right will be assigned, in order, to the variables on the left, like this: s1, s2, s3 = "Hickory", "Dickory", "Dock" This ability not only gives you a shortcut way to make multiple assignments; it also lets you swap the values of variables (you just change their orders on either side of the assignment operator: i1 = 1 i2 = 2 i1, i2 = i2, i1 #=> i1 is now 2, i2 is 1
And you can make multiple assignments from the values returned by a method:
def returnArray( a, b, c ) a = "Hello, " + a
b = "Hi, " + b
c = "Good day, " + c return a, b, c
end
CHAPTER EIGHT
parallel_assign.rb
145

THE BOOK OF RUBY
x, y, z = returnArray( "Fred", "Bert", "Mary" )
If you specify more variables to the left than there are values on the right of an assignment, any ‘trailing’ variables will be assigned nil:
x, y, z, extravar = returnArray( "Fred", "Bert", "Mary" ) # extravar = nil
Multiple values returned by a method are put into an array. When you put an array to the right of a multiple-variable assignment, its individual elements will be assigned to each variable, and once again if too many variables are supplied, the extra ones will be assigned nil:
s1, s2, s3 = ["Ding", "Dong", "Bell"]
146

Digging Deeper
BY REFERENCE OR BY VALUE?
Search the Internet and you’ll soon find that Ruby programmers regularly get into arguments about whether Ruby passes arguments ‘by value’ or ‘by refer- ence’.
In many procedural programming languages such as Pascal and C and their derivatives there is a clear distinction between arguments passed by value or by reference.
A ‘by value’ argument is a copy of the original variable; you can pass it to a procedure, mess around with it and the value of the original value remains unchanged.
A ‘by reference’ argument, on the other hand, is a pointer to the original variable. When this gets passed to a procedure, you are not passing a new copy but a reference to the bit of memory in which the original data is stored. So any changes made inside the procedure are made to the original data and necessarily affect the value of the original variable.
It’s actually pretty easy to resolve this issue. If Ruby passes by value, then it makes a copy of the original variable and that copy will therefore have a differ- ent object_id. In fact, this is not the case. Try out the arg_passing.rb program to prove this point.
Now, it may well be that in certain circumstances the passing of arguments could, ‘behind the scenes’ so to speak, be implemented as ‘by value’. However, such implementation details should be of interest to writers of Ruby interpreters and compilers rather than to Ruby programmers. The plain fact of the matter is that, if you program in a ‘pure’ OOP way – by passing arguments into methods but only subsequently using the values which those methods return – the im- plementation details (by value or by reference) will be of no consequence to you.
Nevertheless, due to the fact that Ruby can occasionally modify arguments (for example using ! methods or << as explained earlier), some programmers have CHAPTER EIGHT arg_passing.rb 147 THE BOOK OF RUBY formed the habit of using the modified values of the arguments themselves (equivalent to using By Reference arguments in C) rather than using the values returned. In my view, this is a bad practice. It makes your programs reliant upon the implementation details of methods and should therefore, be avoided. ARE ASSIGNMENTS COPIES OR REFERENCES? I said earlier that a new object is created when a value is yielded by some expres- sion. So, for example, if you assign a new value to a variable called x, the object after the assignment will be a different object from the one before the assignment (that is, it will have a different object_id): x = 10 # this x has one object_id x +=1 # and this x has a different one But it isn’t the assignment that creates a new object. It is the value that is yielded which causes a new object to be created. In the above example, +=1 is an expres- sion that yields a value (x+=1 is equivalent to the expression x=x+1). Simple assignment of one variable to another does not create a new object. So let’s assume you have one variable called num and another called num2. If you assign num2 to num, both variables will refer to the same object. You can test this using the equals? method of the Object class: num = 11.5 num2 = 11.5 # num and num 2 are not equal puts( "num.equal?(num2) #{num.equal?(num2)}" ) num = num2 # but now they are equal puts( "num.equal?(num2) #{num.equal?(num2)}" ) 148 assign_ref.rb CHAPTER EIGHT equal_tests.rb Tests for equality: == or equal? By default (as defined in Ruby’s Kernel module) a test using == re- turns true when both objects being tested are the same object. So it will return false if the values are same but the objects are different: ob1 = Object.new ob2 = Object.new puts( ob1==ob2 ) #<= false In fact == is frequently overridden by classes such as String and will then return true when the values are the same but the objects are dif- ferent: s1 = "hello" s2 = "hello" puts( s1==s2 ) #<= true For that reason, the equal? method is preferable when you want to es- tablish if two variables refer to the same object: puts( s1.equal?(s2) ) #<= false 149 THE BOOK OF RUBY WHEN ARE TWO OBJECTS IDENTICAL? As a general rule, if you initialize ten variables with ten values, each variable will refer to a different object. For example, if you create two strings like this< s1 = "hello" s2 = "hello"
# Code to recover from the exception
end
Here is an example of an exception handler which deals with an attempt to divide by zero:
begin
x = 1/0
rescue Exception x=0
puts( $!.class )
puts( $! ) end
When this code is run, the attempt to divide by zero causes an exception. If unhandled (as in the sample program, div_by_zero.rb), the program will crash. However, by placing the troublesome code inside an exception handling block (between begin and end), I have been able to trap the Exception in the section beginning with rescue. The first thing I’ve done is to set the variable, x, to a meaningful value. Next come these two inscrutable statements:
puts( $!.class ) puts( $! )
In Ruby, $! is a global variable to which is assigned the last exception. Printing $!.class displays the class name, which here is ‚ZeroDivisionError‛; printing the variable $! alone has the effect of displaying the error message contained by the Exception object which here is ‚divided by 0‛.
154
exception1.rb
div_by_zero.rb

I am not generally too keen on relying upon global variables, particularly when they have ‘names’ as undescriptive as $!. Fortunately, there is an alternative. You can associate a variable name with the exception by placing the ‘assoc operator’, =>, after the class name of the exception and before the variable name:
rescue Exception => exc
You can now use the variable name (here exc) to refer to the Exception object:
puts( exc.class ) puts( exc )
Exceptions Have A Family Tree...
To understand how rescue clauses trap exceptions, just remember that, in Ruby, exceptions are objects and, like all other objects, they are defined by a class. There is, moreover, a clear ‘line of descent’ which starts, like all Ruby objects, with the Object class.
While it may seem pretty obvious that, when you divide by zero, you are going to get a ZeroDivisionError exception, in real world code, there may be times when the type of exception is not so predictable. Let’s suppose for instance, that you have a method which does a division based on two values supplied by a user:
def calc( val1, val2 ) return val1 / val2
end
This could potentially produce a variety of different exceptions. Obviously if the second value entered by the user is 0, we will get a ZeroDivisionError.
However, if the second value is a string, the exception will be a TypeError, whereas is the first value is a string it will be a NoMethodError (as the String Class does not define the ‘division operator’ / ). Here the rescue block handles all possible exceptions:
CHAPTER NINE
exception2.rb
exception_tree.rb
155

THE BOOK OF RUBY
def calc( val1, val2 ) begin
result = val1 / val2 rescue Exception => e
puts( e.class ) puts( e ) result = nil
end
return result end
Often it will be useful to take different actions for different exceptions. You can do that by adding multiple rescue clauses. Each rescue clause can handle multiple exception types, with the exception class names separated by commas. Here my calc method handles TypeError and NoMethodError exceptions in one clause with a catch-all Exception handler to deal with other exception types:
def calc( val1, val2 ) begin
result = val1 / val2
rescue TypeError, NoMethodError => e
puts( e.class )
puts( e )
puts( "One of the values is not a number!" ) result = nil
rescue Exception => e puts( e.class )
puts( e )
result = nil
end
return result end
156
multi_except.rb
multi_except2.rb

The Object class is the ultimate ancestor of all exceptions.
From Object, descends Exception, then StandardError and finally more specific types of exception such as ZeroDivisionError. You could, if you wished, write a rescue clause to deal with the Object class and, Object being the ancestor of all objects, this would, indeed, successfully match an exception object:
# This is possible... rescue Object => exc
However, it is generally more useful to try to match a relevant de- scendent of the Exception class. For good measure, it is often useful to append a generalized rescue clause to handle StandardError or Ex- ception objects, just in case an exception which you hadn’t thought of manages to slip through. You may want to run the exception_tree.rb program to view the family tree of the ZeroDivisionError exception.
When handling multiple exception types you should always put the rescue clauses dealing with specific exceptions first, then follow these with rescue clauses dealing with more generalized exceptions.
When a specific exception, such as TypeError, is handled, the begin..end excep- tion block exits so the flow of execution won’t ‘trickle down’ to more generalized rescue clauses. However, if you put a generalized exception handling rescue clause first, that will handle all exceptions so any more specific clauses lower down will never execute.
If, for example, I had reversed the order of the rescue clauses in my calc method, placing the generalized Exception handler first, this would match all exception types so the clause for the specific TypeError and NoMethodError exceptions would never be run:
CHAPTER NINE
exception_tree.rb
157

THE BOOK OF RUBY
# This is incorrect... rescue Exception => e
puts( e.class ) puts( e ) result = nil
rescue TypeError, NoMethodError => e
puts( e.class )
puts( e )
puts( "Oops! This message will never be displayed!" ) result = nil
end
ENSURE
There may be some circumstances in which you want to take some particular action whether or not an exception occurs. For example, whenever you are dealing with some kind of unpredictable input/output – say, when working with files and directories on disk – there is always the possibility that the location (the disk or directory) or the data source (the file) either may not be there at all or may provide some other kinds of problems – such the disk being full when you attempt to write to it or the file containing the wrong kind of data when you attempt to read from it.
You may need to perform some final ‘cleanup’ procedures – such as logging onto a specific working directory or closing a file which was previously opened - whether or not you have encountered any problems. You can do this by follow- ing a begin..rescue block of code with another block starting with the ensure keyword. The code in the ensure block will always execute – whether or not an exception has arisen beforehand.
Let’s look at two simple examples. In the first one, I try to log onto a disk and display the directory listing. At the end of this, I want to be sure that my working directory (given by Dir.getwd) is always restored to its original location. I do this by saving the original directory in the startdir variable and once again making this the working directory in the ensure block:
158
multi_except_err.rb

startdir = Dir.getwd
begin
Dir.chdir( "X:\\" ) puts( `dir` )
rescue Exception => e puts e.class
puts e
ensure
Dir.chdir( startdir )
end
Let’s now see how to deal with the problem of reading the incorrect data from a file. This might happen if the data is corrupt, if you accidentally open the wrong file or – quite simply – if your program code contains a bug.
Here I have a file, test.txt, containing six lines. The first five lines are numbers; the sixth line is not. My code opens this file and reads in all six lines:
f = File.new( "test.txt" ) begin
for i in (1..6) do
puts("line number: #{f.lineno}")
line = f.gets.chomp
num = line.to_i
puts( "Line '#{line}' is converted to #{num}" ) puts( 100 / num )
end
rescue Exception => e
puts( e.class )
puts( e ) ensure
f.close
puts( "File closed" ) end
CHAPTER NINE
ensure.rb
ensure2.rb
159

THE BOOK OF RUBY
The lines are read in as strings (using gets) and the code attempts to convert them to integers (using to_i). No error is produced when the conversion fails; instead Ruby returns the value 0.
The problem arises in the next line of code which attempts a division by the converted number. The sixth line of the input file contains the string ‚six‛ which yields 0 when a conversion to integer is attempted – and that inevitably causes an error when this value is used in a division.
Having opened the data file at the outset, I want to ensure that the file is closed whether or not an error occurs. If, for example, I only read in the first five lines by editing the range in the for loop to (1..5), then there would be no exception. I would still want to close the file.
But it would be no good putting the file closing code (f.close) in the rescue clause as it would not, in this case, be executed. By putting it in the ensure clause, however, I can be certain that the file will be closed whether or not an exception occurs.
ELSE
If the rescue section executes when an error occurs and ensure executes whether or not an error occurs, how can we specifically execute some code only when an error does not occur?
The way to do this is to add an optional else clause after the rescue section and before the ensure section (if there is one), like this:
begin
# code which may cause an exception
rescue [Exception Type]
else # optional section executes if no exception occurs ensure # optional exception always executes
end
160

This is an example:
def doCalc( aNum ) begin
result = 100 / aNum.to_i rescue Exception => e
result = 0
msg = "Error: " + e else
msg = "Result = #{result}" ensure
# executes when there is an error
# executes when there is no error
# always executes msg = "You entered '#{aNum}'. " + msg
end
return msg end
ERROR NUMBERS
If you ran the ensure.rb program earlier and you were watching closely you may have noticed something unusual when you tried to log onto a non-existent drive (for example, on my system that might be the ‚X:\‛ drive). Often, when an exception occurs, the exception class is an instance of a specific named type such as ZeroDivisionError or NoMethodError. In this case, however, the class of the exception is shown to be:
Errno::ENOENT
It turns out that there is quite a variety of Errno errors in Ruby. Try out disk_err.rb. This defines a method, chDisk, which attempts to log onto a disk identified by the character, aChar. So if you pass ‚A‛ as an argument to chDisk it will try to log onto the A:\ drive. I’ve called the chDisk method three times, passing to it a different string each time:
CHAPTER NINE
else.rb
161

THE BOOK OF RUBY
chDisk( "D" ) chDisk( "X" ) chDisk( "ABC" )
On my PC, D:\ is my DVD drive. At the moment it is empty and when my program tries to log onto it, Ruby returns an exception of this type:
Errno::EACCES
I have no X:\ drive on my PC and when I try to log onto that, Ruby returns an exception of this type:
Errno::ENOENT
In the last example, I pass a string parameter, ‚ABC‛ which is invalid as a disk identifier, and Ruby returns an exception of this type:
Errno::EINVAL
Errors of this type are descendents of the SystemCallError class. You can easily verify this by uncommenting the line of code to show the class’s family where indicated in the source code of disk_err.rb.
These classes, in effect, wrap up integer error values which are returned by the underlying operating system. Here Errno is the name of the module containing the constants, such as EACCES and ENOENT, which match the integer error values.
To see a complete list of Errno constants, run this: puts( Errno.constants )
To view the corresponding numerical value of any given constant, append ::Errno to the constant name, like this:
Errno::EINVAL::Errno
162
disk_err.rb

The following code can be used to display a list of all Errno constants along with their numerical values:
for err in Errno.constants do
errnum = eval( "Errno::#{err}::Errno" ) puts( "#{err}, #{errnum}" )
end
RETRY
If you think an error condition may be transient or may be corrected (by the user, perhaps?), you can rerun all the code in a begin..end block using the keyword retry, as in this example which prompts the user to re-enter a value if an error such as ZeroDivisionError occurs:
def doCalc begin
print( "Enter a number: " ) aNum = gets().chomp() result = 100 / aNum.to_i
rescue Exception => e
result = 0
puts( "Error: " + e + "\nPlease try again." ) retry # retry on exception
else
msg = "Result = #{result}"
ensure
msg = "You entered '#{aNum}'. " + msg
end
return msg end
There is, of course, the danger that the error may not be as transient as you think so, if you use retry, you may want to provide a clearly defined exit condition to ensure that the code stops executing after a fixed number of attempts.
CHAPTER NINE
errno.rb
retry.rb
163

THE BOOK OF RUBY
You could, for example, increment a local variable in the begin clause (if you do this, make sure it is incremented before any code that is liable to generate an exception since, once an exception occurs, the remainder of the code prior to the rescue clause will be skipped!). Then test the value of that variable in the rescue section, like this:
rescue Exception => e
if aValue < someValue then retry end Here is a complete example, in which I test the value of a variable named tries to ensure that no more than three tries to run the code without error before the exception-handling block exits: 164 def doCalc tries = 0 begin print( "Enter a number: " ) tries += 1 aNum = gets().chomp() result = 100 / aNum.to_i rescue Exception => e
msg = "Error: " + e
puts( msg )
puts( "tries = #{tries}" ) result = 0
if tries < 3 then retry end else msg = "Result = #{result}" ensure # set a fixed number of retries msg = "You entered '#{aNum}'. " + msg end return msg end retry2.rb RAISE Sometimes you may want to keep an exception ‘alive’ even after it has been trapped in an exception-handling block. This can be used, for example, to defer the handling of the exception – say, by passing it on to some other method. You can do this using the raise method. You need to be aware, however, that once raised, an exception needs to be re-handled otherwise it may cause your program to crash. Here is a simple example of raising a ZeroDivisionError exception and passing on the exception to a method called, in this case, handleError: begin divbyzero rescue Exception => e
puts( "A problem just occurred. Please wait..." ) x=0
begin
raise rescue
handleError( e ) end
end
Here divbyzero is the name of a method in which the divide-by-zero operation takes place and handleError is a method that prints more detailed information on the exception:
def handleError( e )
puts( "Error of type: #{e.class}" ) puts( e )
puts( "Here is a backtrace: " ) puts( e.backtrace )
end
Notice that this uses the backtrace method which displays an array of strings showing the file names and line numbers where the error occurred and, in this case, the line which called the error-producing divbyzero method.
CHAPTER NINE
raise.rb
165

THE BOOK OF RUBY
You can also specifically raise your exceptions to force en error condition even when the program code itself has not caused an exception. Calling raise on its own raises an exception of the type RuntimeError (or whatever exception is in the global variable $!):
raise # raises RuntimeError
By default, this will have no descriptive message associated with it. You can add a message as a parameter, like this:
raise "An unknown exception just occurred!"
You may raise a specific type of error< raise ZeroDivisionError You may also create an object of a specific exception type and initialize it with a custom message< raise ZeroDivisionError.new( "I'm afraid you divided by Zero" ) If the standard exception types don’t meet your requirements, you can, of course, create new ones just by subclassing existing exceptions. Provide your classes with a to_str method in order to give them a default message. class NoNameError < Exception def to_str "No Name given!" end end 166 raise2.rb raise3.rb And this is an example of how you might raise a custom exception: def sayHello( aName ) begin if (aName == "") or (aName == nil) then raise NoNameError end rescue Exception => e
puts( e.class )
puts( "message: " + e ) puts( e.backtrace )
else
puts( "Hello #{aName}" )
end end
CHAPTER NINE
167

THE BOOK OF RUBY
Digging Deeper
OMITTING BEGIN AND END
You may optionally omit begin and end when trapping exceptions inside a method, a class or a module. For example, all the following are legal:
def calc
result = 1/0
rescue Exception => e puts( e.class )
puts( e )
result = nil
return result end
class X
@@x = 1/0
rescue Exception => e puts( e.class )
puts( e ) end
module Y
@@x = 1/0
rescue Exception => e puts( e.class )
puts( e ) end
In all the cases shown above, the exception-handling will also work if you place the begin and end keywords at the start and end of the exception-handling code in the usual way.
168
omit_begin_end.rb

CATCH...THROW
In some languages, exceptions are trapped using the keyword catch and may be raised using the keyword throw. While Ruby provides catch and throw me- thods, these are not directly related to its exception handling. Instead, catch and throw are used to break out of a defined block of code when some condition is met. You could, of course, use catch and throw to break out of a block of code when an exception occurs (though this may not be the most elegant way of handling errors). For example, this code will exit the block delimited by curly brackets if a ZeroDivisionError occurs:
catch( :finished) {
print( 'Enter a number: ' ) num = gets().chomp.to_i begin
result = 100 / num rescue Exception => e
throw :finished end
# jump to end of block
puts( "The result of that calculation is #{result}" ) # end of :finished catch block
}
See Chapter 6 for more on catch and throw.
CHAPTER NINE
catch_except.rb
169

THE BOOK OF RUBY
170

CHAPTER TEN Blocks, Procs and Lambdas
When programmers talk about ‘blocks’, they usually mean some arbitrary ‘chunks’ of code. In Ruby, however, a block is special. It is a unit of code that works somewhat like a method but, unlike a method, it has no name. In order to use blocks effectively, you need to understand how and why they are special. That is what this chapter is all about...
WHAT IS A BLOCK?
Consider this code:
3.times do |i| puts( i )
end
It’s probably pretty obvious that this code is intended to execute three times. What may less obvious is the value which i will have on each successive turn through the loop. In fact, the values of i in this case will be 0, 1, and 2. Here is an alternative form of the code above. This time the block is delimited by curly brackets rather than by do and end:
3.times { |i|
puts( i ) }
1blocks.rb
171

THE BOOK OF RUBY
According to the Ruby documentation, times is a method of Integer (let’s call the Integer int), which iterates a block ‚int times, passing in values from zero to int – 1‛. So, here, the code within the block is run 3 times; the first time it is run the variable, i, is given the value 0; each subsequent time, i is incremented by 1 until the final value, 2 (i.e. int-1) is reached.
Note that the two code examples above are functionally identical. A block may be enclosed either by curly brackets or by the do and end keywords and the programmer may user either syntax according to personal preference.
Note: Some Ruby programmers like to delimit blocks with curly brackets when the entire code of the block fits onto a single line and with do..end when the block spans multiple lines. My personal prejudice is to be consistent, irrespective of code layout, and so I gen- erally use curly braces when delimiting blocks. Usually your choice of delimiters make no difference to the behaviour of the code - but see the section later in this chapter on ‘precedence rules’.
If you are familiar with a C-like language such as C# or Java, you may, perhaps, assume that Ruby’s curly braces can be used, as in those languages, simply to group together arbitrary ‘blocks’ of code – for example, a block of code to be executed when a condition evaluates to true. This is not the case. In Ruby, a block is a special construct which can only be used in very specific circumstances.
LINE BREAKS ARE SIGNIFICANT
The opening block delimiter must be placed on the same line as the method with which it is associated.
These are ok...
3.times do |i| puts( i )
end
3.times { |i|
puts( i ) }
172

But these contain syntax errors...
3.times do |i|
puts( i ) end
3.times { |i|
puts( i ) }
NAMELESS FUNCTIONS
A Ruby block may be regarded as a sort of nameless function or method and its most frequent use is to provides a means of iterating over items from a list or range of values. If you have never come across nameless functions previously, this may sound like gobbledygook. With luck, by the end of this chapter, things will have become a little clearer. Let’s look back at the simple example given earlier. I said a block is like a nameless function. Take this block as an example:
{ |i|
puts( i ) }
If that were written as a normal Ruby method it would look something like this:
def aMethod( i ) puts( i )
end
To call that method three times and pass values from 0 to 2 we might write this:
for i in 0..2 aMethod( i )
end
CHAPTER TEN
173

THE BOOK OF RUBY
When you create a nameless method (that is, a block) variables declared between upright bars such as |i| can be treated like the arguments to a named method. We shall refer to these variables as ‘block parameters’.
Look again at my earlier example:
3.times { |i|
puts( i ) }
The times method of an integer passes values to a block from 0 to the specified integer value minus 1.
So this:
3.times{ |i| }
2}.class)
Try this with a block, however, and you will only get an error message:
puts({|i| puts(i)}.class) #<= error! 178 Block Or Hash? Ruby uses curly brackets to delimit both blocks and Hashes. So how can you (and Ruby) tell which is which? The answer, basically, is that it’s a Hash when it looks like a Hash, otherwise it’s a block. A Hash looks like a Hash when curly brackets contain key-value pairs... puts( {1=>2}.class ) #<= Hash ...or when they are empty: puts( {}.class ) #<= Hash However, once again, if you omit the brackets, there is an ambiguity. Is this an empty Hash or is it a block associated with the puts method? puts{}.class Frankly, I have to admit that I don’t know the answer to that question and I can’t get Ruby to tell me. Ruby accepts this as valid syntax but does not, in fact, display anything when the code executes. While, this... print{}.class ...prints nil (not, you will notice the actual class of nil, which is Nil- Class, but nil itself). If you find all this confusing (as I do!) just re- member that this can all be clarified by the judicious use of brackets: print( {}.class ) #<= Hash CHAPTER TEN 179 THE BOOK OF RUBY CREATING OBJECTS FROM BLOCKS While blocks may not be objects by default, they can be ‘turned into’ objects. There are three ways of creating objects from blocks and assigning them to variables – here’s how: a = Proc.new{|x| x = x*10; puts(x) } b = lambda{|x| x = x*10; puts(x) } c = proc{|x| x.capitalize! } Note that, in each of the three cases above, you will end up creating an instance of the Proc class – which is the Ruby ‘object wrapper’ for a block. Let’s take a closer look at the three ways of creating a Proc object. First, you can create an object calling Proc.new and passing to it a block as an argument: a = Proc.new{|x| x = x*10; puts(x)} You can execute the code in the block to which a refers using the Proc class’s call method with one or more arguments (matching the block parameters) to be passed into the block; in the code above, you could pass an integer such as 100 and this would be assigned to the block variable, x: a.call(100) You can also create a Proc object by calling the lambda or proc methods. These methods (supplied by the Kernel class) are identical. The name lambda is taken from the Scheme (Lisp) language and is a term used to describe an anonymous method or ‘closure’. There is one important difference between creating a Proc object using Proc.new and creating a Proc object using the proc or lambda methods – Proc.new does not check that the number or arguments passed to the block match the number of block parameters – both proc and lambda do: 180 proc_create.rb 3blocks.rb a = Proc.new{|x,y,z| x = y*z; puts(x) } a.call(2,5,10,100) # This is not an error b = lambda{|x,y,z| x = y*z; puts(x) } b.call(2,5,10,100) # This is an error puts('---Block #2---' ) c = proc{|x,y,z| x = y*z; puts(x) } c.call(2,5,10,100) # This is an error WHAT IS A CLOSURE? ‘Closure’ is the name given to a function which has the ability to store (that is, to ‘enclose’) values of local variables within the scope in which the block was created (think of this as the block’s ‘native scope’). Ruby’s blocks are closures. To understand this, look at this example: x = "hello world" ablock = Proc.new { puts( x ) } def aMethod( aBlockArg ) x = "goodbye" aBlockArg.call end puts( x ) ablock.call aMethod( ablock ) ablock.call puts( x ) Here, the value of the local variable, x is ‚hello world‛ within the scope of ablock. Inside aMethod, however, a local variable named x has the value CHAPTER TEN proc_lamba.rb block_closure.rb 181 THE BOOK OF RUBY ‚goodbye‛. In spite of that, when ablock is passed to aMethod and called within the scope of aMethod, it prints ‚hello world‛ (that is, the value of x within the block’s ‘native scope’ rather ‚goodbye‛ which is the value of x within the scope of aMethod. The above code, therefore, only ever prints ‚hello world‛. See Digging Deeper at the end of this chapter for more on closures. YIELD Let’s see a few more blocks in use. The 4blocks.rb program introduces some- thing new – namely, a way of executing a nameless block when it is passed to a method. This is done using the keyword yield. In the first example, I define this simple method: def aMethod yield end It doesn’t really have any code of its own. Instead, it expects to receive a block and the yield keyword causes the block to execute. This is how I pass a block to it: aMethod{ puts( "Good morning" ) } Notice that this time the block is not passed as a named argument. It would be an error to try to pass the block between round brackets, like this: aMethod( { puts( "Good morning" ) } ) # This won‟t work! Instead we simply put the block right next to the method to which we are pass- ing it, just as we did in the very first example in this chapter. That method receives the block without having to declared a named parameter for it and it calls the block with yield. 182 4blocks.rb Here is a slightly more useful example: def caps( anarg ) yield( anarg ) end caps( "a lowercase string" ){ |x| x.capitalize! ; puts( x ) } Here the caps method receives one argument, anarg, and passes this argument to a nameless block which is then executed by yield. When I call the caps method, I pass it a string argument ("a lowercase string") using the normal parameter- passing syntax. The nameless block is passed after the end of the parameter list. When the caps method calls yield( anarg ) the string argument, ‚a lowercase string‛ is passed into the block; it is assigned to the block variable, x, this capital- izes it and displays it with puts( s ). BLOCKS WITHIN BLOCKS We’ve already seen how to use a block to iterate over an array. In the next example, I use one block to iterate over an array of strings, assigning each string in turn to the block variable, s. A second block is then passed to the caps method in order to capitalise the string: ["hello","good day","how do you do"].each{ |s| caps( s ){ |x| x.capitalize! puts( x ) } } This results in this output: Hello Good day How do you do CHAPTER TEN 183 THE BOOK OF RUBY PASSING NAMED PROC ARGUMENTS Up to now, we have passed blocks to procedures either anonymously (in which case the block is executed with the yield keyword) or in the form of a named argument, in which case it is executed using the call method. There is another way to pass a block. When the last argument in a method’s list of parameters is preceded by an ampersand (&) it is considered to be a Proc object. This gives you the option of passing an anonymous block to a procedure using the same syntax as when passing a block to an iterator; and yet the procedure itself can receive the block as a named argument. Load 5blocks.rb to see some examples of this. First, here is a reminder of the two ways which we’ve already seen of passing blocks. This method has three parameters, a, b, c: def abc( a, b, c ) a.call b.call c.call yield end We call this method with three named arguments (which here happen to be blocks but could, in principle, be anything) plus an unnamed block: abc(a, b, c ){ puts "four" } The abc method executes the named block arguments using the call method and the unnamed block using the yield keyword: a.call #<= call block a b.call #<= call block b c.call #<= call block c yield #<= yield unnamed block: { puts "four" } The next method, abc2, takes a single argument, &d: def abc2( &d ) 184 5blocks.rb The ampersand here is significant as it indicates that the &d parameter is a block. We don’t, however, need to send this block as a named argument. Instead, we pass the unnamed block simply by appending it to the method name: abc2{ puts "four" } Instead of using the yield keyword, the abc2 method is able to execute the block using the name of the argument (without the ampersand): def abc2( &d ) d.call end You can think of ampersand-arguments as type-checked block parameters. That is, ampersand arguments are formally declared so unlike nameless blocks (those which are ‘yielded’) the block doesn’t arrive at the method ‘unannounced’. But unlike normal arguments (without an ampersand) they must match blocks. You cannot pass some other type of object to abc2: abc2( 10 ) # This won‟t work! The abc3 method is essentially the same as the abc method apart from the fact that it specifies a fourth formal argument (&d): def abc3( a, b, c, &d) The arguments, a, b and c are called, while the argument &d may be called or yielded, as you prefer: def abc3( a, b, c, &d) a.call b.call c.call d.call #<= block &d yield #<= also block &d end CHAPTER TEN 185 THE BOOK OF RUBY This means that the calling code must pass to this method three formal argu- ments plus a block, which may be nameless: abc3(a, b, c){ puts "five" } You can also use a preceding ampersand in order to pass a named block to a method, when the receiving method has no matching named argument, like this: abc3(a, b, c, &myproc ) When an ampersanded block variable is passed to a method (as in the code above) it may be yielded. This gives the choice of passing either an unnamed block or a Proc object: xyz{ |a,b,c| puts(a+b+c) } xyz( &myproc ) Be careful, however! Notice in one of the examples above, I have used block parameters ( |a,b,c| )with the same names as the three local variables to which I previously assigned Proc objects: a, b, c: a = lambda{ puts "one" } b = lambda{ puts "two" } c = proc{ puts "three" } xyz{ |a,b,c| puts(a+b+c) } Now, in principle, block parameters should be visible only within the block itself. However, it turns out that assignment to block parameters can initialize the values of any local variables with the same name within the block’s native scope (see ‘What Is A Closure?’ earlier in this chapter ). Even though the variables in the xyz method are named x, y and z, it turns out that the integer assignments in that method are actually made to the variables a, b and c when this block< { |a,b,c| puts(a+b+c) } < is passed the values of x, y and z: 186 def xyz x=1 y=2 z=3 yield( x, y, z ) end # 1,2,3 assigned to block parameters a,b,c As a consequence, the variables a, b and c within the block’s native scope (the main scope of my program) are initialized with the values of the block variables once the code in block has been run: xyz{ |a,b,c| puts(a+b+c) } puts( a, b, c ) # displays 1, 2, 3 To clarify this, try out the simple program in 6blocks.rb: a = "hello world" def foo yield 100 end puts( a ) foo{ |a| puts( a ) } puts( a ) #< a is now 100 This is an example of one of the pitfalls into which it is all to easy to fall in Ruby. As a general rule, when variables share the same scope (e.g. a block declared within the scope of the main program here), it is best to make their names unique in order to avoid any unforeseen side effects. Note that the block scoping described here applies to versions of Ruby up to and including Ruby 1.8.x which, at the time of writing, may be considered to be the ‘standard’ version of Ruby. Changes to scoping are being made in the Ruby 1.9 and will be incorporated in Ruby 2.0. For more on scoping see ‘Blocks and Local Variables’ in the Digging Deeper section at the end of this chapter. CHAPTER TEN 6blocks.rb 187 THE BOOK OF RUBY PRECEDENCE RULES Blocks within curly braces have stronger precedence than blocks within do and end. Let’s see what that means in practice. Consider these two examples: foo bar do |s| puts( s ) end foo bar{ |s| puts(s) } Here, foo and bar are methods. So to which method is the block passed? It turns out that the do..end block would be passed to the leftmost method, foo, whereas the block in curly braces would be sent to the rightmost method, bar. This is because curly braces are said to have higher precedence. Consider this program... def foo( b ) puts("---in foo---") a = 'foo' if block_given? puts( "(Block passed to foo)" ) yield( a ) else puts( "(no block passed to foo)" ) end puts( "in foo, arg b = #{b}" ) return "returned by " << a end def bar puts("---in bar---") a = 'bar' if block_given? puts( "(Block passed to bar)" ) yield( a ) else puts( "(no block passed to bar)" ) end return "returned by " << a end 188 precedence.rb foo bar do |s| puts( s ) end # 1) do..end block foo bar{ |s| puts(s) } # 2) {..} block Here the do..end block has lower precedence and the method, foo, is given priority. This means that both bar and the do..end block are passed to foo. Thus, these two expressions are equivalent: foo bar do |s| puts( s ) end foo( bar ) do |s| puts( s ) end A curly brace block, on the other hand, has stronger precedence so it tries to execute immediately and is passed to the first possible receiver method (bar). The result (that is, the value returned by bar) is then passed as an argument to foo; but this time, foo does not receive the block itself. Thus, the two following expressions are equivalent: foo bar{ |s| puts(s) } foo( bar{ |s| puts(s) } ) If you are confused by all this, take comfort in the fact that you are not alone! The behaviour of Ruby blocks is far from transparent. The potential ambiguities result from the fact that, in Ruby, the parentheses around argument lists are optional. As you can see from the alternative versions I give above, the ambigui- ties disappear when you use parentheses. Hint... A method can test if it has received a block using the block_given? method. You can find examples of this in the precedence.rb program. CHAPTER TEN 189 THE BOOK OF RUBY BLOCKS AS ITERATORS As mentioned earlier, one of the primary uses of blocks in Ruby is to provide iterators to which a range or list of items can be passed. Many standard classes such as Integer and Array have methods which can supply items over which a block can iterate. For example: 3.times{ |i| puts( i ) } [1,2,3].each{|i| puts(i) } You can, of course, create your own iterator methods to provide a series of values to a block. In the iterate1.rb program, I have defined a simple timesRepeat method which executes a block a specified number of times. This is similar to the times method of the Integer class apart from the fact that it begins at index 1 rather than at index 0 (here the variable i is displayed in order to demonstrate this fact): def timesRepeat( aNum ) for i in 1..aNum do yield i end end Here is an example of how this method might be called: timesRepeat( 3 ){ |i| puts("[#{i}] hello world") } I’ve also created a timesRepeat2 method to iterate over an array: def timesRepeat2( aNum, anArray ) anArray.each{ |anitem| yield( anitem ) } end 190 iterate1.rb This could be called in this manner: timesRepeat2( 3, ["hello","good day","how do you do"] ){ |x| puts(x) } In fact, of course, it would be better (truer to the spirit of object orientation) if an object itself contained its own iterator method. I’ve implemented this in the next example. here I have created MyArray, a subclass of Array: class MyArray < Array It is initialized with an array when a new MyArray object is created: def initialize( anArray ) super( anArray ) end It relies upon its own (self) each method, which is provided by its ancestor, Array, to iterate over the items in the array and it uses the times method of Integer to do this a certain number of times. This is the complete class definition: class MyArray < Array def initialize( anArray ) super( anArray ) end def timesRepeat( aNum ) aNum.times{ # start block 1... } end end # ...end block 2 # ...end block 1 | num | self.each{ # start block 2... } | anitem | yield( "[#{num}] :: '#{anitem}'" ) CHAPTER TEN iterate2.rb 191 THE BOOK OF RUBY Notice that, as I have used two iterators (aNum.times and self.each), the times- Repeat method comprises two nested blocks. This is an example of how you might use this... numarr = MyArray.new( [1,2,3] ) numarr.timesRepeat( 2 ){ |x| puts(x) } This would output the following: [0] :: '1' [0] :: '2' [0] :: '3' [1] :: '1' [1] :: '2' [1] :: '3' In iterate3.rb I have set myself the problem of defining an iterator for an array containing an arbitrary number of sub-arrays, in which each sub-array has the same number of items. In other words it will be like a table or matrix with a fixed number of rows and a fixed number of columns. Here, for example, is a multi- dimensional array with three ‘rows’ (sub-arrays) and four ‘columns’ (items): multiarr = [ ['one','two','three','four'], [1, 2, 3, 4 ], [:a, :b, :c, :d ] ] I’ve tried out three alternative versions of this. The first version suffers from the limitation of only working with a pre-defined number (here 2 at indexes [0] and *1+) of ‘rows’: multiarr[0].length.times{|i| puts(multiarr[0][i], multiarr[1][i]) } 192 iterate3.rb The second version gets around this limitation by iterating over each element (or ‘row’) of multiarr and then iteration along each item in that row by obtaining the row length and using the Integer’s times method with that value: multiarr.each{ |arr| multiarr[0].length.times{|i| puts(arr[i]) } } The third version reverses these operations: the outer block iterates along the length of row 0 and the inner block obtains the item at index i in each row: multiarr[0].length.times{|i| multiarr.each{ |arr| puts(arr[i]) } } While versions 2 and 3 work in a similar way, you will find that they iterate through the items in a different order. Run the program to verify that. You could try creating your own subclass of Array and adding iterator methods like this – one method to iterate through the rows in sequence (like Version 2, above) and one to iterate through the columns in sequence (like Version 3). CHAPTER TEN 193 THE BOOK OF RUBY Digging Deeper RETURNING BLOCKS FROM METHODS Earlier, I explained that blocks in Ruby may act as ‘closures’. A closure may be said to enclose the ‘environment’ in which it is declared. Or, to put it another way, it carries the values of local variables from its original scope into a different scope. The example I gave previously showed how the block named ablock captures the value of the local variable x... x = "hello world" ablock = Proc.new { puts( x ) } ...and it is then able to ‘carry’ that variable into a different scope. Here, for example, ablock is passed to aMethod. When ablock is called inside that method it runs the code puts( x ). This displays ‚hello world‛ and not ‚goodbye‛... def aMethod( aBlockArg ) x = "goodbye" aBlockArg.call #<= displays “hello world” end In this particular example, this behaviour may seem like a curiosity of no great interest. In fact, block/closures can be used more creatively. For example, instead of creating a block and sending it to a method, you could create a block inside a method and return that block to the calling code. If the method in which the block is created happens to take an argument, the block could be initialized with that argument. This gives us a simple way of creating multiple blocks from the same ‘block template’, each instance of which is initialized with different data. Here, for example, I have created two blocks, assigned to the variables salesTax and vat, each of which calculates results based on different values (0.10) and (0.175): 194 block_closure.rb def calcTax( taxRate ) return lambda{ |subtotal| subtotal * taxRate } end salesTax = calcTax( 0.10 ) vat = calcTax( 0.175 ) print( "Tax due on book = ") print( salesTax.call( 10 ) ) print( "\nVat due on DVD = ") print( vat.call( 10 ) ) #<= prints: 1.0 #<= prints: 1.75 BLOCKS AND INSTANCE VARIABLES One of the less obvious features of blocks is the way in which they use variables. If a block may truly be regarded as a nameless function or method then, logi- cally, it should be able 1) to contain its own local variables and 2) to have access to the instance variables of the object to which the block belongs. Let’s look first at instance variables. Load up the closures1.rb program. This providers another illustration of a block acting as a closure – by capturing the values of the local variables in the scope in which it was created. Here I have created block using the lambda method: aClos = lambda{ @hello << " yikes!" } This block appends a string, ‚ yikes!‛ to an instance variable, @hello. Notice that at this stage in the proceedings, no value has previously been assigned to @hello. 195 CHAPTER TEN block_closure2.rb closures1.rb THE BOOK OF RUBY I have, however, created a separate method, aFunc, which does assign a value to a variable called @hello: def aFunc( aClosure ) @hello = "hello world" aClosure.call end When I pass my block to this method (the aClosure argument), the aFunc method brings @hello into being. I can now execute the code inside the block using the call method. And sure enough @hello variable contains the string ‚hello world‛. The same variable can also be used by calling the block outside of the method. Indeed, now, by repeatedly calling the block, I will end up repeatedly appending the string, ‚ yikes!‛ to @hello: aFunc(aClos) aClos.call aClos.call aClos.call aClos.call #<= @hello = “hello world yikes!” #<= @hello = “hello world yikes! yikes!” #<= @hello = “hello world yikes! yikes! yikes!” # ...and so on If you think about it, this is not really too surprising. After all, @hello is an instance variable so it exists within the scope of an object. When we run a Ruby program, an object called main is automatically created. So we should expect any instance variable created within that object (our program) to be available to everything inside it. The question, now arises: what would happen if you were to send the block to a method of some other object? If that object has its own instance variable, @hello, which variable will the block use – the @hello from the scope in which the block was created or the @hello from the scope of the object in which the block is called? Let’s try that out. We’ll use the same block as before, except this time it will display a bit of information about the object to which the block belongs and the value of @hello: aClos = lambda{ @hello << " yikes!" puts("in #{self} object of class #{self.class}, @hello = #{@hello}") } 196 Now to create a new object from a new class (X) and give it a method which will receive our block, b, and call the block: class X def y( b ) @hello = "I say, I say, I say!!!" puts( " [In X.y]" ) puts("in #{self} object of class #{self.class}, @hello = #{@hello}") puts( " [In X.y] when block is called..." ) b.call end end x = X.new To test it out, just pass the block, aClos, to the y method of x: x.y( aClos ) And this is what is displayed: [In X.y] in # object of class X, @hello = I say, I say, I say!!!
[In X.y] when block is called...
in main object of class Object, @hello = hello world yikes! yikes! yikes! yikes! yikes! yikes!
So, it is clear that the block executes in the scope of the object in which it was created (main) and retains the instance variable from that object even though the object in whose scope the block is called has an instance variable with the same name and a different value.
BLOCKS AND LOCAL VARIABLES
Now let’s see how a block/closure deals with local variables. Load up the clo- sures2.rb program. First I declare a variable, x, which is local to the context of the program itself:
CHAPTER TEN
197

THE BOOK OF RUBY
x = 3000
The first block/closure is called c1. Each time I call this block, it picks up the
value of x defined outside the block itself (3000) and returns x + 100:
c1 = lambda{
return x + 100 }
This block has no block parameters (that is, there are no ‘block local’ variables between upright bars) so when it is called with a variable, someval, that variable is discarded, unused. In other words, c1.call(someval) has the same effect as c1.call().
So when you call the block c1, it returns x+100 (i.e. 3100), this value is then assigned to someval. When you call c1 a second time, exactly the same thing happens all over again, so once again someval is assigned 3100:
someval=1000
someval=c1.call(someval); puts(someval) #<= someval is now 3100 someval=c1.call(someval); puts(someval) #<= someval is now 3100 Note: Instead of repeating the call to c1, as show above, you could place the call inside a block and pass this to the times method of In- teger like this: 2.times{ someval=c1.call(someval); puts(someval) } However, as it can be hard enough to work what just one block is up to (such as the c1 block here) I’ve deliberately avoided using any more blocks than are absolutely necessary in this program! closures2.rb 198 The second block is named c2. This declares a ‘block parameter’, z. This too returns a value: c2 = lambda{ |z| return z + 100 } However, this time the returned value can be reused since the block parameter acts like an incoming argument to a method – so when the value of someval is changed after it is assigned the return value of c2 this changed value is subse- quently passed as an argument: someval=1000 someval=c2.call(someval); puts(someval) #<= someval is now 1100 someval=c2.call(someval); puts(someval) #<= someval is now 1200 The third block, c3, looks, at first sight, pretty much the same as the second block, c2. In fact, the only difference is that its block parameter is called x instead of z: c3 = lambda{ |x| return x + 100 } The name of the block parameter has no effect on the return value. As before, someval is first assigned the value 1100 (that is, its original value, 1000, plus the 100 added inside the block) then, when the block is called a second time, someval is assigned the value 1200 (its previous value, 1100, plus 100 assigned inside the block). But now look at what happens to the value of the local variable x. This was assigned 3000 at the top of the unit. Simply by giving the block parameter the same name, x, we have altered the value of the local variable, x. It now has the value, 1100 – that is, the value that the block parameter, x, last had when the c3 block was called: CHAPTER TEN 199 THE BOOK OF RUBY x = 3000 c3 = lambda{ |x| return x + 100 } someval=1000 someval=c3.call(someval); puts(someval) someval=c3.call(someval); puts(someval) puts( x ) #<= x is now 1100 Incidentally, even though block-local variables and block parameters can affect similarly named local variables outside the block, the block variables themselves have no ‘existence’ outside the block. You can verify this using the defined? keyword to attempt to display the type of variable if it is, indeed, defined: print("x=[#{defined?(x)}],z=[#{defined?(z)}]") Matz, the creator of Ruby, has described the scoping of local variables within a block as ‘regrettable’. In particular, he feels that it was mistake to make local variables within a block invisible to the method containing that block. For an example of this, see local_var_scope.rb: def foo a = 100 [1,2,3].each do |b| c=b a=b print("a=#{a}, b=#{b}, c=#{c}\n") end when inside the block itself. The block has access to both these variables and to 200 # Can't print #{b} and #{c} here!!! Here, the block parameter, b, and the block-local variable, c, are both visible only print("Outside block: a=#{a}\n") end local_var_scope.rb the variable a (local to the foo method). However, outside of the block, b and c are inaccessible and only a is visible. Just to add to the confusion, whereas the block-local variable, c and the block parameter, b, are both inaccessible outside the block in the example above, they are accessible when you iterate a block with for as in the example below: def foo2 a = 100 for b in [1,2,3] do c=b a=b print("a=#{a}, b=#{b}, c=#{c}\n") end print("Outside block: a=#{a}, b=#{b}, c=#{b}\n") end In future versions of Ruby, local variables to which values are assigned inside a block (as with c) will also be local to the method (such as foo) outside the block. Formal block parameters, like b, will be local to the block. CHAPTER TEN 201 THE BOOK OF RUBY 202 CHAPTER ELEVEN Symbols Many newcomers to Ruby are confused by symbols. A symbol is an identifier whose first character is a colon ( : ), so :this is a symbol and so is :that. Symbols are, in fact, not at all complicated – and, in certain circumstances, they may be extremely useful, as we shall see shortly. Let’s first be clear about what a symbol is not: it is not a string, it is not a constant and it is not a variable. A symbol is, quite simply, an identifier with no intrinsic meaning other than its own name. Whereas you might assign a value to a varia- ble like this... name = “Fred” ...you would not assign a value to a symbol. The value of a symbol called :name is :name. For a more technical account of what a symbol is, refer to the Digging Deeper section at the end of the chapter. We have, of course, used symbols before. In Chapter 2, for instance, we created attribute readers and writers by passing symbols to the attr_reader and attr_writer methods, like this: attr_reader( :description ) attr_writer( :description ) 203 THE BOOK OF RUBY You may recall that the above code causes Ruby to create a @description in- stance variable plus a pair of getter (reader) and setter (writer) methods called description. Ruby takes the value of a symbol literally. Its value is its name (:description). The attr_reader and attr_writer methods create, from that name, variables and methods with matching names. SYMBOLS AND STRINGS It is a common misconception that a symbol is a type of string. After all, isn’t the symbol, :hello pretty similar to the string, ‚hello‛? In fact, symbols are quite unlike strings. For one thing, each string is different – so, ‚hello‛, ‚hello‛ and ‚hello‛ are three separate objects with three separate object_ids. puts( "hello".object_id ) # These 3 strings have 3 different object_ids puts( "hello".object_id ) puts( "hello".object_id ) But a symbol is unique, so :hello, :hello and :hello all refer to the same object with the same object_id. In this respect, a symbol has more in common with an integer than with a string. Each occurrence of a given integer value, you may recall, refers to the same object so 10, 10 and 10 may be considered to be the same object and they have the same object_id: # These three symbols have the same object_id puts( :ten.object_id ) puts( :ten.object_id ) puts( :ten.object_id ) # These three integers have the same object_id puts( 10.object_id ) puts( 10.object_id ) puts( 10.object_id ) 204 symbol_ids.rb ints_and_symbols.rb Or you could test for equality using the equal? method: puts( :helloworld.equal?( :helloworld ) ) puts( "helloworld".equal?( "helloworld" ) ) puts( 1.equal?( 1 ) ) #=> true #=> false #=> true
Being unique, a symbol provides an unambiguous identifier. You can pass symbols as arguments to methods, like this:
amethod( :deletefiles )
A method might contain code to test the value of the incoming argument:
def amethod( doThis )
if (doThis == :deletefiles) then
puts( 'Now deleting files...') elsif (doThis == :formatdisk) then
puts( 'Now formatting disk...') else
puts( "Sorry, command not understood." ) end
end
Symbols could also be used in case statements where they would provide both
the readability of strings and the uniqueness of integers:
case doThis
when :deletefiles : puts( 'Now deleting files...') when :formatdisk : puts( 'Now formatting disk...') else puts( "Sorry, command not understood." )
end
The scope in which a symbol is declared does not affect its uniqueness.
CHAPTER ELEVEN
symbols_strings.rb
symbols_1.rb
205

THE BOOK OF RUBY
Consider the following...
module One class Fred
end
$f1 = :Fred end
module Two Fred = 1
$f2 = :Fred end
def Fred() end
$f3 = :Fred
Here, the variables $f1, $f2 and $f3 are assigned the symbol :Fred in three different scopes: module One, module Two and the ‘main’ scope. I’ll have more to say on modules in Chapter 12. For now, just think of them as ‘namespaces’ which define different scopes. And yet each variable refers to the same symbol, :Fred, and has the same object_id:
# All three display the same id! puts( $f1.object_id )
puts( $f2.object_id )
puts( $f3.object_id )
Even so, the ‘meaning’ of the symbol changes according to its scope.
In other words, in module One, :Fred refers to the class Fred, in module Two, it refers to the constant, Fred = 1, and in the main scope it refers to the method Fred.
A rewritten version of the previous program demonstrates this:
206
symbol_ref.rb

module One
class Fred
end
$f1 = :Fred
def self.evalFred( aSymbol )
puts( eval( aSymbol.id2name ) ) end
end
module Two
Fred = 1
$f2 = :Fred
def self.evalFred( aSymbol )
puts( eval( aSymbol.id2name ) ) end
end
def Fred()
puts( "hello from the Fred method" )
end
$f3 = :Fred
One::evalFred( $f1 ) Two::evalFred( $f2 ) method($f3).call
#=> displays the module::class name: One::Fred #=> displays the Fred constant value: 1
#=> calls Fred method: displays:
# “hello from the Fred method”
Naturally, since the variables $f1, $f2 and $f3 reference the same symbol, it doesn’t matter which variable you use at any given point. The following produc- es exactly the same results:
One::evalFred( $f3 ) Two::evalFred( $f1 ) method($f2).call
CHAPTER ELEVEN
symbol_ref2.rb
207

THE BOOK OF RUBY
SYMBOLS AND VARIABLES
To understand the relationship between a symbol and an identifier such as a variable name, take a look at our symbols_2.rb program. This begins by assign- ing the value 1 to a local variable, x. It then assigns the symbol :x to a local variable, xsymbol...
x=1 xsymbol = :x
At this point there is no obvious connection between the variable, x, and the symbol :x. I have declared a method which simply takes some incoming argu- ment and inspects and displays it using the p method. I can call this method with the variable and the symbol:
# Test 1 amethod( x ) amethod( :x )
This is the data which the method prints as a result:
1 :x
In other words, the value of the x variable is 1, since that’s the value assigned to it and the value of :x is :x. But the interesting question that arises is: if the value of :x is :x and this is also the symbolic name of the variable x, would it be possi- ble to use the symbol :x to find the value of the variable x? Confused? Hopefully the next line of code will make this clearer:
# Test 2
amethod( eval(:x.id2name))
Here, id2name is a method of the Symbol class. It returns the name or string corresponding to the symbol (the to_s method would perform the same func- tion); the end result is that, when given the symbol :x as an argument, id2name returns the string ‚x‛. Ruby’s eval method (which is defined in the Kernel class)
208
symbols_2.rb

is able to evaluate expressions within strings. In the present case, that means it finds the string ‚x‛ and tries to evaluate it as though it were executable code. It finds that x is the name of a variable and that the value of x is 1. So the value 1 is passed to amethod. You can verify this by running symbols2.rb and comparing the code with the output.
Evaluating data as code is explained in more detail in Chapter 20.
Things can get even trickier. Remember that the variable, xsymbol has been assigned the symbol :x...
x=1 xsymbol = :x
That means that if we eval :xsymbol, we can obtain the name assigned to it – that is, the symbol :x. Having obtained :x we can go on to evaluate this also, giving the value of x – namely, 1:
CHAPTER ELEVEN
# Test 3
amethod( xsymbol )
amethod( :xsymbol )
amethod( eval(:xsymbol.id2name))
amethod( eval( ( eval(:xsymbol.id2name)).id2name ) )
#=> :x
#=> :xsymbol #=> :x
#=> 1
As we’ve seen, when used to create attribute accessors symbols can refer to method names. We can make use of this by passing a method name as a symbol to the method method (yes, there really is a method called ‘method’) and then calling the specified method using the call method:
#Test 4 method(:amethod).call("")
The call method lets us pass arguments and, just for the heck of it, we could pass an argument by evaluating a symbol:
method(:amethod).call(eval(:x.id2name))
209

THE BOOK OF RUBY
If this seems complicated, take a look at a simpler example in symbols_3.rb. This
begins with this assignment:
def mymethod( somearg ) print( "I say: " << somearg ) end this_is_a_method_name = method(:mymethod) Here method(:mymethod) looks for a method with the name specified by the symbol passed as an argument (:mymethod) and, if one is found, it returns the Method object with the corresponding name. In my code I have a method called mymethod and this is now assigned to the variable this_is_a_method_name. When you run this program, you will see that the first line of output prints the value of the variable: puts( this_is_a_method_name ) #=> This displays: #
This shows that the variable, this_is_a_method_name, has been assigned the method, mymethod, which is bound to the Object class (as are all methods which are entered as ‘freestanding’ functions). To double-check that the variable really is an instance of the Method class the next line of code prints out its class:
puts( "#{this_is_a_method_name.class}" ) #=> This displays: Method
OK, so if it’s really and truly a method, then we should be able to call it, shouldn’t we? In order to do that we need to use the call method. That is what the last line of code does:
this_is_a_method_name.call( "hello world" ) #=> This displays: I say: hello world
210
symbols_3.rb

WHY USE SYMBOLS?
Some methods in the Ruby class library specify symbols as arguments. Naturally, if you need to call those methods, you are obliged to pass symbols to them. Other than in those cases, however, there is no absolute requirement to use symbols in your own programming. For many Ruby programmers, the ‘conventional’ data types such as strings and integers are perfectly sufficient.
Symbols do have a special place in ’dynamic’ programming, however. For example, a Ruby program is able to create a new method at runtime by calling, within the scope of a certain class, define_method with a symbol representing the method to be defined and a block representing the code of the method:
class Array
define_method( :aNewMethod, lambda{ |*args| puts( args.inspect) } )
end
After the above code executes, the Array class will have gained a method named aNewMethod. You can verify this by calling method_defined? with a symbol representing the method name:
Array.method_defined?( :aNewMethod ) #=> returns: true
And, of course, you can call the method itself:
[].aNewMethod( 1,2,3 ) #=> returns: [1,2,3]
You can remove an existing method at runtime in a similar way by calling remove_method inside a class with a symbol providing the name of the method to be removed:
class Array
remove_method( :aNewMethod )
end
Dynamic programming is invaluable in applications which need to modify the behaviour of the Ruby program itself while that program is still executing. Dynamic programming is widely used in the Rails framework, for example.
CHAPTER ELEVEN
add_method.rb
211

THE BOOK OF RUBY
Digging Deeper
WHAT IS A SYMBOL?
Previously, I said that a symbol is an identifier whose value is itself. That de- scribes, in a broad sense, the way that symbols behave from the point of view of the Ruby programmer. But it doesn’t tell us what symbols are literally from the point of view of the Ruby interpreter. A symbol is, in fact, a pointer into the symbol table. The symbol table is Ruby’s internal list of known identifiers – such as variable and method names.
If you want to take a peek deep inside Ruby, you can display all the symbols which Ruby knows about like this:
p( Symbol.all_symbols )
This will shows thousands of symbols including method names such as :to_s and :reverse, global variables such as :$/ and :$DEBUG and class names such as :Array and :Symbol. You may restrict the number of symbols displayed using array indexes like this:
p( Symbol.all_symbols[0,10] )
But you can’t sort symbols since symbols are not inherently sequential. The easiest way to display a sorted list of symbols would be to convert them to strings and sort those. In the code below, I pass all the symbols known to Ruby into a block, convert each symbol to a string and collect the strings into a new array which is assigned to the str_array variable. Now I can sort this array and display the results:
str_arr = Symbol.all_symbols.collect{ |s| s.to_s } puts( str_arr.sort )
212
allsymbols.rb

CHAPTER TWELVE Modules and Mixins
In Ruby, each class has only one immediate ‘parent’, though each parent class may have many ‘children’. By restricting class hierarchies to single line of descent, Ruby avoids some of the problems that may occur in those program- ming languages (such as C++) which permit multiple-lines of descent. When classes have many parents as well as many children; and their parents, and children have yet other parents and children, you risk ending up with an im- penetrable network (or ‘knotwork’?) rather than the neat, well-ordered hierarchy which you may have intended.
Nevertheless, there are occasions when it is useful for classes which are not closely related to implement some shared features. For example, a Sword might be a type of Weapon but also a type of Treasure; a PC might be a type of Com- puter but also a type of Investment and so on.
But, since the classes defining Weapons and Treasures or Computers and In- vestments descend from different ancestor classes, their class hierarchy gives them no obvious way of sharing data and methods. Ruby’s solution to this problem is provided by Modules.
A MODULE IS LIKE A CLASS...
The definition of a module looks very similar to a class. In fact, Modules and classes are closely related – the Module class is the immediate ancestor of the Class class. Just like a class, a module can contain constants, methods and classes. Here’s a simple module:
213

THE BOOK OF RUBY
module MyModule GOODMOOD = "happy" BADMOOD = "grumpy"
def greet
return "I'm #{GOODMOOD}. How are you?"
end end
As you can see, this contains a constant, GOODMOOD and an ‘instance method’, greet.
MODULE METHODS
In addition to instance methods a module may also have module methods. Just as class methods are prefixed with the name of the class, so module methods are prefixed with the name of the module:
def MyModule.greet
return "I'm #{BADMOOD}. How are you?"
end
In spite of their similarities, there are two major features which classes possess but which modules do not: instances and inheritance. Classes can have instances (objects), superclasses (parents) and subclasses (children); modules can have none of these.
The Module class does have a superclass – namely, Object. However, any named modules which you create do not have superclasses. For a more detailed account of the relationship between Modules and Classes, see the Digging Deeper section at the end of this chapter.
Which leads us to the next question: if you can’t create an object from a module, what are modules for? This can be answered in two words: namespaces and mixins. Ruby’s ‘mixins’ provide a way of dealing with the problem of multiple inheritance. We’ll come to mixins shortly. First though, let’s look at namespaces.
214

MODULES AS NAMESPACES
You can think of a module as a sort of named ‘wrapper’ around a set of methods, constants and classes. The various bits of code inside the module share the same ‘namespace’ so they are all visible to each other but are not visible to code outside the module.
The Ruby class library defines a number of modules such as Math and Kernel. The Math module contains mathematical methods such as sqrt to return a square route and constants such as PI. The Kernel module contains many of the methods we’ve been using from the outset such as print, puts and gets.
Let’s assume we have the module which we looked at earlier:
module MyModule GOODMOOD = "happy" BADMOOD = "grumpy"
def greet
return "I'm #{GOODMOOD}. How are you?"
end
def MyModule.greet
return "I'm #{BADMOOD}. How are you?"
end end
We can access the module constants just as we would access class constants using the :: scope resolution operator like this:
puts(MyModule::GOODMOOD)
We can access module methods using dot notation – that is, specifying the module name followed by a period and the method name. The following would print out ‚I'm grumpy. How are you?‛:
puts( MyModule.greet )
CHAPTER TWELVE
modules1.rb
215

THE BOOK OF RUBY
MODULE ‘INSTANCE METHODS’
But how to access the instance method, greet? As the module defines a closed namespace, any code outside the module won’t be able to ‘see’ the greet method so this won’t work:
puts( greet )
If this were a class rather than a module we could, of course, create objects from the class using the new method – and each separate object, each ‘instance’ of the class - would have access to the instance methods. But you cannot create in- stances of modules. So how can we use their instance methods? This is where mixins enter the picture< INCLUDED MODULES OR ‘MIXINS’ An object can access the instance methods of a module by including that module using the include method. If you were to include MyModule into your program, everything inside that module would suddenly pop into existence within the current scope. So the greet method of MyModule will now be accessible: include MyModule puts( greet ) Note that only instance methods are included. In the above example, the greet (instance) method has been included but the MyModule.greet (module) method has not... module MyModule GOODMOOD = "happy" BADMOOD = "grumpy" def greet return "I'm #{GOODMOOD}. How are you?" end 216 modules2.rb def MyModule.greet return "I'm #{BADMOOD}. How are you?" end end As it’s included, the greet method can be used just as though it were a normal instance method within the current scope... puts( greet ) The process of including a module is also called ‘mixing in’ – which explains why included modules are often called ‘mixins’. When you mix modules into a class definition, any objects created from that class will be able to use the instance methods of the mixed-in module just as though they were defined in the class itself. class MyClass include MyModule def sayHi puts( greet ) end end Not only can the methods of this class access the greet method from MyModule, but so too can any objects created from the class: ob = MyClass.new ob.sayHi puts(ob.greet) Modules can be thought of as discrete code units which can simplify the creation of reusable code libraries. On the other hand, you might be more interested in using modules as an alternative to multiple inheritance. CHAPTER TWELVE modules3.rb 217 THE BOOK OF RUBY Returning to an example which I mentioned right at the start of this chapter, let’s assume that you have a Sword class which is not only a type of Weapon but also of Treasure. Maybe Sword is a descendant of the Weapon class (so inherits the Weapon’s deadliness attribute), but it also needs to have the attributes of a Treasure (such as value and owner) and, this being an Elvish Sword, of Magic- Thing. If you define these attributes inside Treasure and MagicThing modules rather than a Treasure and MagicThing classes, the Sword class would be able to include those modules in order to ‘mix in’ their methods or attributes: module MagicThing attr_accessor :power end module Treasure attr_accessor :value attr_accessor :owner end class Weapon attr_accessor :deadliness end class Sword < Weapon include Treasure include MagicThing attr_accessor :name end The Sword object now has access to the methods and attributes of the Sword class itself, of its ancestor class, Weapon, and also of its mixed-in modules, Treasure and MagicThing: s = Sword.new s.name = "Excalibur" s.deadliness = "fatal" s.value = 1000 s.owner = "Gribbit The Dragon" s.power = "Glows when Orcs Appear" 218 modules4.rb puts(s.name) puts(s.deadliness) puts(s.value) puts(s.owner) puts(s.power) Note, incidentally, that any variables which are local variables in the module cannot be accessed from outside the module. This is the case even if a method inside the module tries to access a local variable and that method is invoked by code from outside the module – for example, when the module is mixed in through inclusion: x = 1 # local to this program module Foo x = 50 # local to module Foo # This can be mixed in but the variable x won't then be visible def no_bar return x end def bar @x = 1000 return @x end puts( "In Foo: x = #{x}" ) end # this can access the „module local‟ x include Foo puts(x) puts( no_bar ) puts(bar) # Error! This can't access the module-local variable # needed by the no_bar method CHAPTER TWELVE mod_vars.rb 219 THE BOOK OF RUBY Note that instance variables are available to mixed in methods (such as bar). But local variables are not available even when a local variable with the same name exists within the current scope of the mixed in method (so, no_bar is unable to access a variable named x even though x is declared in the current scope). A module may have its own instance variables which belong exclusively to the module ‘object’. These instance variables will be in scope to a module method: module X @instvar = "X's @instvar" def self.aaa puts(@instvar) end end X.aaa #=> “X‟s @instvar”
But instance variables that are referenced in instance objects ‘belong’ to the scope into which that module is included:
220
module X
@instvar = "X's @instvar"
def amethod @instvar = 10 puts(@instvar)
end end
include X
X.aaa
puts( @instvar ) amethod
puts( @instvar ) @instvar = "hello world" puts( @instvar )
# creates @instvar in current scope
#=> X's @instvar #=> nil
#=> 10
#=> 10
#=> "hello world"
inst_class_vars.rb

Class variables are also mixed in and, like instance variables, their values may be reassigned within the current scope:
module X
@@classvar = "X's @@classvar"
end include X
puts( @@classvar ) #=> X's @classvar @@classvar = "bye bye"
puts( @@classvar ) #=> "bye bye"
You may obtain an array of instance variable names using the in- stance_variables method:
p( X.instance_variables ) p( self.instance_variables )
NAME CONFLICTS
Module methods (those methods specifically preceded by the module name) can help to protect your code from accidental name conflicts. However, no such protection is given by instance methods within modules. Let’s suppose you have two modules – one called Happy and the other called Sad. They each contain a module method called mood and an instance method called expression.
module Happy def Happy.mood return "happy"
end
def expression return "smiling"
end end
# module method # instance method
CHAPTER TWELVE
happy_sad.rb
221

THE BOOK OF RUBY
module Sad def Sad.mood
return "sad" end
def expression return "frowning"
end end
# module method # instance method
Now, a class, Person, includes both these modules:
class Person
include Happy include Sad attr_accessor :mood
def initialize
@mood = Happy.mood
end end
The initialize method of the Person class needs to set the value of its @mood variable using the mood method from one if the included modules. The fact that they both have a mood method is no problem; being a module method, mood must be preceded by the module name so Happy.mood won’t be confused with Sad.mood.
But both the Happy and Sad modules also contain a method called expression. This is an instance method and, when both the modules are included in the Person class, the expression method can be called without any qualification:
p1 = Person.new puts(p1.expression)
Which expression method is object p1 using here? It turns out that it uses the method last defined. In the present case, that happens to be the method defined in the Sad module for the simple reason that Sad is included after Happy. If you
222

change the order of inclusion so that Happy is included after Sad, the p1 object will use the version of the expression method defined in the Happy module.
Before getting carried away with the possibilities of creating big, complex mod- ules and mixing then into your classes on a regular basis, bear this potential problem in mind – i.e. included instance methods with the same name will ‘overwrite’ one another. The problem may be obvious to spot in my little pro- gram. It may not be so obvious in a huge application!
ALIAS METHODS
One way of avoiding ambiguity when you use similarly named methods from multiple modules is to ‘alias’ those methods. An alias is a copy of an existing method with a new name. You use the alias keyword followed by the new name, then the old name:
alias happyexpression expression
You can also use alias to make copies of methods which have been overridden so
that you can specifically refer to a version prior to its overridden definition:
module Happy
def Happy.mood
return "happy" end
def expression return "smiling"
end
alias happyexpression expression end
module Sad
def Sad.mood
return "sad" end
CHAPTER TWELVE
alias_methods.rb
223

THE BOOK OF RUBY
def expression return "frowning"
end
alias sadexpression expression end
class Person
include Happy include Sad attr_accessor :mood def initialize
@mood = Happy.mood end
end
p2 = Person.new puts(p2.mood) puts(p2.expression) puts(p2.happyexpression) puts(p2.sadexpression)
MIX-IN WITH CARE!
#=> happy #=> frowning #=> smiling #=> frowning
While each class can only descend from one superclass, it can mix in numerous modules. In fact, it is perfectly permissible to mix one lot of modules into another lot of modules and mix these other modules into classes and those classes into yet more modules. Below, is an example of some code that subclasses classes, mixes in modules and even subclasses classes from within mixed-in modules. This code has been deliberately simplified. For the full horror of a working example, see the sample program, multimods.rb:
module MagicThing # module
class MagicClass # class inside module end
end
224
multimods.rb

module Treasure end
module MetalThing
include MagicThing
class Attributes < MagicClass end end include MetalThing class Weapon < MagicClass # module # mixin # subclasses class from mixin # mixin # subclass class from mixin class WeaponAttributes < Attributes # subclass end end class Sword < Weapon include Treasure include MagicThing end # subclass # mixin # mixin In brief, while modules may, when used with care, help to avoid some of the complexities associated the C++ type of multiple inheritance, they are nonethe- less open to misuse. If a programmer really wants to create convoluted hierar- chies of classes with inscrutable dependencies on multiple levels of mixed in modules, then he or she can certainly do so. In multimods.rb I’ve shown how easy it is to write a an impenetrable program in just a few lines of code. Imagine what you could do over many thousands of lines of code spread over dozens of code files! Suffice to say, this is not a style of programming which I recommend, so you may want to think carefully before mixing in modules. INCLUDING MODULES FROM FILES So far, I’ve mixed in modules that have been defined within a single source file. Often it is more useful to define modules in separate files and mix them in as needed. The first thing you have to do in order to use code from another file is to load that file using the require method, like this: CHAPTER TWELVE 225 THE BOOK OF RUBY require( "testmod.rb" ) Optionally, you may omit the file extension: require( "testmod" ) # this works too The required file must be in the current directory, on the search path or in a folder listed in the predefined array variable $:. You can add a directory to this array variable using the usual array-append method, << in this way: $: << "C:/mydir" The global variable, $: (a dollar sign and a colon), contains an array of strings representing the directories which Ruby searches when looking for a loaded or required file. The require method returns a true value if the specified file is successfully loaded; otherwise it returns false. If in doubt, you can simply display the result: puts(require( "testmod.rb" )) Any code which would normally be executed when a file is run will be executed when that file is required. So, if the file, testmod.rb, contains this code... def sing puts( "Tra-la-la-la-la....") end puts( "module loaded") sing ...and the file, require_module.rb contains this... require( "testmod.rb") 226 testmod.rb require_module.rb ...then, when require_module.rb is run, this will be the output: module loaded Tra-la-la-la-la.... When a module is declared in the required file, it can be mixed in: require( "testmod.rb") include MyModule #mix in MyModule declared in testmod.rb Ruby also lets you load a file using the load method. In most respects, require and load can be regarded as interchangeable. But there are a few subtle differ- ences. In particular, load can take an optional second parameter which, if this is true, loads and executes the code as an unnamed or anonymous module: load( "testmod.rb", true) The file loaded does not introduce the new namespace into the main program and you will not have access to all the module(s) in the loaded file. When the second argument to load is false or when there is no second argument, you will to have access to modules in the loaded file. Note that you must enter the full file name with load (‚testmod‛ minus the ‚.rb‛ extension will not suffice). Another difference is that require loads a file once only (even if your code requires that file many times) whereas load causes the specified file to be re- loaded each time load is called. Let’s suppose you have this in the file, test.rb: MyConst = 1 if @a == nil then @a = 1 else @a += MyConst end puts @a CHAPTER TWELVE load_module.rb test.rb 227 THE BOOK OF RUBY Let’s suppose you now require this file three times: require "test" require "test" require "test" This will be the output: 1 But if you load the file three times... load "test.rb" load "test.rb" load "test.rb" ...then this will be the output: 1 ./test.rb:1: warning: already initialized constant MyConst 2 ./test.rb:1: warning: already initialized constant MyConst 3 228 require_again.rb load_again.rb Digging Deeper MODULES AND CLASSES We’ve looked at the behaviour of a module. Let’s now find out what a module really is. It turns out that, as with most other things in Ruby, a module is an object. Each named module is, in fact, an instance of the Module class: module MyMod end puts( MyMod.class ) #=> Module
You cannot create descendents of named modules, so this is not allowed: module MyMod
end
module MyOtherMod < MyMod end However, as with other classes, it is permissible to create a descendent of the Module class: class X < Module end Indeed, the Class class is itself a descendent of the Module class. It inherits the behaviour of Module and adds on some important new behaviour – notably the ability to create objects. You can verify that Module is the superclass of Class by running the modules_classes.rb program which shows this hierarchy: Class Module #=> is the superclass of Class Object #=> is the superclass of Module
CHAPTER TWELVE
module_inst.rb
modules_classes.rb
229

THE BOOK OF RUBY
PRE-DEFINED MODULES
The following modules are built into the Ruby interpreter:
Comparable, Enumerable, FileTest, GC, Kernel, Math, ObjectSpace, Preci- sion, Process, Signal
Comparable is a mixin module which permits the including class to implement comparison operators. The including class must define the <=> operator, which compares the receiver against another object, returning -1, 0, or +1 depending on whether the receiver is less than, equal to, or greater than the other object. Comparable uses <=> to implement the conventional comparison operators (<, <=, ==, >=, and >) and the method between?.
Enumerable is a mix-in module for enumeration. The including class must provide the method each.
FileTest is a module containing file test functions; its methods can also be accessed from the File class.
The GC module provides an interface to Ruby’s mark and sweep garbage collection mechanism. Some of the underlying methods are also available via the ObjectSpace module.
Kernel is a module included by the Object class; it defines Ruby’s ‘built-in’ methods.
Math is a module containing module functions for basic trigonometric and transcendental functions. It has both ‘instance methods’ and module methods of the same definitions and names.
ObjectSpace is a module which contains routines that interact with the garbage collection facility and allow you to traverse all living objects with an iterator.
Precision is a mixin for concrete numeric classes with precision. Here, `precision’ means the fineness of approximation of a real number, so, this module should not be included into anything which is not a subset of Real (so it should not be included in classes such as Complex or Matrix).
230

CHAPTER TWELVE Process is the module for manipulating processes. All its methods are module
methods.
Signal is the module for handling signals sent to running processes. The list of available signal names and their interpretation is system dependent.
Here is a brief overview of three of the most commonly used Ruby modules...
KERNEL
The most important of the pre-defined modules is Kernel which provides many of the ‘standard’ Ruby methods such as gets, puts, print and require. In com- mon with much of the Ruby class library, Kernel is written in the C language. While Kernel is, in fact, ‘built into’ the Ruby interpreter, conceptually it can be regarded as a mixed-in module which, just like a normal Ruby mixin, makes its methods directly available to any class that requires it. Since it is mixed in to the Object class, from which all other Ruby classes descend, the methods of Kernel are universally accessible.
MATH
The Math module’s methods are provided as both ‘module’ and ‘instance’ methods and can therefore be accessed either by mixing Math into a class or by accessing the module methods ‘from the outside’ by using the module name, a dot and the method name; you can access constants, using a double-colon:
puts( Math.sqrt(144) ) puts( Math::PI )
math.rb
231

THE BOOK OF RUBY
COMPARABLE
The Comparable module provides the neat ability to define your own compari- son ‘operators’ <, <=, ==, >= and > by mixing the module into your class and defining the <=> method. You can then specify the criteria for comparing some value from the current object with some other value. You might, for example, compare two integers, the length of two strings or some more eccentric value such as the position of a string in an array. I’ve opted for this eccentric type of comparison in my example program, compare.rb. This uses the index of a string in an array of mythical beings in order to compare the name of one being with that of another. A low index such as ‘hobbit’ at index 0 is considered to be ‘less than’ a high index such as ‘dragon’ at index 6:
class Being
include Comparable
BEINGS = ['hobbit','dwarf','elf','orc','giant','oliphant','dragon']
attr_accessor :name
def <=> (anOtherName) BEINGS.index[@name]<=>BEINGS.index[anOtherName]
232
end
def initialize( aName ) @name = aName
end end
elf = Being.new('elf') orc = Being.new('orc') giant = Being.new('giant')
puts( elf.name < orc.name ) puts( elf.name > giant.name )
#=> true #=> false
compare.rb

SCOPE RESOLUTION
As with classes, you may use the double-colon scope resolution operator to access constants (including classes and other modules) declared inside modules. For example, let’s suppose you have nested modules and classes, like this:
module OuterMod moduleInnerMod
class Class1
end end
end
You could use the :: operator to access Class1, like this:
OuterMod::InnerMod::Class1
See Chapter 2 for an introduction to scope resolution of constants within classes...
Each module and class has its own scope, which means that a single constant name might be used in different scopes. This being so, you could use the :: operator to specify a constant within a precise scope:
Scope1::Scope2::Scope3 #...etc
If you use this operator at the very start of the constant name this has the effect of ‘breaking out’ of the current scope and accessing the ‘top level’ scope:
::ACONST # refers to ACONST at „top level‟ scope
The following program provides some examples of the scope operator:
CHAPTER TWELVE
233

THE BOOK OF RUBY
234
ACONST = "hello"
module OuterMod module InnerMod
ACONST=10 class Class1
class Class2 module XYZ class ABC
ACONST=100 def xyz
# We‟ll call this the „top-level‟ constant
puts( ::ACONST ) #<= this prints the „top-level‟ constant end end end end end end end puts(OuterMod::InnerMod::ACONST) #=> displays 10
puts(OuterMod::InnerMod::Class1::Class2::XYZ::ABC::ACONST) #=> displays 100
ob = OuterMod::InnerMod::Class1::Class2::XYZ::ABC.new
ob.xyz
#=> displays hello
scope_resolution.rb

MODULE FUNCTIONS
If you want a function to be available both as an instance and a module method, you can use the module_function method with a symbol matching the name of an instance method, like this:
module MyModule def sayHi
return "hi!" end
def sayGoodbye return "Goodbye"
end
module_function :sayHi end
The sayHi method may now be mixed into a class and used as an instance method:
class MyClass include MyModule
def speak puts(sayHi) puts(sayGoodbye)
end end
It may be used as a module method, using dot notation:
ob = MyClass.new ob.speak puts(MyModule.sayHi)
Since the sayGoodbye method here is not a module function, it cannot be used in this way:
CHAPTER TWELVE
module_func.rb
235

THE BOOK OF RUBY
puts(MyModule.sayGoodbye) #=> Error: undefined method
Ruby uses module_function in some of its standard modules such as Math (in the Ruby library file, complex.rb) to create ‘matching pairs’ of module and instance methods.
EXTENDING OBJECTS
You can add the methods of a module to a specific object (rather than to an entire class) using the extend method, like this:
module A
def method_a
puts( 'hello from a' ) end
end
class MyClass def mymethod
puts( 'hello from mymethod of class MyClass' ) end
end
ob = MyClass.new ob.mymethod ob.extend(A)
Now that the object ob is extended with the module A, it can access that mod- ule’s instance method, method_a:
ob.method_a
You can, in fact, extend an object with several modules all at once. Here, the modules B and C extend the object, ob:
236
extend.rb

ob.extend(B, C)
When an object is extended with a module containing a method with the same name as a method in the object’s class, the method from the module replaces the method from the class. So, let’s assume that ob is extended with this class< module C def mymethod puts( 'hello from mymethod of module C' ) end end Now, when you call ob.mymethod, the string 'hello from mymethod of module C' will be displayed rather than 'hello from mymethod of class MyClass', which was displayed previously. You can prevent an object from being extended it by ‘freezing’ it using the freeze method: ob.freeze Any attempt to extend this object further would result in a runtime error. In order to avoid such an error, you can use the frozen? method to test whether or not an object has been frozen: if !(ob.frozen?) ob.extend( D ) ob.method_d else puts( "Can't extend a frozen object" ) end CHAPTER TWELVE 237 THE BOOK OF RUBY 238 CHAPTER THIRTEEN Files and IO Ruby provides classes dedicated to handling IO – Input and Output. Chief among these is a class called, unsurprisingly, IO. The IO class lets you open and close IO ‘streams’ (sequences of bytes) and read and write data to and from them. For example, assuming you have a file called ‘textfile.txt, containing some lines of text, this is how you might open the file and display each line on screen: IO.foreach("testfile.txt") {|line| print( line ) } Here foreach is a class method of IO so you don’t need to create a new IO object in order to use it; instead, you just specify the file name as an argument. The foreach method takes a block into which each line that is read from the file is passed as an argument. You don’t have to open the file for reading and close it when you’ve finished (as you might expect from your experience with other languages) as Ruby’s IO.foreach method does this for you. IO has a number of other useful methods. For example, you could use the readlines method to read the file contents into an array for further processing. Here is a simple example which once again prints the lines to screen: lines = IO.readlines("testfile.txt") lines.each{|line| print( line )} CHAPTER THIRTEEN io_test.rb 239 THE BOOK OF RUBY The File class is a subclass of IO and the above examples could be rewritten using the File class: File.foreach("testfile.txt") {|line| print( line ) } lines = File.readlines("testfile.txt") lines.each{|line| print( line )} OPENING AND CLOSING FILES While some standard methods open and close files automatically, often, when processing the contents of a file, you will need to open and close the file explicit- ly. You can open a file using either the new or the open method. You must pass two arguments to one of those methods – the file name and the file ‘mode’ – and it returns a new File object. The File modes may be either integers which are defined by operating-system-specific constants or strings. The mode generally indicates whether the file is be opened for reading (‚r‛), writing (‚w‛) or reading and writing (‚rw‛). This is the list of available string modes: file_test.rb Mode Meaning "r" Read-only, starts at beginning of file (default mode). "r+" Read-write, starts at beginning of file. "w" Write-only, truncates existing file to zero length or creates a new file for writing. "w+" Read-write, truncates existing file to zero length or creates a new file for reading and writing. "a" Write-only, starts at end of file if file exists, otherwise creates a new file for writing. "a+" Read-write, starts at end of file if file exists, otherwise creates a new file for reading and writing. "b" (DOS/Windows only) Binary file mode (may appear with any of the key letters listed above). 240 Let’s look at an actual example of opening, processing and closing files. In open_close.rb I first open a file, ‚myfile.txt‛, for writing (‚w‛). When a file is opened for writing, a new file will be created if it doesn’t already exist. I use puts() to write six strings to the file, one string on each of six lines. Finally I close the file. f = File.new("myfile.txt", "w") f.puts( "I", "wandered", "lonely", "as", "a", "cloud" ) f.close Closing a file not only releases the ‘file handle’ (the pointer to the file data) but also ‘flushes’ any data from memory to ensure that it is all saved onto the file on disk. Failing to close a file may result in unpredictable side-effects (try comment- ing out the f.close shown above to see for yourself!). Now, having written text into a file, let’s see how to open that file and read the data back in. This time I’ll read the data in one character at a time. As I do so, I’ll keep a count of the characters that have been read. I’ll also keep a count of the lines, which will be incremented whenever I read in a linefeed character (given by ASCII code 10). For the sake of clarity, I’ll add a string to the end of each line that’s been read, displaying its line number. I’ll display the characters plus my line-end strings on screen and, when everything has been read from the file I’ll close it and display the statistics which I’ve calculated. Here is the complete code: charcount = 0 linecount = 0 f = File.new("myfile.txt", "r") while !( f.eof ) do c = f.getc() if ( c == 10 ) then # while not at end of file... # getc gets a single character # ...whose ASCII code is tested linecount += 1 puts( " " )
else
putc( c ) charcount += 1
end end
# putc here puts the char to screen
CHAPTER THIRTEEN
open_close.rb
241

THE BOOK OF RUBY
if f.eof then
puts( "" )
end
f.close
puts("This file contains #{linecount} lines and #{charcount} characters." )
FILES AND DIRECTORIES...
You can also use the File class to manipulate files and directories on disk. Before attempting to perform some operation on a file, you must naturally make sure that the file exists. It might, after all, have been renamed or deleted after the program started – or the user may have incorrectly entered a file or directory name.
You can verify the existence of a file using the File.exist? method. This is one of several testing methods which are provided to the File class by the FileTest module. As far as the File.exist? method is concerned, a directory counts as a file, so you could use the following code to test for the presence of a C:\ drive (note that you must use double file separator ‘\\’ characters in string, as a single ‘\’ will be treated as an escape character):
if File.exist?( "C:\\" ) then
puts( "Yup, you have a C:\\ directory" )
else
puts( "Eeek! Can't find the C:\\ drive!" )
end
If you want to distinguish between a directory and a data file, use the directory?
method:
def dirOrFile( aName )
if File.directory?( aName ) then
puts( "#{aName} is a directory" ) else
puts( "#{aName} is a file" ) end
end
242
file_ops.rb

COPYING FILES
Let’s put the File class to some practical use by writing a simple file backup program. When you run copy_files.rb you will be asked to choose a directory to copy from (the source directory) and another directory to copy to (the target directory). Assuming both directories exist, the program will then copy all the files from the source directory to the target directory. If the target directory does not exist, it will ask you if you would like to create it (you should enter ‚Y‛ to accept). I’ve supplied a source directory for you; just enter the name srcdir when prompted. When asked for a target directory, enter targetdir in order to create a subdirectory of that name beneath the current directory.
The program initializes the variable, sourcedir, with the path of the source directory and it initializes targetdir with the name of the target directory. This is the code that does the file copying:
Dir.foreach( sourcedir ){ |f|
filepath = "#{sourcedir}\\#{f}"
if !(File.directory?(filepath) ) then
if File.exist?("#{targetdir}\\#{f}") then
puts("#{f} already exists in target directory (not copied)" )
else
FileUtils.cp( filepath, targetdir ) puts("Copying... #{filepath}" )
end end
}
Here I’ve used the foreach method of the Dir class which passes into a block the file name, f, of each file in the specified directory. I’ll have more to say about the Dir class shortly. The code constructs a qualified path to the file, filepath, by appending the file name to the directory name given by the sourcedir variable. I only want to copy data files not directories so I test that filepath is a file and not a directory:
f !(File.directory?(filepath) )
CHAPTER THIRTEEN
copy_files.rb
243

THE BOOK OF RUBY
This program won’t copy over files that already exist, so it first checks to see if a file with the name, f, already exists in the target directory, targetdir:
if File.exist?("#{targetdir}\\#{f}")
Finally, assuming all the specified conditions are met, the source file, filepath, is
copied to targetdir:
FileUtils.cp( filepath, targetdir )
Here cp is a file-copy method found in the FileUtils module. This module also contains a number of other useful file handling routines such as mv(source, target) to move a file from source to target; rm( files ) to delete one or more files listed in the files parameter and mkdir to create a directory as I have done when creating targetdir in the current program:
FileUtils.mkdir( targetdir )
DIRECTORY ENQUIRIES
My backup program deals with just one directory level at a time – which is why it tests to see that a file, f, is not a directory before attempting to copy it. There are many times, however, when you may want to traverse the subdirectories. For an example of this, let’s write a program that calculates the sizes of all the subdi- rectories beneath a specified root directory. This might be useful if, for example, you wanted locate the biggest files and directories in order to free up disk space by archiving or deleting them.
Navigating through subdirectories provides us with an interesting programming problem. When we begin searching for the presence of subdirectories we have no idea whether we will find one, none or many. Moreover, any subdirectory we find may contain yet another level of subdirectories each of which may contain other subdirectories and so on through many possible levels.
244

A DISCURSION INTO RECURSION
Our program needs to be able to navigate down the entire subdirectory tree to any number of levels. In order to be able to do this we have to use recursion.
What Is Recursion?
Put simply, a recursive method is one that calls itself. If you aren’t familiar with recursive programming, see ‘Recursion Made Simple’ in the Digging Deeper section at the end of this chapter.
In the program, file_info.rb, the processfiles method is recursive:
def processfiles( aDir ) totalbytes = 0 Dir.foreach( aDir ){ |f|
mypath = "#{aDir}\\#{f}"
s = ""
if File.directory?(mypath) then
if f != '.' and f != '..' then
bytes_in_dir = processfiles(mypath)
puts( "