has-guarded-handlers 1.1.0 → 1.2.0

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode # currently in active development, may or may not work for your project
+  - ruby-head
+notifications:
+  irc: "irc.freenode.org#adhearsion"

data/CHANGELOG.md

@@ -1,9 +1,13 @@
-# develop
+# [develop](https://github.com/adhearsion/has-guarded-handlers)
 
-# 1.1.0 - 2012-01-21
+# [1.2.0](https://github.com/adhearsion/has-guarded-handlers/compare/v1.1.0...v1.2.0) - [2012-03-28](https://rubygems.org/gems/has-guarded-handlers/versions/1.2.0)
+  * Feature: Allow registering temporary (single execution) handlers which are removed after they are triggered
+  * Feature: Registering a handler returns an ID by which it may be unregistered
+
+# [1.1.0](https://github.com/adhearsion/has-guarded-handlers/compare/v1.0.0...v1.1.0) - [2012-01-21](https://rubygems.org/gems/has-guarded-handlers/versions/1.1.0)
   * Feature: Allow guarding on the value of method calls with arguments, by using an array as a hash key
 
-# 1.0.0 - 2012-01-19
+# [1.0.0](https://github.com/adhearsion/has-guarded-handlers/compare/v0.0.1...v1.0.0) - [2012-01-19](https://rubygems.org/gems/has-guarded-handlers/versions/1.0.0)
   * Bump to 1.0.0 because the API is stable
   * Feature: Allow guarding with a module to test if an object has a mixin
 

data/has-guarded-handlers.gemspec

@@ -18,11 +18,13 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency 'bundler', ["~> 1.0.0"]
+  s.add_dependency 'uuid'
+
+  s.add_development_dependency 'bundler', ["~> 1.0"]
   s.add_development_dependency 'rspec', [">= 2.5.0"]
   s.add_development_dependency 'mocha', [">= 0"]
   s.add_development_dependency 'ci_reporter', [">= 1.6.3"]
-  s.add_development_dependency 'yard', ["~> 0.7.0"]
+  s.add_development_dependency 'yard', [">= 0.7.0"]
   s.add_development_dependency 'rake', [">= 0"]
   s.add_development_dependency 'guard-rspec'
 end

data/lib/has_guarded_handlers.rb

@@ -1,27 +1,69 @@
 require "has_guarded_handlers/version"
+require 'uuid'
 
 module HasGuardedHandlers
   # Register a handler
   #
-  # @param [Symbol, nil] type set the filter on a specific handler
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels
   # @param [guards] guards take a look at the guards documentation
-  # @yield [Object] stanza the incoming event
+  #
+  # @yield [Object] trigger_object the incoming event
+  #
+  # @return [String] handler ID for later manipulation
   def register_handler(type, *guards, &handler)
-    register_handler_with_priority type, 0, *guards, &handler
+    register_handler_with_options type, {}, *guards, &handler
+  end
+
+  # Register a temporary handler. Once triggered, the handler will be de-registered
+  #
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels
+  # @param [guards] guards take a look at the guards documentation
+  #
+  # @yield [Object] trigger_object the incoming event
+  #
+  # @return [String] handler ID for later manipulation
+  def register_tmp_handler(type, *guards, &handler)
+    register_handler_with_options type, {:tmp => true}, *guards, &handler
   end
 
   # Register a handler with a specified priority
   #
-  # @param [Symbol, nil] type set the filter on a specific handler
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels
   # @param [Integer] priority the priority of the handler. Higher priority executes first
   # @param [guards] guards take a look at the guards documentation
-  # @yield [Object] stanza the incoming event
+  #
+  # @yield [Object] trigger_object the incoming event
+  #
+  # @return [String] handler ID for later manipulation
   def register_handler_with_priority(type, priority, *guards, &handler)
-    initialize_guarded_handlers
+    register_handler_with_options type, {:priority => priority}, *guards, &handler
+  end
+
+  # Register a handler with a specified set of options
+  #
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels
+  # @param [Hash] options the options for the handler
+  # @option options [Integer] :priority (0) the priority of the handler. Higher priority executes first
+  # @option options [true, false] :tmp (false) Wether or not the handler should be considered temporary (single execution)
+  # @param [guards] guards take a look at the guards documentation
+  #
+  # @yield [Object] trigger_object the incoming event
+  #
+  # @return [String] handler ID for later manipulation
+  def register_handler_with_options(type, options, *guards, &handler)
     check_guards guards
-    @handlers[type] ||= {}
-    @handlers[type][priority] ||= []
-    @handlers[type][priority] << [guards, handler]
+    options[:priority] ||= 0
+    new_handler_id.tap do |handler_id|
+      guarded_handlers[type][options[:priority]] << [guards, handler, options[:tmp], handler_id]
+    end
+  end
+
+  # Unregister a handler by ID
+  #
+  # @param [Symbol] type the handler classification used at registration
+  # @param [String] handler_id the handler ID returned by registration
+  def unregister_handler(type, handler_id)
+    delete_handler_if(type) { |_, _, _, id| id == handler_id }
   end
 
   # Clear handlers with given guards
@@ -29,26 +71,33 @@ module HasGuardedHandlers
   # @param [Symbol, nil] type remove filters for a specific handler
   # @param [guards] guards take a look at the guards documentation
   def clear_handlers(type, *guards)
-    initialize_guarded_handlers
-    @handlers[type].each_pair do |priority, handlers|
-      handlers.delete_if { |g, _| g == guards }
-    end
+    delete_handler_if(type) { |g, _| g == guards }
   end
 
+  # Trigger a handler classification with an event object
+  #
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels
+  # @param [Object] the event object to yield to the handler block
   def trigger_handler(type, event)
