hookr 1.0.1 → 1.1.0

data/History.txt

@@ -1,3 +1,8 @@
+== 1.1.0 / 2010-09-13
+
+* 1 minor ehancement
+  * Better support for defining hooks in singleton classes and modules
+
 == 1.0.1 / 2008-12-03
 
 * 1 bug fix

data/Rakefile

@@ -1,30 +1,32 @@
-# Look in the tasks/setup.rb file for the various options that can be
-# configured in this Rakefile. The .rake files in the tasks directory
-# are where the options are used.
+gem 'bones', '~> 3.0'
 
 begin
   require 'bones'
-  Bones.setup
 rescue LoadError
-  load 'tasks/setup.rb'
+  abort '### Please install the "bones" gem ###'
 end
 
-ensure_in_path 'lib'
-require 'hookr'
-
 task :default => 'spec:run'
+task 'gem:release' => 'spec:run'
+
+Bones {
+  name    'hookr'
+  authors 'Avdi Grimm'
+  email   'avdi@avdi.org'
+  url     'http://hookr.rubyforge.org'
+
+  summary "A callback hooks framework for Ruby."
 
-PROJ.name = 'hookr'
-PROJ.authors = 'Avdi Grimm'
-PROJ.email = 'avdi@avdi.org'
-PROJ.url = 'http://hookr.rubyforge.org'
-PROJ.version = HookR::VERSION
-PROJ.rubyforge.name = 'hookr'
+  # ann.email[:from]     = 'avdi@avdi.org'
+  # ann.email[:to]       = 'ruby-talk@ruby-lang.org'
+  # ann.email[:server]   = 'smtp.gmail.com'
+  # ann.email[:domain]   = 'avdi.org'
+  # ann.email[:port]     = 587
+  # ann.email[:acct]     = 'avdi.grimm'
+  # ann.email[:authtype] = :plain
 
-# TODO I want to be able to use -w here, but RSpec produces a hojillion warnings
-PROJ.ruby_opts = []
-PROJ.spec.opts << '--color'
+  depend_on 'fail-fast', '1.0.0'
+}
 
-depend_on 'fail-fast', '1.0.0'
 
 # EOF

data/TODO

@@ -0,0 +1,94 @@
+# -*- mode: org -*-
+* DONE Add Hook#each_callback and refactor execution to use it.
+  CLOSED: [2008-12-02 Tue 11:51]
+* DONE Add ability to clear callbacks from hooks.
+  CLOSED: [2008-12-02 Tue 12:09]
+* DONE Add ability to disconnect hooks from their parents
+  CLOSED: [2008-12-02 Tue 12:09]
+  Copy each_callback to a new null-parented set.
+* DONE Make #hooks and #callbacks read-only
+  CLOSED: [2008-12-02 Tue 11:51]
+  Replace writable access with #fetch_or_create_*
+* DONE Add Listener API
+  CLOSED: [2008-12-01 Mon 17:04]
+  A Listener is an object attached to a wildcard calback.  Every event that
+  passes through the callback is sent to the listener as a method call
+  corresponding to the hook name.
+* DONE Add an (easy) way to remove listeners
+  CLOSED: [2008-12-02 Tue 11:51]
+* TODO (Maybe) Verify that recursive handlers call either skip, next, or cancel.
+* TODO Add #skip and #cancel methods to Event.
+* TODO Consider using Roxy for #hooks and #callbacks extensions.
+  http://ryandaigle.com/articles/2008/11/10/implement-ruby-proxy-objects-with-roxy
+* TODO Standard, extensable method for deriving handles from objects
+  Driver: we need to be able to remove a listener using the the listener object
+  as an index.
+* TODO Reconsider fetch_or_create_* methods - they are kinda ugly.
+* TODO More Hook parent/child unification
+  Most Hook methods should behave as if the hook contained all of its parent's
+  callbacks as well.  Specifically:
+  - It should not be possible to add a callback with the same handle as an
+    existing parent callback
+  - #callbacks should probably return a unified set of all callbacks
+
+* TODO Collect return values when running hooks iteratively
+* TODO Rewrite iterative model in terms of recursive
+  This will make some of the other TODOs possible/more feasible.
+
+  May want to push the execution models out into separate Event classes,
+  e.g. IterativeEvent and RecursiveEvent.  An IterativeEvent could apply itself
+  to a callback generator in such a way that it collected return values into an
+  array.
+
+* TODO Write example "error strategy filter"
+  A possible implementation for turning exceptions into benign values:
+
+  Wrap callback execution in a begin...rescue block.  If an exception is raised,
+  catch it, and wrap it in a new exception which inludes a reference to the
+  callback stack.  An exception filter further up the chain can:
+   
+  1. Catch the wrapped exception
+  2. Create a Failure object which references the exception
+  3. Replace the top element of the callback stack with a stub that just returns
+     the Failure object.
+  4. Retry the exception.
+     
+* TODO Syntax sugar for before_ and after_ filters
+:  class ZeroWing
+:    define_hook :we_get_signal
+:
+:    before_we_get_signal :foo
+:    after_we_get_signal  :bar
+:  end
+* TODO Syntax sugar for execute_hook
+  E.g.:
+
+  : execute_we_get_signal(arg1, arg2)
+  : run_we_get_signal(arg1, arg2)
+  
+* TODO Interleave wildcard callback execution based definition order
+  Instead of running all wildcards first or last.
+
+  One possible approach is to combine wildcards and specific callbacks into a
+  single set before executing.  This would require reworking how we generate
+  indices, if nothing else.  Indices would have to be unique across the whole
+  class.
+
+  Another approach: when adding a wildcard callback, first add it individually
+  to every existing hook.  Then add it to a class-wide "wildcard list".  When a
+  new hook is defined, add all the wildcards in the wildcard list to it.
+
+  A side-effect of the second approach is that it would be possible to remove
+  wildcard callbacks from individual instances/hooks using remove_callback().
+  This may be a feature.
+* TODO Make it possible to add a Listener at the class level
+  Both internally and externally to the class
+* TODO Make callback macros accept listeners
+* TODO Add ability for listeners to see event object
+  Currently only the event arguments are passed.
+
+  May want to make the core Listener API a single #notify(event) call, and then
+  have SomeClass::Listener add the demultiplexing code.
+* TODO Split up into multiple files
+* TODO No methods flog higher than 15
+* TODO 95% code coverage

data/lib/hookr.rb

@@ -10,7 +10,7 @@ module HookR
   # No need to document the boilerplate convenience methods defined by Mr. Bones.
   # :stopdoc:
 
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
 
@@ -96,6 +96,13 @@ module HookR
         end
       end
 
+      def extended(object)
+        super(object)
+        class << object
+          include ::HookR::Hooks
+        end
+      end
+
       protected
 
       def make_hook(name, parent, params)
@@ -181,7 +188,7 @@ module HookR
 
     # returns the hooks exposed by this object
     def hooks
-      fetch_or_create_hooks.dup.freeze
+      fetch_or_create_hooks.dup
     end
 
     # Execute all callbacks associated with the hook identified by +hook_name+,
@@ -272,7 +279,22 @@ module HookR
     end
 
     def fetch_or_create_hooks
-      @hooks ||= self.class.hooks.deep_copy
+      @hooks ||= inherited_hooks.deep_copy
+    end
+
+    def inherited_hooks
+      singleton_class_hooks | class_hooks
+    end
+
+    def singleton_class_hooks
+      (class << self; self; end).hooks
+    end
+
+    def class_hooks
+      self.class.ancestors.inject(HookSet.new) { |hooks, a|
+        a_hooks = a.respond_to?(:hooks) ? a.hooks : HookSet.new
+        hooks | a_hooks
+      }
     end
   end
 
@@ -316,7 +338,7 @@ module HookR
     end
 
     def callbacks
-      fetch_or_create_callbacks.dup.freeze
+      fetch_or_create_callbacks.dup
     end
 
     # Add a callback which will be executed in the context where it was defined

data/spec/hookr_spec.rb

@@ -201,6 +201,39 @@ describe HookR::Hooks do
       end
     end
   end
+
+  context "included in a singleton class" do
+    before :each do
+      @object = Object.new
+      @class = (class << @object; self; end)
+      @class.module_eval do
+        include HookR::Hooks
+
+        define_hook :foo, :x, :y
+      end
+    end
+
+    specify "the singleton object should be able to list its hooks" do
+      @object.hooks.size.should be > 0
+    end
+  end
+
+  context "defined in a module and then added to an object" do
+    before :each do
+      @object = Object.new
+      @module = Module.new do
+        include HookR::Hooks
+
+        define_hook :foo, :x, :y
+      end
+      @object.extend(@module)
+    end
+
+    specify "the singleton object should be able to list its hooks" do
+      pending "FIXME"
+      @object.hooks.size.should be > 1
+    end
+  end
 end
 
 describe "a no-param hook named :on_signal" do
@@ -250,7 +283,7 @@ describe "a no-param hook named :on_signal" do
     end
 
     specify "there should be two callbacks total" do
-      @instance_hook.total_callbacks.should == 2
+      @instance_hook.total_callbacks.should be == 2
     end
 
   end
@@ -276,19 +309,19 @@ describe "a no-param hook named :on_signal" do
     end
 
     specify ":callback1 should be the first callback" do
-      @class_hook.callbacks[0].handle.should == :callback1
+      @class_hook.callbacks[0].handle.should be == :callback1
     end
 
     specify ":callback2 should be the second callback" do
-      @class_hook.callbacks[1].handle.should == :callback2
+      @class_hook.callbacks[1].handle.should be == :callback2
     end
 
     specify ":callback1 should execute the given code" do
-      @class_hook.callbacks[:callback1].call(@event).should == 2
+      @class_hook.callbacks[:callback1].call(@event).should be == 2
     end
 
     specify ":callback2 should execute the given code" do
-      @class_hook.callbacks[:callback2].call(@event).should == 4
+      @class_hook.callbacks[:callback2].call(@event).should be == 4
     end
   end
 end
@@ -322,9 +355,9 @@ describe "a two-param hook named :on_signal" do
     it "should call back with the correct arguments" do
       @sensor.should_receive(:ping) do |event, color, flavor|
         event.source.should equal(@instance)
-        event.name.should == :on_signal
-        color.should == :purple
-        flavor.should == :grape
+        event.name.should be == :on_signal
+        color.should be == :purple
+        flavor.should be == :grape
       end
       @instance.send(:execute_hook, :on_signal, :purple, :grape)
     end
@@ -403,7 +436,7 @@ describe "a two-param hook named :on_signal" do
     end
 
     specify "the callback handle should be :do_stuff" do
-      @callback.handle.should == :do_stuff
+      @callback.handle.should be == :do_stuff
     end
   end
 
@@ -439,10 +472,10 @@ describe "a two-param hook named :on_signal" do
 
     specify "the callback should call back" do
       @sensor.should_receive(:ping) do |event, arg1, arg2|
-        event.source.should == @instance
-        event.name.should == :on_signal
-        arg1.should == :apple
-        arg2.should == :orange
+        event.source.should be == @instance
+        event.name.should be == :on_signal
+        arg1.should be == :apple
+        arg2.should be == :orange
       end
       @instance.send(:execute_hook, :on_signal, :apple, :orange)
     end
@@ -518,7 +551,7 @@ describe "a two-param hook named :on_signal" do
         log(:inner, arg1, arg2)
       end
 
-      @log.should == [
+      @log.should be == [
        [:cb3_before, :on_signal, :fizz, :buzz],
        [:cb2_before, :on_signal, :fizz, :buzz],
        [:cb1_before, :on_signal, :pish, :tosh],
@@ -573,20 +606,20 @@ describe HookR::Hook do
       @block = lambda {}
     end
 
-    specify { @it.name.should == :foo }
+    specify { @it.name.should be == :foo }
 
     specify { @it.should have(0).callbacks }
 
     it "should be equal to any other hook named :foo" do
       @parent = HookR::Hook.new(:parent)
       @other = HookR::Hook.new(:foo, @parent)
-      @it.should == @other
+      @it.should be == @other
       @it.should eql(@other)
     end
 
     describe "when adding a callback" do
       it "should return the handle of the added callback" do
-        @it.add_callback(@callback).should == 123
+        @it.add_callback(@callback).should be == 123
       end
     end
 
@@ -620,16 +653,16 @@ describe HookR::Hook do
       specify { @it.should have(5).callbacks }
 
       specify "the handles of the anonymous callbacks should be their indexes" do
-        @it.callbacks[0].handle.should == 0
-        @it.callbacks[2].handle.should == 2
+        @it.callbacks[0].handle.should be == 0
+        @it.callbacks[2].handle.should be == 2
       end
 
       specify "the add methods should return handles" do
-        @anon_external_cb.should == 0
-        @named_external_cb.should == :my_external
-        @anon_internal_cb.should == 2
-        @named_internal_cb.should == :my_internal
-        @method_cb.should == :my_method
+        @anon_external_cb.should be == 0
+        @named_external_cb.should be == :my_external
+        @anon_internal_cb.should be == 2
+        @named_internal_cb.should be == :my_internal
+        @method_cb.should be == :my_method
       end
 
       specify "the callbacks should have the intended types" do
@@ -655,7 +688,7 @@ describe HookR::Hook do
         @it.each_callback do |callback|
           callbacks << callback.handle
         end
-        callbacks.should == [@anon_external_cb, @named_external_cb,
+        callbacks.should be == [@anon_external_cb, @named_external_cb,
           @anon_internal_cb, @named_internal_cb, @method_cb]
       end
 
@@ -664,7 +697,7 @@ describe HookR::Hook do
         @it.each_callback_reverse do |callback|
           callbacks << callback.handle
         end
-        callbacks.should == [@method_cb, @named_internal_cb, @anon_internal_cb,
+        callbacks.should be == [@method_cb, @named_internal_cb, @anon_internal_cb,
           @named_external_cb, @anon_external_cb]
       end
 
@@ -716,7 +749,7 @@ describe HookR::Hook do
     end
 
     it "should report 2 total callbacks" do
-      @it.total_callbacks.should == 2
+      @it.total_callbacks.should be == 2
     end
 
     it "should be able to iterate over own and parent callbacks" do
@@ -724,7 +757,7 @@ describe HookR::Hook do
       @it.each_callback do |callback|
         callbacks << callback
       end
-      callbacks.should == [@parent_callback, @child_callback]
+      callbacks.should be == [@parent_callback, @child_callback]
     end
 
     it "should be able to reverse-iterate over own and parent callbacks" do
@@ -732,7 +765,7 @@ describe HookR::Hook do
       @it.each_callback_reverse do |callback|
         callbacks << callback
       end
-      callbacks.should == [@child_callback, @parent_callback]
+      callbacks.should be == [@child_callback, @parent_callback]
     end
 
     it "should be able to clear its own callbacks, leaving parent callbacks" do
@@ -742,7 +775,7 @@ describe HookR::Hook do
       @it.each_callback do |callback|
         callbacks << callback
       end
-      callbacks.should == [@parent_callback]
+      callbacks.should be == [@parent_callback]
     end
 
     it "should be able to clear all callbacks" do
@@ -752,7 +785,7 @@ describe HookR::Hook do
       @it.each_callback do |callback|
         callbacks << callback
       end
-      callbacks.should == []
+      callbacks.should be == []
     end
 
     it "should leave parent callbacks alone when clearing all" do
@@ -804,7 +837,7 @@ describe HookR::CallbackSet do
     end
 
     it "should sort the callbacks" do
-      @it.to_a.should == [@cb1, @cb2, @cb3]
+      @it.to_a.should be == [@cb1, @cb2, @cb3]
     end
 
     it "should be able to locate callbacks by index" do