Module: HookR::Hooks

Defined in:

lib/hookr.rb

Overview

Include this module to decorate your class with hookable goodness.

Note: remember to call super() if you define your own self.inherited().

Defined Under Namespace

Modules: CallbackHelpers, ClassMethods

Class Method Summary

• .included(other) ⇒ Object

  end of CallbackHelpers.

Instance Method Summary

• #add_listener(listener, handle = listener_to_handle(listener)) ⇒ Object

  Add a listener object.

• #execute_hook(hook_name, *args, &block) ⇒ Object

  Execute all callbacks associated with the hook identified by hook_name, plus any wildcard callbacks.

• #hooks ⇒ Object

  returns the hooks exposed by this object.

• #remove_listener(handle_or_listener) ⇒ Object

  Remove a listener by handle or by the listener object itself.

Class Method Details

.included(other) ⇒ Object

end of CallbackHelpers

# File 'lib/hookr.rb', line 189

def self.included(other)
  other.extend(ClassMethods)
  other.extend(CallbackHelpers)
  other.send(:include, CallbackHelpers)
  other.send(:define_hook, :__wildcard__)
end

Instance Method Details

#add_listener(listener, handle = listener_to_handle(listener)) ⇒ Object

Add a listener object. The object should have a method defined for every hook this object publishes.

# File 'lib/hookr.rb', line 237

def add_listener(listener, handle=listener_to_handle(listener))
  add_wildcard_callback(handle) do |event|
    listener.send(event.name, *event.arguments)
  end
end

#execute_hook(hook_name, *args, &block) ⇒ Object

Execute all callbacks associated with the hook identified by hook_name, plus any wildcard callbacks.

When a block is supplied, this method functions differently. In that case the callbacks are executed recursively. The most recently defined callback is executed and passed an event and a set of arguments. Calling event.next will pass execution to the next most recently added callback, which again will be passed an event with a reference to the next callback, and so on. When the list of callbacks are exhausted, the block is executed as if it too were a callback. If at any point event.next is passed arguments, they will replace the value of the callback arguments for callbacks further down the chain.

In this way you can use callbacks as “around” advice to a block of code. For instance:

execute_hook(:write_data, data) do |data|
  write(data)
end

Here, the code exposes a :write_data hook. Any callbacks attached to the hook will “wrap” the data writing event. Callbacks might log when the data writing operation was started and stopped, or they might encrypt the data before it is written, etc.

# File 'lib/hookr.rb', line 225

def execute_hook(hook_name, *args, &block)
  event = Event.new(self, hook_name, args, !!block)

  if block
    execute_hook_recursively(hook_name, event, block)
  else
    execute_hook_iteratively(hook_name, event)
  end
end

#hooks ⇒ Object

returns the hooks exposed by this object

# File 'lib/hookr.rb', line 197

def hooks
  fetch_or_create_hooks.dup
end

#remove_listener(handle_or_listener) ⇒ Object

Remove a listener by handle or by the listener object itself

# File 'lib/hookr.rb', line 244

def remove_listener(handle_or_listener)
  handle = case handle_or_listener
           when Symbol then handle_or_listener
           else listener_to_handle(handle_or_listener)
           end
  remove_wildcard_callback(handle)
end