= Hooks
<em>Generic hooks with callbacks for Ruby.</em>
== Introduction
_Hooks_ lets you define hooks declaratively in your ruby class. You can add callbacks to your hook, which will be run as soon as _you_ run the hook!
It's almost like ActiveSupport::Callbacks but 76,6% less complex. Instead, it is not more than 60 lines of code, one method compilation, no +method_missing+ and no magic.
Also, you may pass additional arguments to your callbacks when invoking a hook.
== Example
Let's take... a cat.
require 'hooks'
class Cat
include Hooks
define_hook :after_dinner
Now you can add callbacks to your hook declaratively in your class.
after_dinner do
puts "Ice cream for #{self}!"
end
after_dinner :have_a_desert # => refers to Cat#have_a_desert
def have_a_desert
puts "Hell, yeah!"
end
This will run the block and <tt>#have_a_desert</tt> from above.
cat.run_hook :after_dinner
# => Ice cream for #<Cat:0x8df9d84>!
Hell, yeah!
Callback blocks and methods will be executed with instance context. Note how +self+ in the block refers to the Cat instance.
== Inheritance
Hooks are inherited, here's a complete example to put it all together.
class Garfield < Cat
after_dinner :want_some_more
def want_some_more
puts "Is that all?"
end
end
Garfield.new.run_hook :after_dinner
# => Ice cream for #<Cat:0x8df9d84>!
Hell, yeah!
Is that all?
Note how the callbacks are invoked in the order they were inherited.
== Options for Callbacks
You're free to pass any number of arguments to #run_callback, those will be passed to the callbacks.
cat.run_hook :before_dinner, cat, Time.now
The callbacks should be ready for receiving parameters.
before_dinner :wash_pawns
before_dinner do |who, when|
...
end
def wash_pawns(who, when)
Not sure why a cat should have ice cream for dinner. Beside that, I was tempted naming this gem _hooker_.
== Installation
gem install hooks
== Anybody using it?
* Hooks is already used in [Apotomo:http://github.com/apotonick/apotomo], a hot widget framework for Rails. Look at +lib/apotomo/widget.rb+ for examples and into +lib/apotomo/tree_node.rb+ to learn how modules-driven code might benefit from hooks.
== Similar libraries
* http://github.com/nakajima/aspectory
* http://github.com/auser/backcall
* http://github.com/mmcgrana/simple_callbacks
== License
Copyright (c) 2010, Nick Sutterer
Released under the MIT License.
