Errata for Programming Ruby

#26913: In the second paragraph, the wording isn't really strong enough. Ruby _enforces_ these conventions. "should all start" should be "must all start", etc.--Rich Morin

#29389: Please change:
song.inspect
to
puts song.inspect

It is probably obvious to an experienced person, but not the person that is reading your book.

Thanks --twscannell@hotmail.com

#28352: "Similarly, the patterns \b and \B match word boundaries and nonword boundaries, respectively" would be clearer as "Similarly, the patterns \b and \B match word boundaries and word non-boundaries,
respectively"--Karl

#29614: In the example on the bottom of page 67, there is this line:

include Comparable

The include statement was not covered earlier in the book, and there is no explanation of what it does after the example.

Suggestion: explain it or don't use it.--7stud

#29295: The second last paragraph says "Whoever created it entered all the artists' names in lowercase.", and then goes on to explain how to make them mixed case. But the part of the file that we've been shown on page 63 doesn't show the artist names in lowercase.--Steve

#27026: The fact that empty rescue rescues StandardErrors should be more emphasized - a separate paragraph or a side box or at least bold font. It seems that many people overlook this pretty important sentence.--Jano Svitok

#28899: When the raise statement (with no parameters) is called, the exception is rethrown. Can we say a few words about the type of the error? I believe it is RuntimeError.--Wing

#29647: On p. 118-119 is this passage:

If this made you think of class methods, your next thought may well be "what happens if I define instance methods within a module?" Good question. A module can't have instances, because a module isn't a class[Ok, no module instance methods]. However, you can include a module in a class definition. When this happens, all the module's instance methods are suddenly available as methods in the class as well. [Whoa! A module's instance methods?]

I propose this change:

If this made you think of class methods, your next thought may well be "what happens if I define instance methods within a module?" Good question. You can define instance methods in a module, but they are not like instance methods in a class. Since a module is not a class, you cannot create instances of a module and use them to call the module's instance methods.

However, you can include a module within a class definition. When this happens, all the modules instance methods are suddenly available as methods in the class as well.
--7stud

#29677: p. 129: Reading and Writing Files -- The are no descriptions or examples showing how to write to a file in this section. So I find the title of the section baffling.

In addition, the intro to the chapter says:

"In this chapter, we'll be concentrating on class IO and its most commonly used subclass File."

"IO" stands for Input/Output. Yet, there isn't a single example in the whole chapter showing how to write to a File, i.e. the Output half of Input/Output.

The acknowledgments at the beginning of the book tout the excellent work done by swarms of volunteer reviewers. Here's a suggestion, next time give your book to someone who has never heard of Ruby before. Then give their comments 100 times the weight of anyone else's.

In case anyone might ever need to *write* to a file using Ruby, here are some examples:

File.open("aaa.txt", "w") do |file|
file.print("hello\n", "world\n", "goodbye\n")
end
#'w': erases existing file or creates new file

File.open("bbb.txt", "w") do |file|
file.puts("hello", "world", "goodbye")
end
#puts automatically adds a new line to
#each argument.

File.open("bbb.txt", "a") do |file| #'a' for append
count = file.write("hi\nmars\nout\n")
puts "The number of bytes written to the file was: #{count}."
end
#'a': appends to the end of the file, i.e. does not
#erase file.

--7stud

#36769: Chapter 11, “Threads and Processes”, contains a section “Condition Variables”. The book gives a code example that uses a condition variable. However, other than a vague two-sentence description in the book (“A condition variable is a controlled way of communicating an event [or a condition] between two threads. One thread can wait on the condition, and the other can signal it.”), condition variables are not described in the main part of the book, in the reference part of the book, or even in the ri documentation. The closest one can get is by executing ri commands on some of the unexplained commands in the code sample (“ri new_cond”, “ri signal”). “ri new_cond” only obtains a “FIXME” notice, while “ri signal” tells you that you could look at a number of “signal” commands, including “ConditionVariable#signal” and “MonitorMixin::ConditionVariable#signal”. These produce fairly cryptic descriptions as well, though they do at least tell you that ConditionVariable is a genuine class (a fact that should be mentioned in the book).

If a subject is important enough to be discussed in the main part of the book, then it should be documented thoroughly where it is brought up, as well as in the reference part of the book and in the ri documentation. Otherwise, it derails the reader, who should be allowed to focus on the subject matter.

Note that the posted errata contain the following note, which is in accord with my perception: ”#29349: It’s not clear what the condition variable is in the code example.—bob”--Alan Frankel

#29736: Unit Testing, chap 12: This omitted fact caused me hours of frustration and testing until I discovered how things work. Suppose you have a simple program that prompts the user for some information like this:

