octiron 0.1.0

data/lib/octiron/version.rb

@@ -0,0 +1,12 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+module Octiron
+  # The current release version
+  VERSION = "0.1.0".freeze
+end

data/lib/octiron/world.rb

@@ -0,0 +1,94 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+require 'octiron/events/bus'
+require 'octiron/transmogrifiers/registry'
+
+##
+# World module, putting together the event bus and transmogrifier registry with
+# easy access functions.
+module Octiron::World
+  ##
+  # Modules also can have class methods
+  module ClassMethods
+    ##
+    # Singleton transmogrifier registry
+    # @return (Octiron::Transmogrifiers::Registry) the registry.
+    def transmogrifier_registry
+      if @transmogrifier_registry.nil?
+        @transmogrifier_registry = ::Octiron::Transmogrifiers::Registry.new
+      end
+      return @transmogrifier_registry
+    end
+
+    ##
+    # Singleton event bus
+    # @return (Octiron::Events::Bus) the bus.
+    def event_bus
+      if @event_bus.nil?
+        @event_bus = ::Octiron::Events::Bus.new
+      end
+      return @event_bus
+    end
+  end # module ClassMethods
+  extend ClassMethods
+
+  ##
+  # Delegator for the on_transmogrify(FROM).to TO syntax
+  # @api private
+  class TransmogrifierRegistrator
+    def initialize(from)
+      @from = from
+    end
+
+    def to(to, transmogrifier_object = nil, &transmogrifier_proc)
+      ::Octiron::World.transmogrifier_registry.register(@from, to, false,
+                                                        transmogrifier_object,
+                                                        &transmogrifier_proc)
+    end
+  end
+
+  ##
+  # Delegator for the transmogrify(FROM).to TO syntax
+  # @api private
+  class TransmogrifyDelegator
+    def initialize(from)
+      @from = from
+    end
+
+    def to(to)
+      return ::Octiron::World.transmogrifier_registry.transmogrify(@from, to)
+    end
+  end
+
+  ##
+  # Register a transmogrifier with the singleton transmogrifier registry
+  def on_transmogrify(from)
+    return TransmogrifierRegistrator.new(from)
+  end
+
+  ##
+  # Transmogrify using the singleton transmogrifier registry
+  def transmogrify(from)
+    return TransmogrifyDelegator.new(from)
+  end
+
+  ##
+  # 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)
+  end
+
+  ##
+  # Publish an event on the singleton event bus
+  def publish(event)
+    ::Octiron::World.event_bus.publish(event)
+  end
+
+end

data/octiron.gemspec

@@ -0,0 +1,50 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'octiron/version'
+
+# rubocop:disable Style/UnneededPercentQ, Style/ExtraSpacing
+# rubocop:disable Style/SpaceAroundOperators, Metrics/BlockLength
+Gem::Specification.new do |spec|
+  spec.name          = "octiron"
+  spec.version       = Octiron::VERSION
+  spec.authors       = ["Jens Finkhaeuser"]
+  spec.email         = ["jens@finkhaeuser.de"]
+  spec.description   = %q(
+    Events octiron responds to can be any classes or Hash prototypes. Using
+    transmogrifiers, events can be turned into other kinds of events
+    transparently.
+  )
+  spec.summary       = %q(
+    Octiron is an event bus with the ability to magically transform events.
+  )
+  spec.homepage      = "https://github.com/jfinkhaeuser/octiron"
+  spec.license       = "MITNFA"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 2.0'
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rubocop", "~> 0.46"
+  spec.add_development_dependency "rake", "~> 11.3"
+  spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "simplecov", "~> 0.12"
+  spec.add_development_dependency "yard", "~> 0.9"
+
+  spec.add_dependency "collapsium", "~> 0.8"
+  spec.add_dependency "rgl", "~> 0.5"
+end
+# rubocop:enable Style/SpaceAroundOperators, Metrics/BlockLength
+# rubocop:enable Style/UnneededPercentQ, Style/ExtraSpacing

data/spec/events_bus_spec.rb

