In the previous chapter, we covered a common pattern for interface simplification, allowing you to turn code like this:

pdf = Prawn::Document.new
pdf.text "Hello World"
pdf.render_file "hello.pdf"

into something like this:

Prawn::Document.generate("hello.pdf") do
  text "Hello World"
end

As you’ll recall, this trick is relatively straightforward to implement:

class Prawn::Document
  def self.generate(file, *args, &block)
    pdf = Prawn::Document.new(*args)
    pdf.instance_eval(&block)
    pdf.render_file(file)
  end
end

However, there is a limitation that comes with this sort of interface. Because we are evaluating the block in the context of a Document instance, we do not have access to anything but the local variables of our enclosing scope. This means the following code won’t work:

class MyBestFriend

  def initialize
    @first_name = "Paul"
    @last_name  = "Mouzas"
  end

  def full_name
    "#{@first_name} #{@last_name}"
  end

  def generate_pdf
    Prawn::Document.generate("friend.pdf") do
      text "My best friend is #{full_name}"
    end
  end

end

It’d be a shame to have to revert to building this stuff up manually, and a bit messy to rely on storing things in local variables. Luckily, there is a middle-of-the-road option: we can optionally yield a Document object. Here’s how we’d go about doing that:

class Prawn::Document
  def self.generate(file, *args, &block)
    pdf = Prawn::Document.new(*args)
    block.arity < 1 ? pdf.instance_eval(&block) : block.call(pdf)
    pdf.render_file(file)
  end
end

This new code preserves the old instance_eval behavior, but allows a new approach as well. We can now write the following code without worry:

class MyOtherBestFriend

  def initialize
    @first_name = "Pete"
    @last_name  = "Johansen"
  end

  def full_name
    "#{@first_name} #{@last_name}"
  end

  def generate_pdf
    Prawn::Document.generate("friend.pdf") do |doc|
      doc.text "My best friend is #{full_name}"
    end
  end

end

Here, the code is an ordinary closure, and as such, can access the instance methods and variables of the enclosing scope. Although we need to go back to having an explicit receiver for the PDF calls, our Document.generate method can still do its necessary setup and teardown for us, salvaging some of its core functionality.

The feature that makes this all possible is Proc#arity. This method tells you how many arguments, if any, the code block was given. Here’s a few examples as an illustration:

>> lambda { |x| x + 1 }.arity
=> 1
>> lambda { |x,y,z| x + y + z }.arity
=> 3
>> lambda { 1 }.arity
=> 0

As you can see, because Proc objects are just objects themselves, we can do some reflective inquiry to find out how many arguments they’re expecting to process. Although not strictly related to our task, it’s worth mentioning that you can accomplish the same thing with methods as well:

>> Comparable.instance_method(:between?).arity
=> 2
>> Fixnum.instance_method(:to_f).arity
=> 0

Although our use of an arity check was confined to a relatively simple task here, the technique is general. Any time you want to conditionally handle something based on how many block arguments are present, you can use this general approach.

That having been said, even if you never use this trick for anything else, knowing how to selectively instance_eval a block is important. As you’ll see through the rest of this section, a key part of developing a pleasant domain-specific interface is maintaining flexibility. If you limit yourself to an all-or-nothing choice between your sexy shortcuts and the bland, low-level API, frustration is inevitable. Of course, because Ruby is so dynamic, you should never be forced to make this decision.

We’ll now move on to another key component of flexible interface design: the use of method_missing and send to dynamically route messages within your objects.

Continuing on a theme, we can look at more Prawn code to see how to make things a bit more dynamic. We’ll be looking at elementary drawing operations here, but you can substitute your own problem mentally. As in other examples, the actual domain does not matter.

In Prawn, there are two ordinary ways to generate some shapes and then draw them onto the page. The first is the most simple—just drawing the paths, and then calling one of stroke, fill, or fill_and_stroke:

Prawn::Document.generate("shapes.pdf") do
  fill_color "ff0000"

  # Fills a red circle
  circle_at [100,100], :radius => 25
  fill

  # Strokes a transparent circle with a black border and a line extending
  # from its center point
  circle_at [300,300] :radius => 50
  line [300,300], [350, 300]
  stroke

  # Fills and strokes a red hexagon with a black border
  polygon [100, 250], [200, 300], [300, 250],
          [300, 150], [200, 100], [100, 150]
  fill_and_stroke
end

This isn’t too bad, but for some needs, a block form is better. This makes it clearer what paint operation is being used, and may be a bit easier to extend:

Prawn::Document.generate("shapes.pdf") do
  fill_color "ff0000"

  # Fills a red circle
  fill { circle_at [100,100], :radius => 25 }

  # Strokes a transparent circle with a black border and a line extending
  # from its center point
  stroke do
    circle_at [300,300] :radius => 50
    line [300,300], [350, 300]
  end

  fill_and_stroke do
    # Fills and strokes a red hexagon with a black border
    polygon [100, 250], [200, 300], [300, 250],
            [300, 150], [200, 100], [100, 150]
  end

end

This may be a bit more readable, especially the middle one, in which multiple paths need to be stroked. However, it still feels like more work than we’d really want. Wouldn’t things be nicer this way?

Prawn::Document.generate("shapes.pdf") do
  fill_color "ff0000"

  fill_circle_at [100,100], :radius => 25

  stroke_circle_at [300,300] :radius => 50
  stroke_line [300,300], [350, 300]

  fill_and_stroke_polygon [100, 250], [200, 300], [300, 250],
                          [300, 150], [200, 100], [100, 150]
end

This has a nice, declarative feel to it. Obviously though, we don’t want to define four methods for every graphics drawing operation. This is especially true when you think of the nature of what each of these would look like. Let’s take stroke for example:

def stroke_some_method(*args)
  some_method(*args)
  stroke
end

Repeat that ad nauseam for every single drawing method, and keep up this pattern every time a new one is added? No way! Maybe this sort of repetition would be tolerated over in Java-land, but in Ruby, we can do better. The answer lies in dynamically interpreting method calls.

When you attempt to call a method that doesn’t exist in Ruby, you see an exception raised by default. However, Ruby provides a way to hook into this process and intercept the call before an error can be raised. This is done through the method method_missing.

To give a very brief introduction to how it works, let’s take a quick spin in irb:

>> def method_missing(name, *args, &block)
>>   puts "You tried to call #{name} with #{args.inspect}"
>>   puts "Epic Fail!"
>> end
=> nil
>> 1.fafsafs
You tried to call fafsafs with []
Epic Fail!
=> nil
>> "kitten".foo("bar", "baz")
You tried to call foo with ["bar", "baz"]
Epic Fail!

By including a method_missing hook at the top level, all unknown messages get routed through our new method and print out our message. As you can see, the name of the message as well as the arguments are captured. Of course, this sort of global change is typically a very bad idea, and serves only as an introduction. But if you’re feeling ambitious, take a moment to think about how this technique could be used to solve the problem we’re working on here, before reading on.

Did you have any luck? If you did attempt this exercise, what you would find is that method_missing isn’t very useful on its own. Typically, it is used to do part of a job and then route the work to another function. The way we do this is by making use of Kernel#send, which allows us to call a method by just passing a symbol or string, followed by any arguments:

>> "foo".send(:reverse)
=> "oof"
>> [1,2,3].send("join", "|")
=> "1|2|3"

Does this clue make things a bit clearer? For those who didn’t try to build this on their own, or if you attempted it and came up short, here’s how to make it all work:

# Provides the following shortcuts:
#
#    stroke_some_method(*args) #=> some_method(*args); stroke
#    fill_some_method(*args) #=> some_method(*args); fill
#    fill_and_stroke_some_method(*args) #=> some_method(*args); fill_and_stroke
#
def method_missing(id,*args,&block)
  case(id.to_s)
  when /^fill_and_stroke_(.*)/
    send($1,*args,&block); fill_and_stroke
  when /^stroke_(.*)/
    send($1,*args,&block); stroke
  when /^fill_(.*)/
    send($1,*args,&block); fill
  else
    super
  end