my_prog.rb
----------
def get_name(msg)
print msg
gets
end
def get_scores(msg)
print msg
gets
end

name = get_name("Name: ")
scores = get_scores("scores: ")

#do something with
#user info...

Then having just read about unit testing in pickaxe2, you decide to create a unit test for your program to test the get_scores method, and this is what you come up with:

my_test.rb
---------
require "test/unit"
require "my_prog.rb"

class TestFuncs < Test::Unit::TestCase
def test_get_scores
input = get_scores("scores: ")
assert_instance_of(Array, input)
end
end

However, if you run that unit test, the method get_name will execute--even though the unit test does not attempt to execute the get_name method.

Apparently, when you run a unit test on a program, any code in the program that is not inside a class definition or a top level method definition will execute before the unit test executes.

One solution is to just comment out any code that is outside of any class or method definitions. Another solution is to surround any code that is not in a class or a method definition with the block:

if __FILE__ == $0
..
..
end

So the program would look like this:

my_prog.rb
----------
def get_name(msg)
print msg
gets
end
def get_scores(msg)
print msg
gets
end

if __FILE__ == $0
name = get_name("Name: ")
scores = get_scores("scores: ")
end

__FILE__ is the name of the file containing the __FILE__ statement, which in this case is my_prog.rb And $0 is the name of the file you entered on the command line to execute with ruby, i.e.:

ruby my_test.rb

The net effect is that when you run the program directly, e.g.

ruby my_prog.rb

the code in the if block will execute. However, if the file is require'ed into another program, and that other program is executed, e.g.

ruby my_test.rb

the code in the if block won't execute. Suggestion: please mention something about this in the next edition.
--7stud

#29737: p. 160, "Where to put Tests", middle of the page: The text says, "A better solution is to run the tests from the directory containing the library being tested." On the previous page is a diagram of the directory structure:

roman/ (note: there is a missing slash after roman)
-----lib/
--------roman.rb
-----test/
--------test_roman.rb

I think a literal reading of that quoted sentence means that you should run your tests from the roman directory. However, it turns out that the book is using the term "library" to refer to roman.rb--not the lib directory. That couldn't be anymore confusing.

To clear things up: one way to run the test program from the command line is to first cd to the lib directory. Then use the command:

/lib% ruby ../test/test_roman.rb

The current directory is always included by default in the search path used by require and include. test.roman.rb has a require statement that says:

require roman.rb

One place ruby will look for roman.rb is in the current directory, and since the current directory is /lib, ruby will be able to find roman.rb.

The whole purpose of this whole section is a little tricky to understand. If I've got it right: when program A is required into program B, the path of a require statement in program A will be relative to program B's directory. If program A has a require statement like this:

require "fileX"

then fileX is in the directory containing A. If program B then require's program A into program B, and program B is in another directory, then ruby will search B's directory for fileX. Since fileX is not in B's directory, that will cause an error.
--7stud

#36807: The book gives the following guideline:

"Within a class definition, Ruby will parse setter= as an assignment to a local variable, not as a method call. User the form self.setter= to indicate the method call."

There are two confusing things about this. The first is that "setter" is a placeholder, not an actual word. Perhaps it should be written in italics.

The second is that a simpler, more intuitive, and more common approach is not mentioned: using "@" rather than "self." on the left-hand side to indicate that an instance variable is being referred to. This approach should be mentioned in the text and also in the code:

class Incorrect
attr_accessor :one, :two, :three
def initialize
one = 1 # incorrect - sets local variable
self.two = 2 # correct - sets instance variable
@three = 3 # also correct - sets instance variable
end
end--Alan Frankel

#36806: In the example illustrating "Watch out for precedence issues...", the complexity of the code (which contains several branches that are not executed) obscures the point being made. It probably also makes sense to execute the "puts" statements right after setting the corresponding variables.

Something like this might be better:

def one(arg)
"block given to 'one' returns #{yield}"
end

def two(arg)
"block given to 'two' returns #{yield}"
end

# Version with braces
result1 = one two {
"three"
}

puts "With braces, result = #{result1}"

# Version with do/end
result2 = one two do
"three"
end

puts "With do/end, result = #{result2}"
--Alan Frankel

#28911: Since I was checking the gems directory, I found that all the doc/ directories in gems/ are all named with the singular form, not the plural form docs/. The book uses the plural form. Again is there a standard?--Wing

#36866: Two examples of a CGI script are given, where the only difference is that the second inserts a header. But this is obscured by the fact that this difference is listed as a parenthetical remark, and is not followed by a colon linking it to the following script. To avoid confusion, this paragraph:

"Put this script in a CGI directory, mark it as executable, and you'll be able to access it via your browser. (If your Web server doesn't automatically add headers, you'll need to add the response header yourself.)"

should be rewritten as follows:

"Put this script in a CGI directory, mark it as executable, and you'll be able to access it via your browser. If your Web server doesn't automatically add headers, you'll need to add the response header yourself as follows:"
--Alan Frankel

#26874: The Google SOAP API seems no longer available for new users. Google says:
<CITE>
As of December 5, 2006, we are no longer issuing new API keys for the SOAP Search API. Developers with existing SOAP Search API keys will not be affected.

Depending on your application, the AJAX Search API may be a better choice for you instead. It tends to be better suited for search-based web applications and supports additional features like Video, News, Maps, and Blog search results.

For developers who are already using the SOAP Search API, we've kept the documentation live on this site.
</CITE>

Thanks for the great book!--Remi

#29760: I'm currently using your "Programming Ruby" as a reference while learning Ruby and especially Rails. I'm highly enjoying the book.

I did encounter one pain point, though: Symbols.

The concept of ruby symbols is used practically everywhere in RoR, so I very soon started looking through my Ruby books for some kind of explanation for the : that seemed to pop up everywhere. The explanation given on p336 in the 2nd edition (9th printing, if this makes a difference), did not leave me much less confused. I hope you'll consider elaborating the section a bit. Googling for "Ruby symbols" gave me the impression that I'm not the first programmer moving into Ruby to have struggled with the concept, but did lead me to some articles that cleared it up a bit more.

Hope you can use the above suggestion in some future revision of the book.--Henrik

#36872: The code sample on page 357 could be improved in two ways: (1) The sample could demonstrate more aspects of the description at the top of the page. For instance, there should be "yield" statements that pass parameters as well as "yield" statements that don't. (2) The sample could include more printed output to clarify what is going on. Currently, there is no output for any of the statements within the "Holder" class.--Alan Frankel

#36875: The final lines of the code sample may be poorly chosen as a means to illustrate the points made in the following paragraph.

The end of the code sample, followed by the final paragraph, runs as follows:

:::

iv = Roman.new(4)
xi = Roman.new(11)

3 * iv --> 12
1.1 * xi --> 12.1

Of course, class Roman as implemented doesn't know how to do addition itself: you couldn't have written "xi + 3" in the previous example, as Roman doesn't have a "plus" method. And that's probably as it should be. But let's go wild and implement addition for Roman numbers.

:::

But that paragraph confuses the issue by bringing up addition whereas the code sample used multiplication. The important point that the paragraph is probably intended to make is that the order is important.

Here are a rewritten code sample and paragraph that make the point more effectively:

:::

iv = Roman.new(4)
xi = Roman.new(11)

3 * iv --> 12
1.1 * xi --> 12.1
3 + iv --> 7
1.1 + xi --> 12.1

iv * 3 --> error
xi * 1.1 --> error
iv + 3 --> error
xi + 1.1 --> error

Of course, class Roman as implemented doesn't know how to do multiplication or addition itself: you couldn't have written "xi + 3" in the previous example, as Roman doesn't have a "plus" method. And that's probably as it should be. But let's go wild and implement addition for Roman numbers.

:::--Alan Frankel

#29207: Under 'clone', I think it would be helpful to mention that cloned objects retain singleton methods while duped objects do not. For example,

class Snark
def beware
"Snarks are dangerous"
end
end

boojum = Snark.new

def boojum.beware
"Boojums are even more dangerous"
end

boojum.beware # => "Boojums are even more dangerous"
boojum.dup.beware # => "Snarks are dangerous"
boojum.clone.beware # => "Boojums are even more dangerous"

And maybe a cross-reference from 'dup'?
--Morton Goldberg

#29287: The second paragraph says: "ERB breaks its input text into checks of regular text and program fragments." Perhaps "chunks" makes more sense then "checks".--Steve

#30496: Library ParseDate, second line: if the time zone is included in the returned array, it's not just "an array of Fixnum values", but "an array of Fixnum and String values".--Felix Siegrist

#26674: The bookmarks section of the PDF no longer contains a link to the Index. What happened to it? Can you put it back? The last thing I see is "Part V, Appendixes". Adobe Reader 7.08, Windows XP.--Daniel Berger

#26684: It would be nice if there was an index entry for ? that referenced pp. 319-320 where using ? to obtain the integer value of an ASCII character is described.

I went to the index after viewing the sample on p. 550 that used that technique and didn't find anything in the index.
--Brian Adkins

#32686: This may have been mentioned before, but the TOC no longer contains a link to the index in the PDF version. It would be great if it could have a link, not just to the start of the index, but to each letter in the index. This would make it much faster to skip to the portion of the book that contains what you're looking for. For an example, see the TOC in the Agile Web Development with Rails book.--Jason M. Kusar