A word of warning:

This is heavy ruby abuse. It even got the Evil of the Day Award™ from zenspider.

Only works with Ruby 1.8, make sure you have chainable >= 0.4.0.

Thou shalt not use alias_method_chain!¶ ↑

• yehudakatz.com/2009/03/06/alias_method_chain-in-models

• yehudakatz.com/2009/01/18/other-ways-to-wrap-a-method

• www.codefluency.com/articles/2009/01/03/wrapping-a-method-in-ruby

What it does¶ ↑

Chaining Methods¶ ↑

Chainable is an alternative to alias_method_chain, that uses inheritance, rather than aliasing. It does the following when “chaining” a method:

• copy the original method to a new model

• include the model

• overwrite the method

Thus you can use super and keep your method list clean, too! It even supports a (rather dangerous) auto chaining mode, so you do not have to explicitly chain a method, but chain a method whenever it would be overwritten instead.

Example:

class Foo

  def foo
   10
  end

  # now chain to foo
  chain_method :foo do
    super + 3
  end

  # or turn on auto chaining
  auto_chain do

    def bar
      10
    end

    def bar
      super + 1
    end

    def bar
      super ** 2
    end

  end

  # or chain multiple methods at once
  chain_method :foo, :bar do
    super.to_s
  end

end

f = Foo.new
puts f.foo # => 13
puts f.bar # => 121

Of course you can do this with any class (or module):

Array.class_eval do
  chain_method :each
  def each
    return super if block_given? or RUBY_VERSION >= "1.8.7"
    MyStuff::Enumerator.new self, :each
  end
end

Note that there is a speed advantage when using chain_method without a block and doing a “def”, since chain_method will use define_method if a block is given, which produces slower methods.

Merging Methods¶ ↑

But wait, there is more:

class Foo
  def foo
    10
  end
  merge_method :foo do
    super * 3
  end
end

puts Ruby2Ruby.translate Foo, :foo

The output:

def foo
  (10) * 3
end

Before you yell at me about how insane I am, read on!

The library will only allow merging, if it thinks, it is possible:

class Foo
  def foo
    x = 10
  end
  merge_method :foo do
    x = 20
    super
    puts x
  end
end

Will give you:

ArgumentError: cannot merge foo.

Same goes for this one:

class Foo
  def foo x
    puts x
  end
  merge_method :foo do
    super
  end
end

# => ArgumentError: cannot merge foo.

But where is the fun in that one? You probably don’t want your ruby script throwing such errors at you.

Enter “try_merge”:

SomeEvilClassWithoutHooks.class_eval do
  chain_method *instance_methods(false), :try_merge => true do
    old_value = self.value.dup
    super.tap { observer.notify if old_value != value }
  end
  attr_accessor :observer
end

some_evil_instance.observer = MyObserver.new

When to use it?¶ ↑

As with alias_method_chain, you should use this as seldom as possible. Prefer clean inheritance over evil hacks. There actually is only one case one may use chainable (or alias_method_chain, for that matter): If there is a class you need to modify that is not part of your own code and the instances you deal with may already exists when you modify the class. In case you can modify the class before instance creation, just create another class inheriting from the first one and overwrite new to return instances of the latter.

Benchmark¶ ↑

chain_method tends do produce slightly faster methods than alias_method_chain:

$ rake benchmark
                                         user     system      total        real
no wrappers                          0.000000   0.000000   0.000000 (  0.004887)
merge_method                         0.000000   0.000000   0.000000 (  0.004830)
chain_method (def)                   1.040000   0.350000   1.390000 (  1.392329)
chain_method (define_method)         1.150000   0.240000   1.390000 (  1.396007)
alias_method_chain (def)             1.210000   0.260000   1.470000 (  1.472633)
alias_method_chain (define_method)   3.470000   0.590000   4.060000 (  4.096245)

Installation¶ ↑

gem install chainable

Running test¶ ↑

The specs should work with rspec, mspec and bacon.