end

As the documentation describes, this hook simply extracts the paint command out from the method call, and then sends the remainder as the function to execute. All arguments (including an optional block) are forwarded on to the real method. Then, when it returns, the specified paint method is called.

It’s important to note that when the patterns do not match, super is called. This allows objects up the chain to do their own method_missing handling, including the default, which raises a NoMethodError. This prevents something like pdf.the_shiny_kitty from failing silently, as well as the more subtle pdf.fill_circle.

Although this is just a single example, it should spark your imagination for all the possibilities. But it also hints at the sort of looseness that comes with this approach. Prawn will happily accept pdf.fill_and_stroke_start_new_page or even pdf.stroke_stroke_stroke_line without complaining. Any time you use the method_missing hook, these are the trade-offs you must be willing to accept. Of course, by making your hooks more robust, you can get a bit more control, but that starts to defeat the purpose if you take it too far.

The best approach is to use method_missing responsibly and with moderation. Be sure to avoid accidental silent failures by calling super for any case you do not handle, and don’t bother using it if you want things to be ironclad. In cases where there is a relatively small set of methods you want to generate dynamically, a solution using define_method might be preferred. That having been said, when used as a shortcut alternative to a less pleasant interface, method_missing can be quite helpful, especially in cases where the messages you’ll need to accept are truly dynamic.

The techniques described so far combined with some of the methods shown in the previous chapter will get you far in building a domain-specific interface. We’re about to move on to other dynamic Ruby topics, but before we do that, we’ll cover one more cheap trick that leads to clean and flexible interfaces.

One thing you will notice when working with code that has an instance_eval-based interface is that using ordinary setters can be ugly. Because you need to disambiguate between local variables and method calls, stuff like this can really cramp your style:

Prawn::Document.generate("accessors.txt") do

  self.font_size = 10
  text "The font size is now #{font_size}"

end

It’s possible to make this look much nicer, as you can see:

Prawn::Document.generate("accessors.txt") do

  font_size 10
  text "The font size is now #{font_size}"

end

The concept here isn’t a new one; we covered it in the previous chapter. We can use Ruby’s default argument syntax to determine whether we’re supposed to be getting or setting the attribute:

class Prawn::Document

  def font_size(size = nil)
    return @font_size unless size
    @font_size = size
  end

  alias_method :font_size=, :font_size

end

As I said before, this is a relatively cheap trick with not much that is special to it. But the first time you forget to do it and find yourself typing self.foo = bar in what is supposed to be a domain-specific interface, you’ll be sure to remember this technique.

One thing to note is that you shouldn’t break the normal behavior of setters from the outside. We use alias_method here instead of attr_writer to ensure down the line that there won’t be any difference between the following two lines of code:

pdf.font_size = 16
pdf.font_size(16)

Though not essential, this is a nice way to avoid potential headaches at a very low cost, so it’s a good habit to get into when using this technique.

When we combine all the tactics we’ve gone over so far, we’ve got all the essential components for building flexible domain-specific interfaces. Before we move on to the next topic, let’s review the main points to remember about flexible interface design:

With these tips in mind, let’s move on to another topic. It’s time to shift gears from per-class dynamic behavior to individual objects.

In Chapter 1, Driving Code Through Tests, I mentioned and made use of a small extension to Test::Unit that dynamically defines test methods for us. As previously mentioned, we’ve borrowed this functionality from the granddaddy of Ruby extensions, ActiveSupport. We glossed over the implementation details before, but now that we’re on the topic, this serves as a good example of the sorts of things you can accomplish by extending preexisting classes. We still don’t need to worry about how it works; the focus is on how it extends TestCase:

module Test::Unit
  class TestCase

    def self.must(name, &block)
      test_name = "test_#{name.gsub(/s+/,'_')}".to_sym
      defined = instance_method(test_name) rescue false
      raise "#{test_name} is already defined in #{self}" if defined
      if block_given?
        define_method(test_name, &block)
      else
        define_method(test_name) do
          flunk "No implementation provided for #{name}"
        end
      end
    end

  end
