event_dispatcher 0.0.2 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d8af04d32455e73210d27f128e787bc377211342
+  data.tar.gz: c380073bd768ca64c093d5faaa06f07c0ff5e1d6
+SHA512:
+  metadata.gz: beda259764f924a76b4b329e329c630496c5521ed32c32b6a8eacc3af38b764a2eae8de03aee7af62d36fc28792752e09808a75a442436a1ee4eedbd905c6937
+  data.tar.gz: 3f235e2205c5ca51a5a140c247fa313bf6f39a1f6fbe90c135b6762c53c2f3877e36a9e5bc6eab111644e52bcc263d7c690bb9f0068c6a48abf4762e290c0502

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+* Massive refactoring of the existing classes to allow more abstraction and breacking code apart into more logical pieces.
+* Using Class `Struct` as Data container for listeners.
+* Commenting all methods for better understanding.
+* Adding more test unit  for maximum quality assurance.
+* Extending documentation.
+
+

data/README.md

@@ -0,0 +1,96 @@
+event_dispatcher
+====================
+
+[![Gem Version](https://badge.fury.io/rb/event_dispatcher.png)](http://badge.fury.io/rb/event_dispatcher)
+
+event_dispatcher gem provides a simple observer implementation, allowing you to subscribe and listen for events in your application with a simple and effective way. 
+
+It is very strongly inspired by the [Symfony EventDispatcher component](http://symfony.com/components/EventDispatcher)
+
+## Install
+Install the gem :
+
+    gem install event_dispatcher
+
+Accessing the gem :
+
+    require 'event_dispatcher'
+
+## Usage
+### Creating an Event
+When an event is dispatched, it's identified by a unique name, which any number of listeners might be listening to. An event instance is also created and passed to all of the listeners : 
+
+    class UserEvent
+       attr_reader :user, :login_time
+       
+       def initialize(user, login_time)
+          @user = user
+          @login_time = login_time
+       end
+     
+       def log
+         "#{login_time} : User #{user} has just logged in."
+       end
+    end
+
+### Creating an EventDispatcher
+The Dispatcher is the commander of the event dispatcher system, it maintains a registry of listeners. It's responsible for notifying listeners when events are dispatched :
+
+    dispatcher = EventDispatcher::Dispatcher.new
+
+### Connecting Listeners
+To take advantage of an existing event, a listener needs to be connected to the dispatcher so that it can be notified when the event is dispatched. There are two ways for attaching a listener to the dispatcher.
+
+Using a block :
+
+    listener = lambda do |event|
+       puts event.log
+    end
+    
+    dispatcher.add_listener(:user_login, listener)
+
+Or using a class instance with a handler method for the event : 
+
+    class UserEventListener
+       def handle(event)
+          puts event.log
+       end
+    end
+   
+    listener = UserEventListener.new     
+    dispatcher.add_listener(:user_login, listener.method(:handle))
+
+You may also specify a priority when subscribing to events. Listeners with higher priority will be run first :
+
+    dispatcher.add_listener(:user_login, listener1, 1) 
+    dispatcher.add_listener(:user_login, listener2, 2) 
+    dispatcher.add_listener(:user_login, listener3, 3) 
+
+
+### Dispatching an Event
+Notifies all listeners of the given event, so the event instance is then passed to each listener :
+
+    event = UserEvent.new('Bobby', Time.now) 
+    dispatcher.dispatch(:user_login, event)
+
+### Stopping Event propagation
+You may wish to stop the propagation of an event to other listeners. To do so you need to first mixing the module Event in your custom event class, then setting the event instance variable `stop_propagation` to true : 	
+
+    class UserEvent
+       include EventDispatcher::Event
+       # ... 
+       # ... 
+    end
+
+    listener = lambda do |event|
+       puts event.log
+       event.stop_propagation = true
+    end
+
+## Tests
+    rake test
+
+## Licence
+LGPL, see LICENCE.
+
+

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.verbose = true
+end
+
+desc "Run event_dispatcher tests"
+task :default => :test

data/lib/event_dispatcher/dispatcher.rb

@@ -1,75 +1,75 @@
 module EventDispatcher
    class Dispatcher
+      attr_reader :listeners
+
       def initialize
          @listeners = {}
-         @sorted = {}
       end
-     
-      def get_listeners( event_name = nil )
-         if event_name
-            sort_listeners!( event_name )  if @sorted[event_name].nil?
 
-            return @sorted[event_name]
-         end   
+      # Checks if the given event has some listeners that want to listen to.
+      def has_listeners?(event_name)
+         event_name = symbolize_key(event_name) 
+         @listeners.key?(event_name) && @listeners[event_name].size > 0  ? true : false
+      end
 
-         @listeners.each_key { |event_name| sort_listeners!( event_name ) if @sorted[event_name].nil?  }
+      # Using Struct as data container for each listener.
+      Listener = Struct.new(:listener, :priority)
 
-         return @sorted
-      end
+      # Connects a listener to the dispatcher so that it can be notified when an event is dispatched.  
+      def add_listener(event_name, listener, priority = 0)
+         raise ArgumentError.new("Priority must be a Fixnum") unless priority.is_a?(Fixnum)
+         event_name = symbolize_key(event_name) 
+         @listeners[event_name] ||= []
+         @listeners[event_name] << Listener.new(listener, priority)
 
-      def has_listeners?( event_name = nil )
-          get_listeners( event_name ).count > 0 ? true : false
+         sort_listeners!(event_name)
       end
-      
-      def add_listener( event_name, listener, priority = 0 )
-         @listeners[event_name] ||= {}
-         @listeners[event_name][priority] ||= [] 
-         @listeners[event_name][priority].push(listener)
 
-         @sorted[event_name].clear unless @sorted[event_name].nil?
-      end
-       
-      def remove_listener( event_name, listener )
-         return if @listeners[event_name].nil?
+      # Removes an event listener from the specified event.
+      def remove_listener!(event_name, listener)
+         event_name = symbolize_key(event_name) 
+         return unless @listeners.key?(event_name) && !listener.nil?
+         @listeners[event_name].delete_if { |l| l.listener.eql?(listener) }
 
-         @listeners[event_name].each_pair do |priority, listeners|
-           listeners.delete_if { |item| p listener == item  }
+         sort_listeners!(event_name)
+      end
+ 
+      # Removes a collection of event listeners attached to a specified event, or reset the entire container of listeners if no event is given. 
+      def remove_listeners!(event_name = nil)
+         if event_name.nil?
+            @listeners.clear
+         else 
+             event_name = symbolize_key(event_name) 
+             @listeners.delete(event_name) if @listeners.key?(event_name)
          end
-
-         @sorted[event_name].clear unless @sorted[event_name].nil?
       end
-    
-      def dispatch( event_name, event = nil )
-         return if @listeners[event_name].nil? || event.nil?
-         
-         do_dispatch( get_listeners( event_name ), event )
-  
+
+      # Notifies all listeners of the given event. The event instance is then passed to each listener of that event.
+      def dispatch(event_name, event)
+         event_name = symbolize_key(event_name) 
+         return unless @listeners.key?(event_name) && !event.nil?
+         @listeners[event_name].each do |l|
+            invoke_callable(l.listener, event)  
+            # A Listener is able to tell the dispatcher to stop all propagation of the event to future listeners.
+            break if event.respond_to?(:stop_propagation) && event.stop_propagation 
+         end
       end
       
       private 
-    
-         def sort_listeners!( event_name )
-            @sorted[event_name] = {} 
-            
-            if @listeners[event_name]
-               @sorted[event_name] = @listeners[event_name].sort
-               
-            end
+         # For better performance we convert each string key into symbol one.
+         def symbolize_key(key)
+            key.to_sym rescue key
          end
-      
-         def do_dispatch( listeners, event )
-            listeners.each do |priority|
-               priority[1].each do |listener|
-                  if listener.is_a?(Hash) 
-                     listener[:object].send( listener[:method], event  )
-                  elsif listener.respond_to?(:call)
-                     listener.call( event )   
-                  else
-                     raise ArgumentError.new("Listener must be a Hash or Block")
-                  end
-                end
-            end
+
+         # Sorts the list of listeners attached to given event by priority. The higher the priority, the earlier the listener is called.
+         def sort_listeners!(event_name)
+            @listeners[event_name].sort_by! { |l| l.priority }
          end
 
+         # Calls the listener instance method which is responsible of handling the event object.        
+         def invoke_callable(callable, event)
+            raise ArgumentError.new("Listener must be a block or a callable object's method") unless callable.respond_to?(:call)
+            callable.call(event)   
+         end
    end
 end

data/lib/event_dispatcher/event.rb

@@ -1,15 +1,9 @@
 module EventDispatcher
    module Event
-      def propagation_stopped
-         @propagation_stopped ||= false
-      end
-
-      def stop_propagation
-         @propagation_stopped = true
-      end
-
-      def propagation_stopped?
-         propagation_stopped
+      attr_accessor :stop_propagation
+      # A listener can prevent any other listeners from being called. 
+      def initialize
+         @stop_propagation = false
       end
    end
 end

data/test/test_dispatcher.rb

@@ -0,0 +1,155 @@
+require 'test/unit'
+require 'event_dispatcher'
+
+
+class DispatcherTest < Test::Unit::TestCase
+   PREFOO = :pre_foo
+   POSTFOO = :post_foo 
+
+   def setup
+      @dispatcher = EventDispatcher::Dispatcher.new
+      @listener = TestEventListener.new
+   end
+
+   def test_initial_state
+      assert_empty @dispatcher.listeners
+
+      assert_equal false, @dispatcher.has_listeners?(PREFOO) 
+      assert_equal false, @dispatcher.has_listeners?(POSTFOO) 
+   end
+ 
+   def test_add_listener
+      @dispatcher.add_listener(:pre_foo, @listener)
+      @dispatcher.add_listener(:post_foo, @listener)
+
+      assert_equal true, @dispatcher.has_listeners?(PREFOO)
+      assert_equal true, @dispatcher.has_listeners?(POSTFOO)
+      assert_equal 1, @dispatcher.listeners[PREFOO].size
+      assert_equal 1, @dispatcher.listeners[PREFOO].size
+      assert_equal 2, @dispatcher.listeners.size
+   end
+   
+   def test_remove_listeners
+      @dispatcher.add_listener(PREFOO, @listener)
+      @dispatcher.add_listener(POSTFOO, @listener)
+      @dispatcher.remove_listeners!(PREFOO)
+
+      assert_equal false, @dispatcher.has_listeners?(PREFOO)
+      assert_equal true, @dispatcher.has_listeners?(POSTFOO)
+      assert_equal 1, @dispatcher.listeners.size
+      
+      @dispatcher.remove_listeners!
+
+      assert_empty @dispatcher.listeners
+   end
+
+   def test_remove_listener!
+      listener1 = TestEventListener.new       
+      listener2 = TestEventListener.new       
+      listener3 = TestEventListener.new 
+
+      @dispatcher.add_listener(:pre_foo, listener1)
+      @dispatcher.add_listener(:pre_foo, listener2)
+      @dispatcher.add_listener(:pre_foo, listener3)
+
+      assert_equal true, @dispatcher.has_listeners?(PREFOO)
+      assert_equal 3, @dispatcher.listeners[PREFOO].size
+
+      @dispatcher.remove_listener!(:pre_foo, listener1) 
+      @dispatcher.remove_listener!(:pre_foo, listener2) 
+
+      assert_equal true, @dispatcher.has_listeners?(PREFOO)
+      assert_equal 1, @dispatcher.listeners.size
+ 
+      @dispatcher.remove_listener!(:not_exists, listener3) 
+
+      assert_equal true, @dispatcher.has_listeners?(PREFOO)
+      assert_equal 1, @dispatcher.listeners.size
+   end
+ 
+   def test_listener_sorts_by_priority
+      listener1 = TestEventListener.new       
+      listener2 = TestEventListener.new       
+      listener3 = TestEventListener.new       
+      listener4 = TestEventListener.new       
+      listener5 = TestEventListener.new       
+
+      @dispatcher.add_listener(:pre_foo, listener1, 0)
+      @dispatcher.add_listener(:pre_foo, listener2, -10)
+      @dispatcher.add_listener(:pre_foo, listener3, 10)
+      @dispatcher.add_listener(:post_foo, listener4)
+      @dispatcher.add_listener(:post_foo, listener5, 10)
+
+      assert_equal [:pre_foo, :post_foo], @dispatcher.listeners.keys 
+      @dispatcher.listeners
+
+      assert_equal true,  @dispatcher.listeners[PREFOO].first.include?(-10)
+      assert_equal true,  @dispatcher.listeners[PREFOO].last.include?(10)
+      assert_equal true,  @dispatcher.listeners[PREFOO][1].include?(0)
+      assert_equal true,  @dispatcher.listeners[POSTFOO].first.include?(0)
+      assert_equal true,  @dispatcher.listeners[POSTFOO].last.include?(10)
+  end
+  
+  def test_dispatcher_for_block
+      invoked = 0
+      foo = '
+'
+      block1 = lambda do |event|
+         invoked += 1
+         foo = event.foo
+      end
+
+      @dispatcher.add_listener(:pre_foo, block1) 
+      test_event = FooEvent.new
+      @dispatcher.dispatch(:pre_foo, test_event) 
+
+      assert_equal 1, invoked
+      assert_equal 'foo', foo
+  end
+   
+  def test_dispatcher_for_class
+      
+      assert_equal 'bar', @listener.bar
+      test_event = FooEvent.new
+      @dispatcher.add_listener(:pre_foo, @listener.method(:handle))
+      @dispatcher.dispatch(:pre_foo, test_event)
+
+      assert_equal 'foo', @listener.bar
+  end
+
+  def test_stop_event_propagation
+      other_listener = TestEventListener.new
+      test_event = FooEvent.new
+      @dispatcher.add_listener(:pre_foo, @listener.method(:handle),10)
+      @dispatcher.add_listener(:pre_foo, other_listener.method(:handle))
+      @dispatcher.dispatch(:pre_foo, test_event)
+
+      assert_equal 'foo', other_listener.bar
+      assert_equal 'bar', @listener.bar
+  end
+   
+end
+
+class TestEventListener
+
+   attr_accessor :bar
+
+   def initialize
+      @bar = 'bar'
+   end
+
+   def handle(event)
+      @bar = event.foo
+      event.stop_propagation = true
+   end
+end
+
+class FooEvent
+   include EventDispatcher::Event
+   attr_accessor :foo
+
+   def initialize
+      @foo = 'foo'
+   end
+end
+

data/test/test_event.rb

@@ -0,0 +1,21 @@
+require 'test/unit'
+require 'event_dispatcher'
+
+class EventTest < Test::Unit::TestCase
+   def setup
+      @event = TestEventClass.new 
+   end
+
+   def test_if_propagation_stopped
+      assert_equal false, @event.stop_propagation
+   end
+
+   def test_stop_propagation_and_if_propagation_stopped
+      @event.stop_propagation = true
+      assert_equal true, @event.stop_propagation
+   end
+end
+
+class TestEventClass
+   include EventDispatcher::Event
+end

metadata

@@ -1,49 +1,56 @@
 --- !ruby/object:Gem::Specification
 name: event_dispatcher
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - Amine Asli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-01 00:00:00.000000000 Z
+date: 2013-12-17 00:00:00.000000000 Z
 dependencies: []
-description: EventDispatcher implements a lightweight version of the Observer design
-  pattern. It's a ruby port of the well known Symfony EventDispatcher
+description: event_dispatcher gem provides a simple observer implementation, allowing
+  you to subscribe and listen for events in your application in a simple and effective
+  way. It is very strongly inspired by the Symfony EventDispatcher component
 email: phobosapp@yahoo.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Rakefile
+- README.md
+- CHANGELOG.md
 - lib/event_dispatcher.rb
-- lib/event_dispatcher/dispatcher.rb
 - lib/event_dispatcher/event.rb
+- lib/event_dispatcher/dispatcher.rb
+- test/test_event.rb
+- test/test_dispatcher.rb
 homepage: https://github.com/ThatAmine/event_dispatcher
 licenses:
 - LGPL
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 2.1.11
 signing_key: 
-specification_version: 3
-summary: EventDispatcher implements a lightweight version of the Observer design pattern.
-test_files: []
+specification_version: 4
+summary: event_dispatcher implements a lightweight version of the Observer design
+  pattern.
+test_files:
+- test/test_event.rb
+- test/test_dispatcher.rb