tilia-event 2.0.2

data/lib/tilia/event/event_emitter_trait.rb

@@ -0,0 +1,169 @@
+module Tilia
+  module Event
+    # Event Emitter Trait
+    #
+    # This trait contains all the basic functions to implement an
+    # EventEmitterInterface.
+    #
+    # Using the trait + interface allows you to add EventEmitter capabilities
+    # without having to change your base-class.
+    module EventEmitterTrait
+      # The list of listeners
+      #
+      # @return [Hash]
+      attr_accessor :listeners
+
+      # Subscribe to an event.
+      #
+      # @param [String] event_name
+      # @param [Proc, Method] call_back
+      # @param [Fixnum] priority
+      # @return [void]
+      def on(event_name, call_back, priority = 100)
+        @listeners[event_name] ||= [false, [], []]
+
+        @listeners[event_name][0] = @listeners[event_name][1].size == 0
+        @listeners[event_name][1] << priority
+        @listeners[event_name][2] << call_back
+      end
+
+      # Subscribe to an event exactly once.
+      #
+      # @param [String] event_name
+      # @param [Proc, Method] call_back
+      # @param [Fixnum] priority
+      # @return [void]
+      def once(event_name, call_back, priority = 100)
+        wrapper = nil
+        wrapper = lambda do |*arguments|
+          remove_listener(event_name, wrapper)
+          call_back.call(*arguments)
+        end
+
+        on(event_name, wrapper, priority)
+      end
+
+      # Emits an event.
+      #
+      # This method will return true if 0 or more listeners were succesfully
+      # handled. false is returned if one of the events broke the event chain.
+      #
+      # If the continueCallBack is specified, this callback will be called every
+      # time before the next event handler is called.
+      #
+      # If the continueCallback returns false, event propagation stops. This
+      # allows you to use the eventEmitter as a means for listeners to implement
+      # functionality in your application, and break the event loop as soon as
+      # some condition is fulfilled.
+      #
+      # Note that returning false from an event subscriber breaks propagation
+      # and returns false, but if the continue-callback stops propagation, this
+      # is still considered a 'successful' operation and returns true.
+      #
+      # Lastly, if there are 5 event handlers for an event. The continueCallback
+      # will be called at most 4 times.
+      #
+      # @param [String] event_name
+      # @param [Array] arguments
+      # @param [Proc, method] continue_call_back
+      # @return [Boolean]
+      def emit(event_name, arguments = [], continue_call_back = nil)
+        if !continue_call_back.is_a?(Proc)
+
+          listeners(event_name).each do |listener|
+            result = listener.call(*arguments)
+            return false if result == false
+          end
+        else
+          my_listeners = listeners(event_name)
+          counter = my_listeners.size
+
+          my_listeners.each do |listener|
+            counter -= 1
+            result = listener.call(*arguments)
+
+            return false if result == false
+
+            break if counter > 0 && !continue_call_back.call
+          end
+        end
+
+        true
+      end
+
+      # Returns the list of listeners for an event.
+      #
+      # The list is returned as an array, and the list of events are sorted by
+      # their priority.
+      #
+      # @param [String] event_name
+      # @return [Array<Proc, Method>]
+      def listeners(event_name)
+        return [] unless @listeners.key? event_name
+
+        # The list is not sorted
+        unless @listeners[event_name][0]
+          # Sorting
+          # array_multisort with ruby
+          joined = (0...@listeners[event_name][1].size).map do |i|
+            [@listeners[event_name][1][i], @listeners[event_name][2][i]]
+          end
+          sorted = joined.sort do |a, b|
+            a[0] <=> b[0]
+          end
+          sorted.each_with_index do |data, i|
+            @listeners[event_name][1][i] = data[0]
+            @listeners[event_name][2][i] = data[1]
+          end
+
+          # Marking the listeners as sorted
+          @listeners[event_name][0] = true
+        end
+
+        @listeners[event_name][2]
+      end
+
+      # Removes a specific listener from an event.
+      #
+      # If the listener could not be found, this method will return false. If it
+      # was removed it will return true.
+      #
+      # @param [String] event_name
+      # @param [Proc, Method] listener
+      # @return [Boolean]
+      def remove_listener(event_name, listener)
+        return false unless @listeners.key?(event_name)
+
+        @listeners[event_name][2].each_with_index do |check, index|
+          next unless check == listener
+
+          @listeners[event_name][1].delete_at(index)
+          @listeners[event_name][2].delete_at(index)
+          return true
+        end
+        false
+      end
+
+      # Removes all listeners.
+      #
+      # If the eventName argument is specified, all listeners for that event are
+      # removed. If it is not specified, every listener for every event is
+      # removed.
+      #
+      # @param [String] event_name
+      # @return [void]
+      def remove_all_listeners(event_name = nil)
+        if !event_name.nil?
+          @listeners.delete(event_name)
+        else
+          @listeners = {}
+        end
+      end
+
+      # TODO: document
+      def initialize_event_emitter_trait
+        @listeners = {}
+      end
+    end
+  end
+end

data/lib/tilia/event/promise.rb

@@ -0,0 +1,196 @@
+module Tilia
+  module Event
+    # An implementation of the Promise pattern.
+    #
+    # Promises basically allow you to avoid what is commonly called 'callback
+    # hell'. It allows for easily chaining of asynchronous operations.
+    class Promise
+      # Pending promise. No result yet.
+      PENDING = 0
+
+      # The promise has been fulfilled. It was successful.
+      FULFILLED = 1
+
+      # The promise was rejected. The operation failed.
+      REJECTED = 2
+
+      protected
+
+      # The current state of this promise.
+      #
+      # @return [Fixnum]
+      attr_accessor :state
+
+      # A list of subscribers. Subscribers are the callbacks that want us to let
+      # them know if the callback was fulfilled or rejected.
+      #
+      # @return [Array]
+      attr_accessor :subscribers
+
+      # The result of the promise.
+      #
+      # If the promise was fulfilled, this will be the result value. If the
+      # promise was rejected, this is most commonly an exception.
+      attr_accessor :value
+
+      public
+
+      # Creates the promise.
+      #
+      # The passed argument is the executor. The executor is automatically
+      # called with two arguments.
+      #
+      # Each are callbacks that map to self.fulfill and self.reject.
+      # Using the executor is optional.
+      #
+      # @param [Proc, Method] executor
+      # @return [void]
+      def initialize(executor = nil)
+        @state = PENDING
+        @subscribers = []
+        @value = nil
+
+        executor.call(method(:fulfill), method(:reject)) if executor
+      end
+
+      # This method allows you to specify the callback that will be called after
+      # the promise has been fulfilled or rejected.
+      #
+      # Both arguments are optional.
+      #
+      # This method returns a new promise, which can be used for chaining.
+      # If either the onFulfilled or onRejected callback is called, you may
+      # return a result from this callback.
+      #
+      # If the result of this callback is yet another promise, the result of
+      # _that_ promise will be used to set the result of the returned promise.
+      #
+      # If either of the callbacks return any other value, the returned promise
+      # is automatically fulfilled with that value.
+      #
+      # If either of the callbacks throw an exception, the returned promise will
+      # be rejected and the exception will be passed back.
+      #
+      # @param [Proc, Method] on_fulfilled
+      # @param [Proc, Method] on_rejected
+      # @return [Promise]
+      def then(on_fulfilled = nil, on_rejected = nil)
+        sub_promise = self.class.new
+        case @state
+        when PENDING
+          @subscribers << [sub_promise, on_fulfilled, on_rejected]
+        when FULFILLED
+          invoke_callback(sub_promise, on_fulfilled)
+        when REJECTED
+          invoke_callback(sub_promise, on_rejected)
+        end
+        sub_promise
+      end
+
+      # Add a callback for when this promise is rejected.
+      #
+      # I would have used the word 'catch', but it's a reserved word in PHP, so
+      # we're not allowed to call our function that.
+      #
+      # @param [Proc, Method] on_rejected
+      # @return [Promise]
+      def error(on_rejected)
+        self.then(nil, on_rejected)
+      end
+
+      # Marks this promise as fulfilled and sets its return value.
+      #
+      # @param value
+      # @return [void]
+      def fulfill(value = nil)
+        unless @state == PENDING
+          fail PromiseAlreadyResolvedException, 'This promise is already resolved, and you\'re not allowed to resolve a promise more than once'
+        end
+        @state = FULFILLED
+        @value = value
+        @subscribers.each do |subscriber|
+          invoke_callback(subscriber[0], subscriber[1])
+        end
+      end
+
+      # Marks this promise as rejected, and set it's rejection reason.
+      #
+      # @param reason
+      # @return [void]
+      def reject(reason = nil)
+        unless @state == PENDING
+          fail PromiseAlreadyResolvedException, 'This promise is already resolved, and you\'re not allowed to resolve a promise more than once'
+        end
+        @state = REJECTED
+        @value = reason
+        @subscribers.each do |subscriber|
+          invoke_callback(subscriber[0], subscriber[2])
+        end
+      end
+
+      # It's possible to send an array of promises to the all method. This
+      # method returns a promise that will be fulfilled, only if all the passed
+      # promises are fulfilled.
+      #
+      # @param [Array<Promise>] promises
+      # @return [Promise]
+      def self.all(promises)
+        new(
+          lambda do |success, failing|
+            success_count = 0
+            complete_result = []
+
+            promises.each_with_index do |sub_promise, promise_index|
+              sub_promise.then(
+                lambda do |result|
+                  complete_result[promise_index] = result
+                  success_count += 1
+
+                  success.call(complete_result) if success_count == promises.size
+
+                  return result
+                end
+              ).error(
+                lambda do |reason|
+                  failing.call(reason)
+                end
+              )
+            end
+          end
+        )
+      end
+
+      protected
+
+      # This method is used to call either an onFulfilled or onRejected callback.
+      #
+      # This method makes sure that the result of these callbacks are handled
+      # correctly, and any chained promises are also correctly fulfilled or
+      # rejected.
+      #
+      # @param [Promise] sub_promise
+      # @param [Proc, Method] call_back
+      # @return [void]
+      def invoke_callback(sub_promise, call_back = nil)
+        if call_back.is_a?(Proc) || call_back.is_a?(Method)
+          begin
+            result = call_back.call(@value)
+            if result.is_a?(self.class)
+              result.then(sub_promise.method(:fulfill), sub_promise.method(:reject))
+            else
+              sub_promise.fulfill(result)
+            end
+          rescue => e
+            sub_promise.reject(e.to_s)
+          end
+        else
+          if @state == FULFILLED
+            sub_promise.fulfill(@value)
+          else
+            sub_promise.reject(@value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tilia/event/promise_already_resolved_exception.rb

@@ -0,0 +1,8 @@
+module Tilia
+  module Event
+    # This exception is thrown when the user tried to reject or fulfill a promise,
+    # after either of these actions were already performed.
+    class PromiseAlreadyResolvedException < RuntimeError
+    end
+  end
+end

data/lib/tilia/event/version.rb

@@ -0,0 +1,9 @@
+module Tilia
+  module Event
+    # This class contains the version number for this package.
+    class Version
+      # Full version number
+      VERSION = '2.0.2'
+    end
+  end
+end

data/test/continue_callback_test.rb

@@ -0,0 +1,89 @@
+require 'test_helper'
+
+module Tilia
+  module Event
+    class ContinueCallbackTest < Minitest::Test
+      def test_continue_call_back
+        ee = EventEmitter.new
+
+        handler_counter = 0
+        bla = lambda do
+          handler_counter += 1
+        end
+
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+
+        continue_counter = 0
+        r = ee.emit(
+          'foo',
+          [],
+          lambda do
+            continue_counter += 1
+            true
+          end
+        )
+
+        assert(r)
+        assert_equal(3, handler_counter)
+        assert_equal(2, continue_counter)
+      end
+
+      def test_continue_call_back_break
+        ee = EventEmitter.new
+
+        handler_counter = 0
+        bla = lambda do
+          handler_counter += 1
+        end
+
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+
+        continue_counter = 0
+        r = ee.emit(
+          'foo',
+          [],
+          lambda do
+            continue_counter += 1
+            false
+          end
+        )
+
+        assert(r)
+        assert_equal(1, handler_counter)
+        assert_equal(1, continue_counter)
+      end
+
+      def test_continue_call_back_break_by_handler
+        ee = EventEmitter.new
+
+        handler_counter = 0
+        bla = lambda do
+          handler_counter += 1
+          false
+        end
+
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+        ee.on('foo', bla)
+
+        continue_counter = 0
+        r = ee.emit(
+          'foo',
+          [],
+          lambda do
+            continue_counter += 1
+            false
+          end
+        )
+
+        refute(r)
+        assert_equal(1, handler_counter)
+        assert_equal(0, continue_counter)
+      end
+    end
+  end
+end