hooker 1.0.0

data/History.rdoc

@@ -0,0 +1,2 @@
+=== 1.0.0 (2011-2-6)
+* Initial release.

data/Manifest.txt

@@ -0,0 +1,10 @@
+History.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/hooker/base.rb
+lib/hooker.rb
+test/alt_entry.rb
+test/config.rb
+test/setup.rb
+test/test_hooker.rb

data/README.rdoc

@@ -0,0 +1,81 @@
+= Hooker
+
+* http://github.com/dekellum/hooker
+
+== Description
+
+Hooker provides a simple registry of hooks or extension points,
+enabling decoupled run time configuration in terse but straight ruby
+syntax.
+
+Inspiration includes {Emacs Hook
+Functions}[http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html]
+(Lisp) and other applications which support configuration
+files in ruby.
+
+=== Features
+
+* Hook Procs may be added by the configuration source in any order.
+* Hook Procs may be chained and combined via various conventions:
+  Hooker.apply, Hooker.inject, Hooker.merge.
+* Hook Procs are executed only when applied by the extended
+  application. Thus a single configuration source may include hook
+  Procs that are left unused in certain contexts. This is useful
+  when configuring across several different (contextually loaded)
+  modules from one source.
+* Optional or implicit scoping of keys, providing a two level
+  Hook [:scope, :key] hierarchy.
+* Provides an optional logging extension point Hooker.log_with
+* Can check and list hooks that were not applied, including the call
+  site of where added.
+
+== Synopsis
+
+Lets say an application has a 'Job' it would like to support
+hooks on:
+
+ job = Hooker.apply( :job, Job.new )
+
+Then the following configuration of the job could optionally be loaded
+and applied to override Job defaults:
+
+ Hooker.with do |h|
+   h.setup_job do |j|
+     j.workers = 3
+     j.timeout = 10 * 60 #seconds
+   end
+ end
+
+Hooker can be yielded to the config file via an alternative Module
+name, so as not to scare your mom, or to fully encapsulate its use:
+
+ class Chaplain
+   def self.configure( &block )
+     Hooker.with( :church, &block )
+   end
+ end
+
+Supports the config:
+
+ Chaplain.configure do |c|
+   c.setup_job do |j|
+     j.workers = 3
+     j.timeout = 10 * 60 #seconds
+   end
+ end
+
+== License
+
+Copyright (c) 2011 David Kellum
+
+Licensed under the Apache License, Version 2.0 (the "License"); you
+may not use this file except in compliance with the License.  You
+may obtain a copy of the License at:
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied.  See the License for the specific language governing
+permissions and limitations under the License.

data/Rakefile

