middleman--middleman/middleman-core/lib/vendored-middleman-deps/hooks-0.2.0

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