end

To recap, the purpose of the must() method is to allow you to write your test cases a bit more cleanly. Here’s an example from a board game I’ve been working on:

  class TestStone < Test::Unit::TestCase
    def setup
      @board = Pressman::Board.new
      @stone = Pressman::Stone.new(:black, :board    => @board,
                                           :position => [3,3] )
    end

    must "have a color" do
      assert_equal :black, @stone.color
    end

    must "have a default status of active" do
      assert_equal :active, @stone.status
    end

    must "be able to deactivate" do
      @stone.deactivate
      assert_equal :inactive, @stone.status
    end
  end

Without this extension, you would need to write the full test method names out in the traditional way:

  class TestStone < Test::Unit::TestCase
    def setup
      @board = Pressman::Board.new
      @stone = Pressman::Stone.new(:black, :board    => @board,
                                           :position => [3,3] )
    end

    def test_must_have_a_color
      assert_equal :black, @stone.color
    end

    def test_must_be_active_by_default
      assert_equal :active, @stone.status
    end

    def test_must_be_able_to_deactivate
      @stone.deactivate
      assert_equal :inactive, @stone.status
    end
  end

Although this code might be a bit more conceptually simple, it is also a bit less readable and doesn’t have the same shortcuts that must() provides. For example, if you just write a single line like this:

must "do something eventually"

The extension will create a failing test for you. For those familiar with RSpec, this is similar to the pending test functionality you’d find there. Of course, by tweaking Test::Unit a bit for our own needs, we can focus on adding only the functionality we’re missing, rather than jumping ship and moving to a whole other system. This is a key benefit of Ruby’s open class system.

From what we’ve seen so far, it seems like adding functionality to a class definition is as easy as defining a new class. It uses the same syntax without any additional overhead. However, that is not to say it is without dangers.

If you can extend predefined objects for your own needs, so can everyone else, including any of the libraries you may depend on. Though we’ll discuss safe techniques for combining partial definitions a little later, the technique shown here of simply opening up a class and defining a new method can result in naming clashes.

Consider two fictional units libraries, one of which converts things like 12.in and 15.ft into meters. We’ll call this metrics_conversions.rb:

class Numeric
  def in
    self * 0.0254
  end

  def ft
    self.in * 12
  end
end

Our other library converts them into PDF points (1/72 of an inch). We’ll call this pdf_conversions.rb:

class Numeric
  def in
    self * 72
  emd

  def ft
    self.in * 12
  end
end

If we load both libraries in, which one gets used? Let’s ask irb:

>> require "metrics_conversions"
=> true
>> 1.in
=> 0.0254
>> require "pdf_conversions"
=> true
>> 1.in
=> 72

As you can see, whatever code is loaded last takes precedence. The way we have written it, the old definitions are completely clobbered and there is no easy way to recover them.

Because we’d almost never want two competing units systems loaded at the same time, it’d be better to see an error rather than a silent failure here. We can do that with the PDF conversion code and see what it looks like:

class Numeric

  [:in, :ft].each do |e|
    if instance_methods.include?(e)
      raise "Method '#{e}' exists, PDF Conversions will not override!"
    end
  end

  def in
    self * 72
  end

  def ft
    self.in * 12
  end

end

Loaded in on its own, this code runs without issue:

>> require "pdf_conversions"
=> true
>> 1.in
=> 72
>> 1.ft
=> 864

But when we revisit the original name clash problem, we have a much more explicit indicator of this issue:

>> require "metrics_conversions"
=> true
>> require "pdf_conversions"
RuntimeError: Method 'in' exists, PDF Conversions will not override!
        ...

Of course, if we do not modify metrics_conversions.rb as well, it will silently override pdf_conversions.rb. The ideal situation is for both libraries to use this technique, because then, regardless of the order in which they are required, the incompatibility between dependencies will be quickly spotted.

It is worth mentioning that it is possible for the library that is loaded first to detect the second library’s attempt to override its definitions and act upon that, but this is generally considered aggressive and also results in fairly convoluted code, so it’s better to address your own problems than the problems of others when it comes to extending an object’s functionality.

So far, we’ve been talking about adding new functionality and dealing with accidental clashes. However, there are going to be times when you intentionally want to modify other code, while preserving some of its initial functionality. Ruby provides a number of ways to do that, so let’s examine a few of them and weigh their risks and benefits.

We’ve used alias_method before for the purpose of making a new name point at an old method. This of course is where the feature gets its name: allowing you to create aliases for your methods.

But another interesting aspect of alias_method is that it doesn’t simply create a new name for a method—it makes a copy of it. The best way to show what this means is through a trivial code example:

# define a method
class Foo
  def bar
    "baz"
  end
end

f = Foo.new
f.bar #=> "baz"


# Set up an alias
class Foo
  alias_method :kittens, :bar
end

f.kittens #=> "baz"

# redefine the original method
class Foo
  def bar
    "Dog"
  end
end

f.bar      #=> "Dog"
f.kittens  #=> "baz"

As you can see here, even when we override the original method bar(), the alias kittens() still points at the original definition. This turns out to be a tremendously useful feature.

Because I like to keep contrived examples to a minimum, we’re going to take a look at a real use of this technique in code that we use every day, RubyGems.

When RubyGems is loaded, it provides access to the libraries installed through its package manager. However, we typically don’t need to load these packages through some alternative interface, we just use Kernel#require, as we do when we’re loading in our own application files. The reason this is possible is because RubyGems patches Kernel#require using the exact technique we’ve been talking about here. This is what the code looks like for custom_require.rb:

module Kernel

  ##
  # The Kernel#require from before RubyGems was loaded.

  alias_method :gem_original_require, :require

  def require(path) # :doc:
    gem_original_require path
  rescue LoadError => load_error
    if load_error.message =~ /#{Regexp.escape path}z/ and
       spec = Gem.searcher.find(path) then
      Gem.activate(spec.name, "= #{spec.version}")
      gem_original_require path
    else
      raise load_error
    end
  end

end

This code first makes a copy of the original require method, then begins to define its enhanced one. It first tries to call the original method to see whether the requested file can be loaded that way. If it can, then it is exactly equivalent to before RubyGems was loaded, and no further processing is needed.

However, if the original require fails to find the requested library, the error it raises is rescued, and then the RubyGems code goes to work looking for a matching gem to activate and add to the loadpath. If it finds one, it then goes back to the original require, which will work this time around because the necessary files have been added to the path.

If the code fails to find a gem that can be loaded, the original LoadError is raised. So this means that in the end, it reverts to the same failure condition as the original require method, making it completely invisible to the user.

This is a great example of responsible modification to a preexisting method. This code does not change the signature of the original method, nor does it change the possible return values or failure states. All it does is add some new intermediate functionality that will be transparent to the user if it is not needed.

However, this concept of copying methods via alias_method might seem a bit foreign to some folks. It also has a bit of a limitation, in that you need to keep coming up with new aliases, as aliases are subject to collision just the same as ordinary methods are.

For example, although this code works fine:

class A

  def count
    "one"
  end

  alias_method :one, :count

  def count
    "#{one} two"
  end

  alias_method :one_and_two, :count

  def count
    "#{one_and_two} three"
  end

end

A.new.count #=> "one two three"

if we rewrote it this way, we’d blow the stack:

class A

  def count
    "one"
  end

  alias_method :old_count, :count

  def count
    "#{old_count} two"
  end

  alias_method :old_count, :count

  def count
    "#{old_count} three"
  end

end

Accidentally introducing infinite recursion by aliasing an old method twice to the same name is definitely not fun. Although this problem is rarer than you might think, it’s important to know that there is a way around it.

If we move our modifications from the per-class level to the per-object level, we end up with a pretty nice solution that gets rid of aliasing entirely, and simply leverages Ruby’s ordinary method resolution path. Here’s how we’d do it:

class A
  def count
    "one"
  end
end

module AppendTwo
  def count
    "#{super} two"
  end
end

module AppendThree
  def count
    "#{super} three"
  end
end

a = A.new
a.extend(AppendTwo)
a.extend(AppendThree)
a.count #=> "one two three"

Here, we have mixed two modules in an instance of A, each of them relying on a call to super(). Each method redefinition gets to use the same name, so we don’t need to worry about naming clashes. Each call to super goes one level higher, until it reaches the top-level instance method as defined in the class.

Provided that all the code used by your application employs this approach instead of aliased method chaining, you end up with two main benefits: a pristine original class and no possibility for collisions. Because the amended functionality is included at the instance level, rather than in the class definition, you don’t risk breaking other people’s code as easily, either.

Note that not every single object can be meaningfully extended this way. Any objects that do not allow you to access their singleton space cannot take advantage of this technique. This mostly applies to things that are immediate values, such as numbers and symbols. But more generally, if you cannot use a call to new() to construct your object, chances are that you won’t be able to use these tricks. In those cases, you’d need to revert to aliasing.

Even with this limitation, you can get pretty far with this approach. I don’t want to end the section without one more practical example, so we’ll look at a fun trick that earlier versions of Ruport did to manage a memory consumption issue in PDF::Writer.

Back before I maintained the Ruby PDF project, it went through a couple years of being relatively unsupported. However, when I ran into problems with it, Austin Ziegler was often willing to help me find workarounds for my own needs, even if he wasn’t able to find the time to get them into a maintenance release for PDF::Writer.

One such fix resolved a memory consumption issue by setting up a hook for transaction_simple in PDF::Writer. I won’t go into the details of how this works, but here is the module that implements it:

module PDFWriterMemoryPatch #:nodoc:
  unless self.class.instance_methods.include?("_post_transaction_rewind")
    def _post_transaction_rewind
      @objects.each { |e| e.instance_variable_set(:@parent,self) }
    end
  end
end

When people use Ruport, they use PDF::Writer indirectly through the object we instantiate for them. Because of this, it was easy to use the techniques described in this section. The following code should look similar to our earlier abstract examples:

class Ruport::Formatter::PDF

  # other implementation details omitted.

  def pdf_writer
    @pdf_writer ||= PDF::Writer.new( :paper       => paper_size || "LETTER",
                                     :orientation => paper_orientation || :portrait)
    @pdf_writer.extend(PDFWriterMemoryPatch)
  end
end

This code dynamically fixed an issue for Ruport users without making a global change that might conflict with other patches. Of course, it was no substitute for fixing the issue at its source, which eventually did happen, but it was a good stopgap procedure that made our users happy. When used appropriately, the power to resolve issues in other codebases whether or not you have direct access to the original code can really come in handy.

Here are the key points to remember from this section:

So far, we’ve talked about extending objects others have created, as well as handling dynamic calls to objects we’ve created ourselves. But we can take this a step further by noticing that Class and Module are objects themselves, and as such, can be dynamically generated and molded to our needs.

As we’ve seen, due to the open class system, Ruby object definitions are never really finalized. As a consequence, if you add a method to Object, it becomes available immediately to every object in the system except instances of BasicObject. To put words into code, here’s what that means:

>> a  = "foo"
=> "foo"
>> b = [1,2,3]
=> [1, 2, 3]
>> class C; end
=> nil
>> c = C.new
=> #<C:0x42a400>
>> class Object
>>   def party
>>     "wooohoo!"
>>   end
>> end
=> nil
>> a.party
=> "wooohoo!"
>> b.party
=> "wooohoo!"
>> c.party
=> "wooohoo!"

Now everyone is partying, except BlankSlate. Or more accurately, BlankSlate is being forced to party when it doesn’t want to. The solution is to set up a hook that watches for newly defined methods and hides them:

class Object
  class << self
    alias_method :blank_slate_method_added, :method_added

    # Detect method additions to Object and remove them in the
    # BlankSlate class.
    def method_added(name)
      result = blank_slate_method_added(name)
      return result if self != Object
      BlankSlate.hide(name)
      result
    end

  end
end

This code uses techniques discussed earlier in this chapter to modify the behavior of a core Ruby function, Object.method_added(), while remaining transparent for the ordinary use cases. Classes inherited from Object will not affect BlankSlate, so this code is set to short-circuit in those cases. However, if self happens to be Object, the code tells BlankSlate to hide it and then returns the results of the original method_added() function that has been aliased here.

You’d think that would do the trick, but as it turns out, Object includes the module Kernel. This means we need to track changes over there too, using nearly the same approach:

module Kernel
  class << self
    alias_method :blank_slate_method_added, :method_added

    # Detect method additions to Kernel and remove them in the
    # BlankSlate class.
    def method_added(name)
      result = blank_slate_method_added(name)
      return result if self != Kernel
      BlankSlate.hide(name)
      result
    end
  end
end

There isn’t much new here, so it’s safe to say that if you understood how this worked on Object, you can assume this is just more of the same stuff. However, it does give a hint about another problem: inclusion of modules into Object at runtime.

First, another quick illustration of the issue:

>> module A
>>   def foo
>>     "bar"
>>   end
>> end
=> nil
>> a = Object.new
=> #<Object:0x428ca4>
>> a.extend(A)
=> #<Object:0x428ca4>
>> a.foo
=> "bar"
>> module A
>>   def kittens
>>     "meow"
>>   end
>> end
=> nil
>> a.kittens
=> "meow"

Every module included in an object is like a back door for future expansion. When you first fire up Ruby, the only module you need to worry about is Kernel, but after that, all bets are off. So we end up jumping up one level higher to take care of module inclusion dynamically:

class Module
  alias blankslate_original_append_features append_features
  def append_features(mod)
    result = blankslate_original_append_features(mod)
    return result if mod != Object
    instance_methods.each do |name|
      BlankSlate.hide(name)
    end
    result
  end
end

In this example, mod is the class that was modified by a module inclusion. As in the other hooks, BlankSlate makes an alias of the original, calls it, and simply returns its result if the modified object isn’t Object itself. In the case where a module is mixed into Object, BlankSlate needs to wipe out the instance methods added to its own class definition. After this, it returns the result of the original append_features() call.

This pretty much describes the key aspects of capturing newly added functionality at the top level. You can of course apply these hooks to individual classes lower in the chain and make use of them in other ways.

When you write unit tests via Test::Unit, you typically just subclass Test::Unit::TestCase, which figures out how to find your tests for you. Though we won’t look at the details for how that is actually implemented, we can take a naive shot at it on our own using the Class#inherited hook.

We’re going to implement the code to make this example functional:

class SimpleTest < SimpleTestHarness

  def setup
    puts "Setting up @string"
    @string = "Foo"
  end

  def test_string_must_be_foo
    answer = (@string == "Foo" ? "yes" : "no")
    puts "@string == 'Foo': " << answer
  end

  def test_string_must_be_bar
    answer = (@string == "bar" ? "yes" : "no")
    puts "@string == 'bar': " << answer
  end

end

class AnotherTest < SimpleTestHarness

  def test_another_lame_example
    puts "This got called, isn't that good enough?"
  end

  def helper_method
    puts "But you'll never see this"
  end

  def a_test_method
    puts "Or this"
  end

end

SimpleTestHarness.run

We must first identify each subclass as a test case, and store it in an array until SimpleTestHarness.run is called. Like Test::Unit and other common Ruby testing frameworks, we’ll wipe the slate clean by reinstantiating our tests for each test method, running a setup method if it exists. We will follow the Test::Unit convention and run only the methods whose names begin with test_. We haven’t implemented any assertions or anything like that, because it’s not really the point of this exercise.

The task can easily be broken down into two parts: detecting the subclasses, and later manipulating them. The first part is where we use the inherited hook, as you can see:

class SimpleTestHarness

  class << self

    def inherited(base)
      tests << base
    end

    def tests
      @tests ||= []
    end

  end

end

Surprisingly enough, that was relatively painless. Each time a new subclass is derived from SimpleTestHarness, the inherited() hook is called, passing in the subclass as base. If we just store these in an array at class level, that’s all we need for writing a test runner. Adding in SimpleTestHarness.run, our full class looks like this:

class SimpleTestHarness
  class << self

    def inherited(base)
      tests << base
    end

    def tests
      @tests ||= []
    end

    def run
      tests.each do |t|
        t.instance_methods.grep(/^test_/).each do |m|
          test_case = t.new
          test_case.setup if test_case.respond_to?(:setup)
          test_case.send(m)
        end
      end
    end
  end

end

This code walks over each class in the tests array, and then filters out the names of the instance methods that begin with test_. For each of these methods, it creates a new instance of the test case, calls setup if it exists, and then uses send to dynamically invoke the individual test. With this class definition in place, the original set of tests for which we were trying to implement this functionality can actually run, resulting in the following output:

Setting up @string
@string == 'Foo': yes
Setting up @string
@string == 'bar': no
This got called, isn't that good enough?

Pretty cool, huh? These hooks essentially provide an event system, giving you a way to handle changes to Ruby in a dynamic way. If you’ve ever had to do GUI programming or anything else that involved dynamic callbacks, you already grasp the core ideas behind this concept. The only difference is that rather than capturing a button press, you’re capturing an inheritance event or an added method. When used appropriately, this can be a very powerful technique.

We’re about to wrap things up here, but before we do, it’s worth showing the equivalent of what we just did, but for modules. There happens to be a fairly standard Ruby idiom that takes advantage of that hook, so it’s one you shouldn’t skip over.

You probably already know that if you use include to mix a module into a class, the methods become available at the instance level, and that if you use extend, they become available at the class level. However, an issue comes up when you want to provide both class and instance methods from a single module.

A naive workaround might look like this:

module MyFeatures

  module ClassMethods
    def say_hello
      "Hello"
    end

    def say_goodbye
      "Goodbye"
    end
  end

  def say_hello
    "Hello from #{self}!"
  end

  def say_goodbye
    "Goodbye from #{self}"
  end
end


class A
  include MyFeatures
  extend MyFeatures::ClassMethods
end

If we test this out in irb, we see that it does work:

?> A.say_hello
=> "Hello"
>> obj = A.new
=> #<A:0x1ee628>
>> obj.say_hello
=> "Hello from #<A:0x1ee628>!"
>> obj.say_goodbye
=> "Goodbye from #<A:0x1ee628>"
>> A.say_goodbye
=> "Goodbye"

Having to manually do the extend call seems a bit ugly, though. It’s not terrible when we are writing it ourselves, but it would be a little weird to do this any time you used a third-party module. Of course, that’s where a nice little hook comes in handy. The following code is functionally equivalent to our previous example:

module MyFeatures

  module ClassMethods
    def say_hello
      "Hello"
    end
    
    def say_goodbye
      "Goodbye"
    end
  end
    
  def self.included(base)
    base.extend(ClassMethods)
  end

  def say_hello
    "Hello from #{self}!"
  end

  def say_goodbye
    "Goodbye from #{self}"
  end

end # MyFeatures

class A
  include MyFeatures
end

Here, we were able to get rid of the manual extend call and automate it through the included hook. This hook gets called every time the module is included into a class, and passes the class object as the base object. From here, we simply call extend as before; it is just now wrapped up in the hook rather than manually specified in the class definition. Although this may seem like a small change, having a single entry point to the module’s features is a major win, as it keeps implementation details off the mind as much as possible when simply including the module.

Although we could dig up more and more hooks provided by Ruby, we’ve already covered most of the ones that are used fairly often. There are certainly plenty that we didn’t cover, and you might want to read over the core Ruby documentation a bit to discover some of the more obscure ones if you’re either curious or have an uncommon need.

For the hooks we did cover, here are some things to remember:

And with that, we can wrap up this intense chapter with some closing notes and a final challenge to the adventurous.