@@ -0,0 +1,32 @@
+# -*- ruby -*-
+
+$LOAD_PATH << './lib'
+
+require 'rubygems'
+gem     'rjack-tarpit', '~> 1.3.0'
+require 'rjack-tarpit'
+
+require 'hooker/base'
+
+t = RJack::TarPit.new( 'hooker', Hooker::VERSION )
+
+t.specify do |h|
+  h.developer( 'David Kellum', 'dek-oss@gravitext.com' )
+  h.testlib = :minitest
+  h.extra_dev_deps += [ [ 'minitest', '>= 1.7.1', '< 2.1' ] ]
+end
+
+# Version/date consistency checks:
+
+task :check_history_version do
+  t.test_line_match( 'History.rdoc', /^==/, / #{ t.version } / )
+end
+task :check_history_date do
+  t.test_line_match( 'History.rdoc', /^==/, /\([0-9\-]+\)$/ )
+end
+
+task :gem  => [ :check_history_version  ]
+task :tag  => [ :check_history_version, :check_history_date ]
+task :push => [ :check_history_version, :check_history_date ]
+
+t.define_tasks

data/lib/hooker/base.rb

@@ -0,0 +1,20 @@
+#--
+# Copyright (c) 2011 David Kellum
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+#++
+
+module Hooker
+  # Hooker version
+  VERSION = '1.0.0'
+end

data/lib/hooker.rb

@@ -0,0 +1,149 @@
+#--
+# Copyright (c) 2011 David Kellum
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+#++
+
+require 'hooker/base'
+
+# A registry of hooks, added and applied for indirect configuration
+# support.
+module Hooker
+
+  class << self
+
+    # Yields self under the given scope to block.
+    def with( scp = :default )
+      prior, @scope = @scope, scp
+      yield self
+    ensure
+      @scope = prior
+    end
+
+    # Add hook block by specified hook key. Will only be executed when
+    # apply, inject, or merge is later called with the same key.
+    # Multiple hook blocks for the same key will be called in the
+    # order added.
+    def add( key, clr = nil, &block )
+      applied.delete( sk( key ) )
+      hooks[ sk( key ) ] << [ block, ( clr || caller.first ).to_s ]
+    end
+
+    # Allow method setup_<foo> as alias for add( :foo )
+    def method_missing( method, *args, &block )
+      if method.to_s =~ /^setup_(.*)$/ && args.empty?
+        add( $1.to_sym, caller.first, &block )
+      else
+        super
+      end
+    end
+
+    # Pass the specified initial value to each previously added Proc
+    # with matching key and returns the mutated value.
+    def apply( key, value )
+      applied << sk( key )
+      hooks[ sk( key ) ].each { |hook| hook[0].call( value ) }
+      value
+    end
+
+    # Inject value (or nil) into the chain of previously added Procs,
+    # which should implement binary operations, returning desired
+    # value. Returns the last value from the last proc.
+    def inject( key, value = nil )
+      applied << sk( key )
+      hooks[ sk( key ) ].inject( value ) { |v, hook| hook[0].call( v ) }
+    end
+
+    # Merge returned values from each added Proc to the initial value
+    # (or empty Hash).
+    def merge( key, value = {} )
+      applied << sk( key )
+      hooks[ sk( key ) ].inject( value ) { |v, hook| v.merge( hook[0].call ) }
+    end
+
+    # Register to yield log messages to the given block.
+    def log_with( &block )
+      @logger = block
+    end
+
+    # Load the specified file via Kernel.load, with a log message if
+    # set.
+    def load_file( file )
+      log "Loading file #{file}."
+      load( file, true ) #wrap in in anonymous module
+    end
+
+    # Register -c/--config flags on given OptionParser to load_file
+    def register_config( opts )
+      opts.on( "-c", "--config FILE", "Load configuration file" ) do |file|
+        load_file( file )
+      end
+    end
+
+    # Log results of check_not_applied, one message per not applied
+    # hook.
+    def log_not_applied
+      check_not_applied do |rkey, calls|
+        k = rkey.map { |s| s.inspect }.compact.join( ', ' )
+        msg = "Hook #{k} was never applied. Added from:\n"
+        calls.each { |cl| msg += "  - #{cl}\n" }
+        log msg
+      end
+    end
+
+    # Yields [ [ scope, key ], [ caller, ... ] ] to block for each
+    # hook key added but not applied.  Often this suggests a typo or
+    # other mistake by the hook Proc author.
+    def check_not_applied
+      ( hooks.keys - applied ).each do |rkey|
+        calls = hooks[ rkey ].map { |blk, clr| clr }
+        yield( rkey, calls )
+      end
+    end
+
+    private
+
+    # Hash of hook keys to array of procs.
+    def hooks
+      @hooks ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # List of hook keys that were applied thus far
+    def applied
+      @applied ||= []
+    end
+
+    # Clears all Hooker state.
+    def clear
+      @hooks = nil
+      @applied = nil
+      @logger = nil
+    end
+
+    def log( msg )
+      @logger.call( msg ) if @logger
+    end
+
+    def sk( key )
+      if key.is_a?( Array ) && ( key.length == 2 )
+        key
+      else
+        [ @scope, key ]
+      end
+    end
+
+  end
+
+  @scope = :default
+
+end

data/test/alt_entry.rb

@@ -0,0 +1,5 @@
+Chaplain.configure do |h|
+  h.setup_test do
+    :returned
+  end
+end

data/test/config.rb

@@ -0,0 +1,5 @@
+Hooker.with do |h|
+  h.setup_test do
+    :returned
+  end
+end

data/test/setup.rb

@@ -0,0 +1,24 @@
+#--
+# Copyright (c) 2011 David Kellum
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You
+# may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+#++
+
+#### General test setup: LOAD_PATH, logging, console output ####
+
+ldir = File.join( File.dirname( __FILE__ ), "..", "lib" )
+$LOAD_PATH.unshift( ldir ) unless $LOAD_PATH.include?( ldir )
+
+require 'rubygems'
+require 'minitest/unit'
+require 'minitest/autorun'

data/test/test_hooker.rb

@@ -0,0 +1,144 @@
+#!/usr/bin/env jruby
+#.hashdot.profile += jruby-shortlived
+#--
+# Copyright (c) 2011 David Kellum
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You
+# may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+#++
+
+TESTDIR = File.dirname( __FILE__ )
+
+require File.join( TESTDIR, "setup" )
+
+require 'hooker'
+
+# An alternative entry point from top level
+class Chaplain
+  def self.configure( &block )
+    Hooker.with( :church, &block )
+  end
+end
+
+class TestContext < MiniTest::Unit::TestCase
+
+  def setup
+    Hooker.log_with { |msg| puts; puts msg }
+  end
+
+  def teardown
+    Hooker.send( :clear ) #private
+  end
+
+  def test_not_set
+    assert_nil( Hooker.inject( :test_hook ) )
+
+    assert_equal( :identity, Hooker.inject( :test_hook, :identity ) )
+  end
+
+  def test_no_arg_hook
+    Hooker.add( :test ) { :returned }
+
+    assert_equal( :returned, Hooker.inject( :test ) )
+    assert_equal( :returned, Hooker.inject( :test, :ignored ) )
+  end
+
+  def test_chained_hook
+    Hooker.with do |h|
+      h.add( :test ) { |l| l << :a }
+      h.add( :test ) { |l| l << :b }
+    end
+
+    assert_equal( [ :a, :b ], Hooker.inject( :test, [] ) )
+  end
+
+  def test_setup_method
+    Hooker.setup_test { :returned } # via method_missing
+    assert_equal( :returned, Hooker.inject( :test ) )
+  end
+
+  def test_not_setup_missing
+    assert_raises( NoMethodError ) do
+      Hooker.bogus_method
+    end
+  end
+
+  def test_apply
+    Hooker.with do |h|
+      h.add( :test ) { |h| h[ :prop ] = "a" }
+      h.add( :test ) { |h| h[ :prop ] = "b" }
+    end
+
+    h = Hooker.apply( :test, { :prop => "orig" } )
+
+    assert_equal( "b", h[ :prop ] )
+  end
+
+  def test_merge
+    Hooker.add( :test ) { { :a => 1, :b => 2                   } }
+    Hooker.add( :test ) { {                   :c => 3          } }
+
+    h = Hooker.merge( :test,
+                          { :a => 0,                   :d => 4 } )
+    assert_equal( h,      { :a => 1, :b => 2, :c => 3, :d => 4 } )
+  end
+
+  def test_check_not_applied
+
+    Hooker.with( :test_scope ) do |h|
+      h.add( :used )     { :returned }
+      h.add( :not_used ) { flunk "first time" }
+      h.add( :not_used ) { flunk "once more"  }
+    end
+
+    assert_equal( :returned,
+                  Hooker.inject( [ :test_scope, :used ] ) )
+
+    not_used_keys = []
+    not_used_calls = []
+    Hooker.check_not_applied do |rkey, calls|
+      not_used_keys << rkey
+      not_used_calls += calls
+    end
+
+    assert_equal( [ [ :test_scope, :not_used ] ], not_used_keys )
+    assert_equal( 2, not_used_calls.length )
+
+    Hooker.log_not_applied
+  end
+
+  def test_check_not_applied_if_added_after
+
+    Hooker.with( :test_scope ) do |h|
+      assert_nil( h.inject( :not_used ) )
+      h.add( :not_used ) { :returned }
+
+      not_used_keys = []
+      not_used_keys = Hooker.check_not_applied do |rkey, calls|
+        not_used_keys << rkey
+      end
+      assert_equal( [ [:test_scope, :not_used] ], not_used_keys )
+    end
+
+  end
+
+  def test_load
+    Hooker.load_file( File.join( TESTDIR, 'config.rb' ) )
+    assert_equal( :returned, Hooker.inject( :test ) )
+  end
+
+  def test_load_with_alt_entry
+    Hooker.load_file( File.join( TESTDIR, 'alt_entry.rb' ) )
+    assert_equal( :returned, Hooker.inject( [ :church, :test ] ) )
+  end
+
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification 
+name: hooker
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+    - 1
+    - 0
+    - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+  - David Kellum
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-06 00:00:00 -08:00
+default_executable: 
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: minitest
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 1
+              - 7
+              - 1
+            version: 1.7.1
+        - - <
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 2
+              - 1
+            version: "2.1"
+    type: :development
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: rjack-tarpit
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ~>
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 1
+              - 3
+              - 0
+            version: 1.3.0
+    type: :development
+    version_requirements: *id002
+description: |-
+  Hooker provides a simple registry of hooks or extension points,
+  enabling decoupled run time configuration in terse but straight ruby
+  syntax.
+  
+  Inspiration includes {Emacs Hook
+  Functions}[http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html]
+  (Lisp) and other applications which support configuration
+  files in ruby.
+email: 
+  - dek-oss@gravitext.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+  - Manifest.txt
+  - History.rdoc
+  - README.rdoc
+files: 
+  - History.rdoc
+  - Manifest.txt
+  - README.rdoc
+  - Rakefile
+  - lib/hooker/base.rb
+  - lib/hooker.rb
+  - test/alt_entry.rb
+  - test/config.rb
+  - test/setup.rb
+  - test/test_hooker.rb
+has_rdoc: true
+homepage: http://github.com/dekellum/hooker
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+  - --main
+  - README.rdoc
+require_paths: 
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
+requirements: []
+
+rubyforge_project: hooker
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Hooker provides a simple registry of hooks or extension points, enabling decoupled run time configuration in terse but straight ruby syntax
+test_files: 
+  - test/test_hooker.rb