-    initialize_guarded_handlers
     return unless handler = handlers_of_type(type)
     catch :halt do
-      handler.find do |guards, handler|
+      handler.find do |guards, handler, tmp|
         catch(:pass) { call_handler handler, guards, event }
+        delete_handler_if(type) { |_, h, _| h.equal? handler } if tmp
       end
     end
   end
 
   private
 
-  def handlers_of_type(type)
-    return unless hash = @handlers[type]
+  def delete_handler_if(type, &block) # :nodoc:
+    guarded_handlers[type].each_pair do |priority, handlers|
+      handlers.delete_if(&block)
+    end
+  end
+
+  def handlers_of_type(type) # :nodoc:
+    return unless hash = guarded_handlers[type]
     values = []
     hash.keys.sort.reverse.each do |key|
       values += hash[key]
@@ -56,16 +105,20 @@ module HasGuardedHandlers
     values
   end
 
-  def call_handler(handler, guards, event)
+  def call_handler(handler, guards, event) # :nodoc:
     handler.call event unless guarded?(guards, event)
   end
 
+  def new_handler_id # :nodoc:
+    UUID.new.generate.to_s
+  end
+
   # If any of the guards returns FALSE this returns true
   # the logic is reversed to allow short circuiting
   # (why would anyone want to loop over more values than necessary?)
   #
   # @private
-  def guarded?(guards, event)
+  def guarded?(guards, event) # :nodoc:
     guards.find do |guard|
       case guard
       when Class, Module
@@ -94,7 +147,7 @@ module HasGuardedHandlers
     end
   end
 
-  def check_guards(guards)
+  def check_guards(guards) # :nodoc:
     guards.each do |guard|
       case guard
       when Array
@@ -107,7 +160,7 @@ module HasGuardedHandlers
     end
   end
 
-  def initialize_guarded_handlers
-    @handlers ||= {}
+  def guarded_handlers # :nodoc:
+    @handlers ||= Hash.new { |h, k| h[k] = Hash.new { |h, k| h[k] = [] } }
   end
 end

data/lib/has_guarded_handlers/version.rb

@@ -1,3 +1,3 @@
 module HasGuardedHandlers
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/has_guarded_handlers_spec.rb

@@ -1,7 +1,11 @@
 require 'spec_helper'
 
-describe TestObject do
-  it { should be_a TestObject }
+describe HasGuardedHandlers do
+  subject do
+    Object.new.tap do |o|
+      o.extend HasGuardedHandlers
+    end
+  end
 
   let(:event) { mock 'Event' }
   let(:response) { mock 'Response' }
@@ -13,6 +17,21 @@ describe TestObject do
     subject.trigger_handler :event, event
   end
 
+  it 'can register a one-shot (tmp) handler' do
+    response.expects(:call).once.with(event)
+    subject.register_tmp_handler(:event) { |e| response.call e }
+    subject.trigger_handler :event, event
+    subject.trigger_handler :event, event
+  end
+
+  it 'can unregister a handler after registration' do
+    response.expects(:call).once.with(event)
+    subject.register_handler(:event) { |e| response.call e }
+    id = subject.register_handler(:event) { |e| response.call :foo }
+    subject.unregister_handler :event, id
+    subject.trigger_handler :event, event
+  end
+
   it 'does not fail when no handlers are set' do
     lambda do
       subject.trigger_handler :event, event

data/spec/spec_helper.rb

@@ -9,7 +9,3 @@ RSpec.configure do |config|
   config.filter_run :focus => true
   config.run_all_when_everything_filtered = true
 end
-
-class TestObject
-  include HasGuardedHandlers
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has-guarded-handlers
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,22 +10,33 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-21 00:00:00.000000000 Z
+date: 2012-03-28 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: uuid
+  requirement: &2152452540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152452540
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2152688380 !ruby/object:Gem::Requirement
+  requirement: &2152452020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *2152688380
+  version_requirements: *2152452020
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2152687820 !ruby/object:Gem::Requirement
+  requirement: &2152451500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +44,10 @@ dependencies:
         version: 2.5.0
   type: :development
   prerelease: false
-  version_requirements: *2152687820
+  version_requirements: *2152451500
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2152687260 !ruby/object:Gem::Requirement
+  requirement: &2152451020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152687260
+  version_requirements: *2152451020
 - !ruby/object:Gem::Dependency
   name: ci_reporter
-  requirement: &2152683040 !ruby/object:Gem::Requirement
+  requirement: &2164285360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,21 +66,21 @@ dependencies:
         version: 1.6.3
   type: :development
   prerelease: false
-  version_requirements: *2152683040
+  version_requirements: *2164285360
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &2152682360 !ruby/object:Gem::Requirement
+  requirement: &2164284000 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.7.0
   type: :development
   prerelease: false
-  version_requirements: *2152682360
+  version_requirements: *2164284000
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2152681860 !ruby/object:Gem::Requirement
+  requirement: &2164282100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +88,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152681860
+  version_requirements: *2164282100
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2152681480 !ruby/object:Gem::Requirement
+  requirement: &2164281140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,7 +99,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152681480
+  version_requirements: *2164281140
 description: Allow an object's API to provide flexible handler registration, storage
   and matching to arbitrary events.
 email:
@@ -99,6 +110,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .travis.yml
 - CHANGELOG.md
 - Gemfile
 - Guardfile
@@ -122,18 +134,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2115013965424304008
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2115013965424304008
 requirements: []
 rubyforge_project: has-guarded-handlers
 rubygems_version: 1.8.10
@@ -144,3 +150,4 @@ summary: A library for associating a set of event handlers, complete with guards
 test_files:
 - spec/has_guarded_handlers_spec.rb
 - spec/spec_helper.rb
+has_rdoc: