has-guarded-handlers 1.2.0 → 1.3.0

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # [develop](https://github.com/adhearsion/has-guarded-handlers)
 
+# [1.3.0](https://github.com/adhearsion/has-guarded-handlers/compare/v1.2.0...v1.3.0) - [2012-07-03](https://rubygems.org/gems/has-guarded-handlers/versions/1.3.0)
+  * Feature: It is now possible to register a handler to process all events
+  * Bugfix: Temporary handlers were being removed after the first event even if their guards didn't match
+  * Bugfix: Fix for a syntax error on Ruby 1.8
+
 # [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

data/README.md

@@ -11,23 +11,148 @@ require 'has_guarded_handlers'
 
 class A
   include HasGuardedHandlers
-
-  def receive_event(event)
-    trigger_handler :event, event
-  end
 end
 
 a = A.new
-a.register_handler :event, :type => :foo do
-  puts "Handled the event"
+a.register_handler :event, :type => :foo do |event|
+  puts "Handled the event of type #{event.type} with value #{event.value}"
 end
 
-class Event
-  attr_accessor :type
-end
+Event = Class.new Struct.new(:type, :value)
+
+a.trigger_handler :event, Event.new(:foo, 'bar')
+```
+
+Register a handler for a particular named channel:
+
+```ruby
+a.register_handler(:event) { ... }
+# or
+a.register_handler(:event, :type => :foo) { ... }
+
+a.trigger_handler :event, :foo
+```
+
+Register a global handler for all channels:
+
+```ruby
+a.register_handler { ... }
+# or
+a.register_handler(nil, :type => :foo) { ... }
+
+a.trigger_handler :event, :foo
+```
+
+Register a temporary handler, which is deleted once triggered:
+
+```ruby
+a.register_tmp_handler(:event) { ... } # This will only fire once
+a.trigger_handler :event, :foo
+```
+
+Handlers are triggered in order of priority, followed by order of declaration. By default, all handlers are registered with priority 0, and are thus executed in the order declared:
+
+```ruby
+a.register_handler { ... } # This is triggered first
+a.register_handler { ... } # This is triggered second
+...
+
+a.trigger_handler :event, :foo
+```
+
+You may specify a handler priority in order to change this order. Higher priority is executed first:
+
+```ruby
+a.register_handler(:event) { ... } # This is triggered second
+a.register_handler_with_priority(:event, 10) { ... } # This is triggered first
+...
+
+a.trigger_handler :event, :foo
+```
+
+You may specify a priority for a temporary handler:
+
+```ruby
+a.register_handler_with_options(:event, {:tmp => true, :priority => 10}, :foo => :bar) { ... }
+```
+
+### Handler chaining
+
+When multiple handlers match the event, the return value of each handler will determine if the handler chain continues. A truthy return value will cause the handler to swallow the event and halt the handler chain. A falsy return value will continue the chain.
+
+It is possible to explicitly pass to the next handler by throwing `:pass` in your handler:
+
+```ruby
+a.register_handler(:event) { throw :pass }
+a.register_handler(:event) { ... } # This will be executed
+
+a.trigger_handler :event, :foo
+```
+
+or indeed explicitly halt the handler chain by throwing `:halt` in the handler:
+
+```ruby
+a.register_handler(:event) { throw :halt }
+a.register_handler(:event) { ... } # This will not be executed
+
+a.trigger_handler :event, :foo
+```
+
+### What are guards?
+
+Guards are a concept borrowed from Erlang. They help to better compartmentalise handlers.
+
+There are a number of guard types and one bit of special syntax. Guards act like AND statements. Each condition must be met if the handler is to be used.
+
+```ruby
+# Equivalent to saying (stanza.chat? && stanza.body)
+message :chat?, :body
+```
+
+The different types of guards are:
+
+```ruby
+# Class / Module
+#   Checks that the event is of the type specified
+#   Equivalent to event.is_a? Foo
+register_handler Foo
+
+# Symbol
+#   Checks for a non-false reply to calling the symbol on the event
+#   Equivalent to event.chat?
+register_handler :chat?
+
+# Hash with any value (:body => 'exit')
+#   Calls the key on the event and checks for equality
+#   Equivalent to event.body == 'exit'
+register_handler :body => 'exit'
+
+# Hash with regular expression (:body => /exit/)
+#   Calls the key on the event and checks for a match
+#   Equivalent to event.body.match /exit/
+register_handler :body => /exit/
+
+# Hash with array value (:name => [:gone, :forbidden])
+#   Calls the key on the event and check for inclusion in the array
+#   Equivalent to [:gone, :forbidden].include?(event.name)
+register_handler :name => [:gone, :fobidden]
+
+# Hash with array key ([:[], :name] => :gone)
+#   Calls the first element of the key on the event, passing the other elements as arguments
+#   and checks the value matches
+#   Equivalent to event[:name] == :gone
+register_handler [:[], :name] => :gone
+
+# Proc
+#   Calls the proc passing in the event
+#   Checks that the ID is modulo 3
+register_handler proc { |m| m.id % 3 == 0 }
 
-event = Event.new.tap { |e| e.type = :foo }
-a.receive_event event
+# Array
+#   Use arrays with the previous types effectively turns the guard into
+#   an OR statement.
+#   Equivalent to event.body == 'foo' || event.body == 'baz'
+register_handler [{:body => 'foo'}, {:body => 'baz'}]
 ```
 
 ## Links:
@@ -46,4 +171,4 @@ a.receive_event event
 
 ## Copyright
 
-Copyright (c) 2011 Ben Langfeld, Jeff Smick. MIT licence (see LICENSE for details).
+Copyright (c) 2011 Ben Langfeld, Jeff Smick. MIT licence (see LICENSE.md for details).

data/lib/has_guarded_handlers/version.rb

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

data/lib/has_guarded_handlers.rb

@@ -4,44 +4,44 @@ require 'uuid'
 module HasGuardedHandlers
   # Register a handler
   #
-  # @param [Symbol, nil] type a classification to separate handlers/events into channels
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels. Omitting the classification will create a handler for all events.
   # @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(type, *guards, &handler)
+  def register_handler(type = nil, *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 [Symbol, nil] type a classification to separate handlers/events into channels Omitting the classification will create a handler for all events.
   # @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)
+  def register_tmp_handler(type = nil, *guards, &handler)
     register_handler_with_options type, {:tmp => true}, *guards, &handler
   end
 
   # Register a handler with a specified priority
   #
-  # @param [Symbol, nil] type a classification to separate handlers/events into channels
+  # @param [Symbol, nil] type a classification to separate handlers/events into channels Omitting the classification will create a handler for all events.
   # @param [Integer] priority the priority of the handler. Higher priority executes first
   # @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_priority(type, priority, *guards, &handler)
+  def register_handler_with_priority(type = nil, priority = 0, *guards, &handler)
     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 [Symbol, nil] type a classification to separate handlers/events into channels Omitting the classification will create a handler for all events.
   # @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)
@@ -50,7 +50,7 @@ module HasGuardedHandlers
   # @yield [Object] trigger_object the incoming event
   #
   # @return [String] handler ID for later manipulation
-  def register_handler_with_options(type, options, *guards, &handler)
+  def register_handler_with_options(type = nil, options = {}, *guards, &handler)
     check_guards guards
     options[:priority] ||= 0
     new_handler_id.tap do |handler_id|
@@ -70,7 +70,7 @@ 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)
+  def clear_handlers(type = nil, *guards)
     delete_handler_if(type) { |g, _| g == guards }
   end
 
@@ -82,8 +82,8 @@ module HasGuardedHandlers
     return unless handler = handlers_of_type(type)
     catch :halt do
       handler.find do |guards, handler, tmp|
-        catch(:pass) { call_handler handler, guards, event }
-        delete_handler_if(type) { |_, h, _| h.equal? handler } if tmp
+        val = catch(:pass) { call_handler handler, guards, event }
+        delete_handler_if(type) { |_, h, _| h.equal? handler } if tmp && val
       end
     end
   end
@@ -102,6 +102,10 @@ module HasGuardedHandlers
     hash.keys.sort.reverse.each do |key|
       values += hash[key]
     end
+    global_handlers = guarded_handlers[nil]
+    global_handlers.keys.sort.reverse.each do |key|
+      values += global_handlers[key]
+    end
     values
   end
 

data/spec/has_guarded_handlers_spec.rb

@@ -17,10 +17,23 @@ describe HasGuardedHandlers do
     subject.trigger_handler :event, event
   end
 
+  it 'can register a handler for all events, regardless of category' do
+    response.expects(:call).twice.with(event)
+    subject.register_handler { |e| response.call e }
+    subject.trigger_handler :event, event
+    subject.trigger_handler :bah, 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
+    event.expects(:foo).once.returns :bar
+
+    nomatch_event = mock 'Event(nomatch)'
+    nomatch_event.expects(:foo).once.returns :baz
+
+    subject.register_tmp_handler(:event, :foo => :bar) { |e| response.call e }
+
+    subject.trigger_handler :event, nomatch_event
     subject.trigger_handler :event, event
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has-guarded-handlers
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-28 00:00:00.000000000 Z
+date: 2012-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uuid
-  requirement: &2152452540 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152452540
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2152452020 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +38,15 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *2152452020
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2152451500 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +54,15 @@ dependencies:
         version: 2.5.0
   type: :development
   prerelease: false
-  version_requirements: *2152451500
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.5.0
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2152451020 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +70,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152451020
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ci_reporter
-  requirement: &2164285360 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +86,15 @@ dependencies:
         version: 1.6.3
   type: :development
   prerelease: false
-  version_requirements: *2164285360
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.3
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &2164284000 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +102,15 @@ dependencies:
         version: 0.7.0
   type: :development
   prerelease: false
-  version_requirements: *2164284000
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2164282100 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,10 +118,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2164282100
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2164281140 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -99,7 +134,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2164281140
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Allow an object's API to provide flexible handler registration, storage
   and matching to arbitrary events.
 email:
@@ -134,15 +174,21 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -3018957415088485817
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -3018957415088485817
 requirements: []
 rubyforge_project: has-guarded-handlers
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A library for associating a set of event handlers, complete with guards,
@@ -150,4 +196,3 @@ 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: