middleman-core-x86-mingw32

= Hooks

Generic hooks with callbacks for Ruby.

== 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 #have_a_desert 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.