octiron 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f6820493b0a41711b72e1cfa9b460a668c1c51a
-  data.tar.gz: 927c382237fb5ac19863356b451a5cef89610248
+  metadata.gz: 77fcd14d6034f8507cd48bcccad8e1c842895bd7
+  data.tar.gz: fd7c20ee199a1406e6973ef92519617c14cd628a
 SHA512:
-  metadata.gz: 4a2ed141ecc3d958d49e9e9e3e79ee6e2d6187b4c470934119f8cfb71c7a756d7b8caf89a2b26552d69cc7545d61d72c342ed076c0a7a97b152e875c0afed399
-  data.tar.gz: d6843fe8e9550957fb1eee0a2cfdbee28d01ee65eab309c69842f1056709c26ad9a0bc4707c515e8c2213ca74fcdc6ba8665fdea2d996cb12e4e9189b7f53953
+  metadata.gz: 292f9c0256bec186e77be6ca75bb864a6d5b5ea99f1179be7202c6fbe941f4fbe3c4d238f056ad2539f6ed4f12d70f04beb8fce24b9b8616b22b429333447265
+  data.tar.gz: ce519cfd7d727e6241a745417c74319b84fd47f403a6a92f7e732e954921d69d1fdd106d633c32650564c2c880ec4d36673d1956d3185c29e6698968eca86271

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    octiron (0.2.0)
+    octiron (0.3.0)
       collapsium (~> 0.8)
       rgl (~> 0.5)
 

data/README.md

@@ -122,6 +122,49 @@ end
 publish(SourceEvent.new) # will raise RuntimeError
 ```
 
+### Handler Classes
+
+*The term "Handler Class" should not be confused with Ruby classes implementing
+handlers. Instead, a class is a grouping "type".*
+
+There may be situations where you want your handlers to be executed in a
+particular order. That is especially the case when one handler relies on a
+different handler having been executed earlier. For those instances, you can
+sort your handlers into classes as you subscribe them:
+
+```ruby
+on_event(MyEvent, nil, SOME_CLASS) do |event|
+  # ...
+end
+
+on_event(MyEvent, nil, ANOTHER_CLASS) do |event|
+  # ...
+end
+```
+
+In the above example, the two handlers are subscribed with the `SOME_CLASS` and
+`ANOTHER_CLASS` constants as handler classes respectively. These parameters must
+be sortable values: if `ANOTHER_CLASS`'s value is sorted before `SOME_CLASS`,
+then the second handler is executed before the first, e.g. in this instance:
+
+```ruby
+ANOTHER_CLASS = 0
+SOME_CLASS = 1
+```
+
+Note that we're passing a `nil` object as the second parameter every time. This
+is because we're subscribing a block handler. For an object handler, the code
+would have to be the following:
+
+```ruby
+on_event(MyEvent, second_handler, SOME_CLASS)
+on_event(MyEvent, first_handler, ANOTHER_CLASS)
+```
+
+Since handlers don't create new events, but pass the event from one handler to
+another, ordering handlers in classes allows you to modify an event before it
+reaches another handler.
+
 ### Singletons vs. API
 
 The octiron gem exposes a number of simple wrapper functions we've used so far

data/lib/octiron/events/bus.rb

@@ -21,6 +21,9 @@ module Octiron::Events
     # @return (String) the default namespace to search for events
     attr_reader :default_namespace
 
+    # The default handler class
+    DEFAULT_CLASS = 'octiron-default'.freeze
+
     ##
     # @param default_namespace (Symbol) The default namespace to look in for
     #     Event classes.
@@ -42,14 +45,19 @@ module Octiron::Events
     # @param handler_object (Object) Handler object that must implement a
     #     `#call` method accepting an instance of the event class provided in
     #     the first parameter. If nil, a block needs to be provided.
+    # @param handler_class (Object) An object describing the handler class; the
+    #     default is DEFAULT_CLASS. Handlers are executed sorted by handler class,
+    #     so the class provided here must be sortable.
     # @param handler_proc (Proc) Handler block that accepts an instance of the
     #     event class provided in the first parameter. If nil, a handler object
     #     must be provided.
     # @return The class represented by the event_id, as a String name.
-    def subscribe(event_id, handler_object = nil, &handler_proc)
-      return with_handlers(event_id, handler_object, handler_proc) do |hlist, h|
-        hlist << h
-      end
+    def subscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS,
+                  &handler_proc)
+      return with_handlers(event_id, handler_class, handler_object,
+                           handler_proc) do |hlist, h|
+               hlist << h
+             end
     end
     alias register subscribe
 
@@ -60,14 +68,19 @@ module Octiron::Events
     # @param handler_object (Object) Handler object that must implement a
     #     `#call` method accepting an instance of the event class provided in
     #     the first parameter. If nil, a block needs to be provided.
+    # @param handler_class (Object) An object describing the handler class; the
+    #     default is DEFAULT_CLASS. Handlers are executed sorted by handler class,
+    #     so the class provided here must be sortable.
     # @param handler_proc (Proc) Handler block that accepts an instance of the
     #     event class provided in the first parameter. If nil, a handler object
     #     must be provided.
     # @return The class represented by the event_id, as a String name.
-    def unsubscribe(event_id, handler_object = nil, &handler_proc)
-      return with_handlers(event_id, handler_object, handler_proc) do |hlist, h|
-        hlist.delete(h)
-      end
+    def unsubscribe(event_id, handler_object = nil, handler_class = DEFAULT_CLASS,
+                    &handler_proc)
+      return with_handlers(event_id, handler_class, handler_object,
+                           handler_proc) do |hlist, h|
+               hlist.delete(h)
+             end
     end
 
     ##
@@ -79,8 +92,10 @@ module Octiron::Events
       if not event.is_a?(Hash)
         event_name = event.class.to_s
       end
-      handlers_for(event_name, false).each do |handler|
-        handler.call(event)
+      @handlers.keys.sort.each do |handler_class|
+        handlers_for(event_name, handler_class, false).each do |handler|
+          handler.call(event)
+        end
       end
     end
     alias broadcast publish
@@ -91,7 +106,10 @@ module Octiron::Events
     # The first parameters is the event class or event name. The second parameter
     # is whether this is for write or read access. We don't want to pollute
     # @handlers with data from the #publish call.
-    def handlers_for(name, write)
+    def handlers_for(name, handler_class, write)
+      # Defaults for the class
+      @handlers[handler_class] ||= {}
+
       # Use prototype matching for Hash names
       if name.is_a?(Hash)
         name.extend(::Collapsium::PrototypeMatch)
@@ -106,7 +124,7 @@ module Octiron::Events
           best_proto = nil
 
           # Find the best matching prototype
-          @handlers.keys.each do |proto|
+          @handlers[handler_class].keys.each do |proto|
             score = name.prototype_match_score(proto)
             if score > best_score
               best_score = score
@@ -115,14 +133,14 @@ module Octiron::Events
           end
 
           if not best_proto.nil?
-            return @handlers[best_proto]
+            return @handlers[handler_class][best_proto]
           end
         else
           merged = []
 
-          @handlers.keys.each do |proto|
+          @handlers[handler_class].keys.each do |proto|
             if name.prototype_match(proto)
-              merged += @handlers[proto]
+              merged += @handlers[handler_class][proto]
             end
           end
 
@@ -140,19 +158,19 @@ module Octiron::Events
       # If we're in write access, make sure to store an empty list as well as
       # returning one (if necessary).
       if write
-        @handlers[name] ||= []
+        @handlers[handler_class][name] ||= []
       end
 
       # In read access, want to either return an empty list, or the registered
       # handlers, but not ovewrite the registered handlers.
-      return @handlers[name] || []
+      return @handlers[handler_class][name] || []
     end
 
-    def with_handlers(event_id, handler_object, handler_proc)
+    def with_handlers(event_id, handler_class, handler_object, handler_proc)
       handler = resolve_handler(handler_object, &handler_proc)
       event_name = identify(event_id)
 
-      yield handlers_for(event_name, true), handler
+      yield handlers_for(event_name, handler_class, true), handler
 
       return event_name
     end

data/lib/octiron/version.rb

@@ -8,5 +8,5 @@
 #
 module Octiron
   # The current release version
-  VERSION = "0.2.0".freeze
+  VERSION = "0.3.0".freeze
 end

data/lib/octiron/world.rb

@@ -120,8 +120,11 @@ module Octiron::World
 
   ##
   # Subscribe an event handler to an event with the singleton event bus
-  def on_event(event_id, handler_object = nil, &handler_proc)
-    ::Octiron::World.event_bus.subscribe(event_id, handler_object, &handler_proc)
+  def on_event(event_id, handler_object = nil,
+               handler_class = ::Octiron::Events::Bus::DEFAULT_CLASS,
+               &handler_proc)
+    ::Octiron::World.event_bus.subscribe(event_id, handler_object,
+                                         handler_class, &handler_proc)
   end
 
   ##

data/spec/events_bus_spec.rb

@@ -295,7 +295,7 @@ describe Octiron::Events::Bus do
       expect(handler2.invoked).to eql 1
     end
 
-    it "unsubscripes proc handlers  properly" do
+    it "unsubscripes proc handlers properly" do
       event = TestEvent.new
       invoked1 = 0
       invoked2 = 0
@@ -319,4 +319,30 @@ describe Octiron::Events::Bus do
       expect(invoked2).to eql 1
     end
   end
+
+  context "event handler classes" do
+    before :each do
+      @bus = ::Octiron::Events::Bus.new(::Octiron::Events)
+    end
+
+    it "executes handlers in order of handler classes" do
+      invoked = []
+      @bus.subscribe(TestEvent, nil, 1) do |_|
+        invoked << 1
+      end
+      @bus.subscribe(TestEvent, nil, 2) do |_|
+        invoked << 2
+      end
+      @bus.subscribe(TestEvent, nil, 0) do |_|
+        invoked << 0
+      end
+
+      @bus.publish(TestEvent.new)
+
+      # Since we used a simple numeric class for each handler, we expect the
+      # handlers to be executed in numeric sort order - independent of the order
+      # they were subscribed.
+      expect(invoked).to eql [0, 1, 2]
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octiron
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-14 00:00:00.000000000 Z
+date: 2016-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler