108 lines
2.5 KiB
Text
108 lines
2.5 KiB
Text
|
= 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.
|