hooks 0.1

data/Gemfile

@@ -0,0 +1,8 @@
+# A sample Gemfile
+source :gemcutter
+
+gem "activesupport", "~>2.3"
+
+group :test do
+  gem "shoulda"
+end

data/Gemfile.lock

@@ -0,0 +1,12 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.9)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3)
+  shoulda

data/README.rdoc

@@ -0,0 +1,87 @@
+= 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 80 lines of code, one method compilation, no +method_missing+ and no magic.
+
+
+== Example
+
+Let's take... a cat.
+
+  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!"
+    end
+    
+    after_dinner :have_a_desert   # => refers to Cat#have_a_desert
+    
+    
+    def have_a_desert
+      puts "Hell, yeah!"
+    end
+ 
+Running the callbacks happens on instances. It will run the block and +#have_a_desert+ from above.
+
+  cat.run_hook :after_dinner
+  # => Ice cream!
+       Hell, yeah!
+
+
+== Options
+
+You're free to pass any number of arguments to #run_callback.
+
+  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
+
+
+== Dependencies
+
+The current gem requires
+
+* active_support 2.3.x
+
+
+== Similar libraries
+
+* http://github.com/nakajima/aspectory/tree/master/lib/aspectory/
+* http://github.com/auser/backcall
+* http://github.com/mmcgrana/simple_callbacks
+
+
+== License
+
+Copyright (c) 2010, Nick Sutterer 
+
+Released under the MIT License.

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the hooks plugin.'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/*_test.rb']
+  test.verbose = true
+end
+
+require 'jeweler'
+$:.unshift File.dirname(__FILE__) # add current dir to LOAD_PATHS
+require 'lib/hooks'
+
+Jeweler::Tasks.new do |spec|
+  spec.name         = "hooks"
+  spec.version      = ::Hooks::VERSION
+  spec.summary      = %{Generic hooks with callbacks for Ruby. }
+  spec.description  = "Declaratively define hooks, add callbacks and run them with the options you like."
+  spec.homepage     = "http://nicksda.apotomo.de/category/hooks"
+  spec.authors      = ["Nick Sutterer"]
+  spec.email        = "apotonick@gmail.com"
+
+  spec.files = FileList["[A-Z]*", File.join(*%w[{lib} ** *]).to_s]
+  
+  spec.add_dependency 'activesupport', '>= 2.3.0'
+end
+
+Jeweler::GemcutterTasks.new

data/lib/hooks.rb

@@ -0,0 +1,67 @@
+require 'active_support/core_ext/class/inheritable_attributes.rb'
+
+# Almost like ActiveSupport::Callbacks but 76,6% less complex.
+#
+# Example:
+#
+#   class CatWidget < Apotomo::Widget
+#     define_hook :after_dinner
+#
+# Now you can add callbacks to your hook declaratively in your class.
+#
+#     after_dinner do puts "Ice cream!" end
+#     after_dinner :have_a_desert   # => refers to CatWidget#have_a_desert
+# 
+# Running the callbacks happens on instances. It will run the block and #have_a_desert from above.
+#
+#   cat.run_hook :after_dinner
+module Hooks
+  VERSION = "0.1"
+  
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  module ClassMethods
+    def define_hook(name)
+      accessor_name = "_#{name}_callbacks"
+      
+      setup_hook_accessors(accessor_name)
+      define_hook_writer(name, accessor_name)
+    end
+    
+    private
+      def define_hook_writer(hook, accessor_name)
+        instance_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+          def #{hook}(method=nil, &block)
+            callback = block_given? ? block : method
+            #{accessor_name} << callback
+          end
+        RUBY_EVAL
+      end
+      
+      def setup_hook_accessors(accessor_name)
+        class_inheritable_array(accessor_name, :instance_writer => false)
+        send("#{accessor_name}=", [])  # initialize ivar.
+      end
+      
+  end
+  
+  # Runs the callbacks (method/block) for the specified hook +name+. Additional arguments will 
+  # be passed to the callback.
+  #
+  # Example:
+  #
+  #   cat.run_hook :after_dinner, "i want ice cream!"
+  #
+  # will invoke the callbacks like
+  # 
+  #   desert("i want ice cream!")
+  #   block.call("i want ice cream!")
+  def run_hook(name, *args)
+    self.class.send("_#{name}_callbacks").each do |callback|
+      send(callback, *args) and next if callback.kind_of? Symbol
+      callback.call(*args) 
+    end
+  end
+end

data/test/hooks_test.rb

@@ -0,0 +1,64 @@
+require 'test_helper'
+
+class HooksTest < ActiveSupport::TestCase
+  context "Hooks.define_hook" do
+    setup do
+      @klass = Class.new(Object) do
+        include Hooks
+        
+        def executed
+          @executed ||= [];
+        end
+      end
+      
+      @mum = @klass.new
+      @mum.class.define_hook :after_eight
+    end
+    
+    should "provide accessors to the stored callbacks" do
+      assert_equal [], @klass._after_eight_callbacks
+      @klass._after_eight_callbacks << :dine
+      assert_equal [:dine], @klass._after_eight_callbacks
+    end
+  
+    context "creates a public writer for the hook that" do
+      should "accepts method names" do
+        @klass.after_eight :dine
+        assert_equal [:dine], @klass._after_eight_callbacks
+      end
+      
+      should "accepts blocks" do
+        @klass.after_eight do true; end
+        assert @klass._after_eight_callbacks.first.kind_of? Proc
+      end
+    end
+    
+    context "Hooks.run_hook"do
+      should "run without parameters" do
+        @mum.instance_eval do
+          def a; executed << :a; end
+          def b; executed << :b; end
+          
+          self.class.after_eight :b
+          self.class.after_eight :a
+        end
+        
+        @mum.run_hook(:after_eight)
+        
+        assert_equal [:b, :a], @mum.executed
+      end
+      
+      should "accept arbitrary parameters" do
+        @mum.instance_eval do
+          def a(me, arg); executed << arg+1; end
+        end
+        @mum.class.after_eight :a
+        @mum.class.after_eight lambda { |me, arg| me.executed << arg-1 }
+        
+        @mum.run_hook(:after_eight, @mum, 1)
+        
+        assert_equal [2, 0], @mum.executed
+      end
+    end  
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+
+# wycats says...
+require 'bundler'
+Bundler.setup
+require 'test/unit'
+require 'shoulda'
+require 'active_support/test_case'
+require 'hooks'
+
+$:.unshift File.dirname(__FILE__) # add current dir to LOAD_PATHS

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: hooks
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Nick Sutterer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-24 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 0
+        version: 2.3.0
+  type: :runtime
+  version_requirements: *id001
+description: Declaratively define hooks, add callbacks and run them with the options you like.
+email: apotonick@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- Gemfile
+- Gemfile.lock
+- README.rdoc
+- Rakefile
+- lib/hooks.rb
+- test/test_helper.rb
+- test/hooks_test.rb
+has_rdoc: true
+homepage: http://nicksda.apotomo.de/category/hooks
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Generic hooks with callbacks for Ruby.
+test_files: 
+- test/test_helper.rb
+- test/hooks_test.rb