@@ -0,0 +1,322 @@
+require 'spec_helper'
+require_relative '../lib/octiron/events/bus'
+
+class TestEvent
+end
+
+module TestModule
+  class InnerTestEvent
+  end
+end
+
+class TestHandler
+  attr_reader :invoked, :event
+
+  def initialize
+    @invoked = 0
+    @event = nil
+  end
+
+  def call(event)
+    @event = event
+    @invoked += 1
+  end
+end
+
+describe Octiron::Events::Bus do
+  describe "construction" do
+    it "can be constructed without a default namespace" do
+      bus = nil
+      expect do
+        bus = ::Octiron::Events::Bus.new
+      end.not_to raise_error
+
+      expect(bus.default_namespace).to eql 'Octiron::Events'
+    end
+
+    it "can be constructed with a namespace" do
+      bus = nil
+      expect do
+        bus = ::Octiron::Events::Bus.new(::Octiron::Events)
+      end.not_to raise_error
+
+      expect(bus.default_namespace).to eql 'Octiron::Events'
+    end
+  end
+
+  describe "subscription" do
+    before :each do
+      @bus = ::Octiron::Events::Bus.new(::Octiron::Events)
+    end
+
+    it "requires a handler" do
+      expect do
+        @bus.subscribe(TestEvent)
+      end.to raise_error(ArgumentError)
+    end
+
+    it "can subscribe an object handler for an event" do
+      klass = nil
+      expect do
+        klass = @bus.subscribe(TestEvent, TestHandler.new)
+      end.not_to raise_error
+      expect(klass).to eql 'TestEvent'
+    end
+
+    it "can subscribe a handler proc for an event" do
+      klass = nil
+      expect do
+        klass = @bus.subscribe(TestEvent) do |_|
+        end
+      end.not_to raise_error
+      expect(klass).to eql 'TestEvent'
+    end
+
+    describe "event name validation" do
+      it "accepts string event IDs" do
+        klass = nil
+        expect do
+          klass = @bus.subscribe('TestEvent', TestHandler.new)
+        end.not_to raise_error
+        expect(klass).to eql 'TestEvent'
+      end
+
+      it "accepts symbolized/underscored event IDs" do
+        klass = nil
+        expect do
+          klass = @bus.subscribe(:test_event, TestHandler.new)
+        end.not_to raise_error
+        expect(klass).to eql 'TestEvent'
+
+        expect do
+          @bus.subscribe(:inner_test_event, TestHandler.new)
+        end.to raise_error(NameError)
+
+        bus = ::Octiron::Events::Bus.new(::TestModule)
+        expect do
+          klass = bus.subscribe(:inner_test_event, TestHandler.new)
+        end.not_to raise_error
+        expect(klass).to eql 'TestModule::InnerTestEvent'
+      end
+
+      it "accepts Hash event IDs" do
+        proto = {
+          a: nil,
+          b: {
+            c: 42,
+          },
+        }
+
+        klass = nil
+        expect do
+          klass = @bus.subscribe(proto, TestHandler.new)
+        end.not_to raise_error
+        expect(klass).to eql proto
+      end
+    end
+  end
+
+  describe "event notification" do
+    before :each do
+      @bus = ::Octiron::Events::Bus.new(::Octiron::Events)
+    end
+
+    it "notifies a single handler object" do
+      event = TestEvent.new
+      handler = TestHandler.new
+
+      @bus.subscribe(TestEvent, handler)
+      @bus.publish(event)
+
+      expect(handler.invoked).to eql 1
+      expect(handler.event.object_id).to eql event.object_id
+    end
+
+    it "notifies multiple handler objects" do
+      event = TestEvent.new
+      handler1 = TestHandler.new
+      handler2 = TestHandler.new
+
+      @bus.subscribe(TestEvent, handler1)
+      @bus.subscribe(TestEvent, handler2)
+      @bus.publish(event)
+
+      expect(handler1.invoked).to eql 1
+      expect(handler1.event.object_id).to eql event.object_id
+      expect(handler2.invoked).to eql 1
+      expect(handler2.event.object_id).to eql event.object_id
+    end
+
+    it "notifies a single handler proc" do
+      event = TestEvent.new
+      got_event = nil
+
+      @bus.subscribe(TestEvent) do |fired|
+        got_event = fired
+      end
+      @bus.publish(event)
+
+      expect(got_event.object_id).to eql event.object_id
+    end
+
+    it "notifies multiple handler procs" do
+      event = TestEvent.new
+      got_event1 = nil
+      got_event2 = nil
+
+      @bus.subscribe(TestEvent) do |fired|
+        got_event1 = fired
+      end
+      @bus.subscribe(TestEvent) do |fired|
+        got_event2 = fired
+      end
+      @bus.publish(event)
+
+      expect(got_event1.object_id).to eql event.object_id
+      expect(got_event2.object_id).to eql event.object_id
+    end
+
+    it "notifies from a Hash event" do
+      proto = {
+        a: nil,
+        b: {
+          c: 42,
+        },
+      }
+      handler = TestHandler.new
+
+      @bus.subscribe(proto, handler)
+
+      # Bad event #1
+      bad_event1 = {
+        a: 'foo',
+        # :b is missing
+      }
+      @bus.publish(bad_event1)
+      expect(handler.invoked).to eql 0
+
+      # Bad event #2
+      bad_event2 = {
+        a: 'foo',
+        b: {
+          c: 123, # value mismatch
+        }
+      }
+      @bus.publish(bad_event2)
+      expect(handler.invoked).to eql 0
+
+      # Good event
+      good_event = {
+        a: 'foo',
+        b: {
+          c: 42,
+        }
+      }
+      @bus.publish(good_event)
+      expect(handler.invoked).to eql 1
+    end
+
+    it "matches multiple Hash prototypes" do
+      # Two similar prototypes
+      proto1 = {
+        a: 42,
+      }
+      handler1 = TestHandler.new
+      @bus.subscribe(proto1, handler1)
+
+      proto2 = {
+        a: nil,
+      }
+      handler2 = TestHandler.new
+      @bus.subscribe(proto2, handler2)
+
+      # Fire one event that matches both
+      @bus.publish(a: 42)
+
+      expect(handler1.invoked).to eql 1
+      expect(handler2.invoked).to eql 1
+    end
+
+    it "stores handlers for the best matching prototype" do
+      # Two different prototypes
+      proto1 = {
+        b: 42,
+      }
+      handler1 = TestHandler.new
+      @bus.subscribe(proto1, handler1)
+
+      proto2 = {
+        a: nil,
+      }
+      handler2 = TestHandler.new
+      @bus.subscribe(proto2, handler2)
+
+      handler3 = TestHandler.new
+      @bus.subscribe(proto2, handler3)
+
+      # Fire one event that matches one prototype
+      @bus.publish(a: 42)
+
+      expect(handler1.invoked).to eql 0
+      expect(handler2.invoked).to eql 1
+      expect(handler3.invoked).to eql 1
+    end
+  end
+
+  describe "unsubscription" do
+    before :each do
+      @bus = ::Octiron::Events::Bus.new(::Octiron::Events)
+    end
+
+    it "requires a handler" do
+      expect do
+        @bus.unsubscribe(TestEvent)
+      end.to raise_error(ArgumentError)
+    end
+
+    it "unsubscripes object handlers properly" do
+      event = TestEvent.new
+      handler1 = TestHandler.new
+      handler2 = TestHandler.new
+
+      @bus.subscribe(TestEvent, handler1)
+      @bus.subscribe(TestEvent, handler2)
+      @bus.publish(event)
+
+      expect(handler1.invoked).to eql 1
+      expect(handler1.event.object_id).to eql event.object_id
+      expect(handler2.invoked).to eql 1
+      expect(handler2.event.object_id).to eql event.object_id
+
+      @bus.unsubscribe(TestEvent, handler2)
+      @bus.publish(event)
+
+      expect(handler1.invoked).to eql 2
+      expect(handler2.invoked).to eql 1
+    end
+
+    it "unsubscripes proc handlers  properly" do
+      event = TestEvent.new
+      invoked1 = 0
+      invoked2 = 0
+
+      @bus.subscribe(TestEvent) do |_|
+        invoked1 += 1
+      end
+      second = proc do |_|
+        invoked2 += 1
+      end
+      @bus.subscribe(TestEvent, &second)
+      @bus.publish(event)
+
+      expect(invoked1).to eql 1
+      expect(invoked2).to eql 1
+
+      @bus.unsubscribe(TestEvent, &second)
+      @bus.publish(event)
+
+      expect(invoked1).to eql 2
+      expect(invoked2).to eql 1
+    end
+  end
+end