From: Dave Thomas <Dave@...>
Date: 2000-12-27T22:58:19+09:00
Subject: [ruby-talk:8110] Code examples in the pickaxe book [long]


A couple of people have mentioned here that they're having problems
because they're typing in code from the book, and some of the code
fragments aren't self contained.

I need some help from folks on the list to decide what to do. I'd like 
to publish the source code, but there is a problem, and I don't know
how big it is.

If we take class Song from the book, the actual source file looks like 
this:

     !0class Song
     !A  include Comparable
     !8  @@plays = 0
     !4  attr_reader :name, :artist, :duration
     !6  attr_writer :duration
     !1  def initialize(name, artist, duration)
     !1    @name     = name
     !1    @artist   = artist
     !1    @duration = duration
     !8    @plays    = 0
     !1  end
     !2  def to_s
     !2    "Song: #{@name}--#{@artist} (#{@duration})"
     !2  end
     !3  def name
     !3    @name
     !3  end
     !3  def artist
     !3    @artist
     !3  end
     !3  def duration
     !3    @duration
     !3  end
     !5  def duration=(newDuration)
     !5    @duration = newDuration
     !5  end
     !7  def durationInMinutes
     !7    @duration/60.0   # force floating point
     !7  end
     !7  def durationInMinutes=(value)
     !7    @duration = (value*60).to_i
     !7  end
     !8  def play
     !8    @plays += 1
     !8    @@plays += 1
     !8    "This  song: #@plays plays. Total #@@plays plays."
     !8  end
     !B  def record
     !B    "Recording..."
     !B  end
     !9  def inspect
     !9    self.to_s
     !9  end
     !A  def <=>(other)
     !A    self.duration <=> other.duration
     !A  end
     !0end

Each line starts with a '!' followed by a flag character. These lines
are interpreted by a preprocesor. So, for example, when we include the 
code for page 27 in the book, we say

   \begin{ruby}[0,1,8]

and in the typeset bok you only see the lines flagged 0, 1, or 8.

The benefit here is that the book code is shorter, and more relevant
to the point at hand. Another indirect benefit is that the code is
consistent: the method 'Song.initialize' for example, is defined once,
and then included where needed throughout the book.

But here's my problem. Take the code on page 25. There we talk about
writable attributes, and show the definition of method 'duration='
(flagged '5' above). A couple of paragraphs later we save 'but Ruby
can write this for you' and show attr_writer instead (coincidentally
flagged with '6' above). The code for the class contains both methods.

So, if I publish the source of class Song as it really is (the code
above minus the !'s), you'd end up with _both_ an attr_writer and a
definition of 'duration=' in the same file. And that's what worries
me. Folks might get the wrong impression from this, and we'd end up
confusing things even more.

So, what should I do? Do I need to do anything?


Thanks


Dave