seh 0.1.0 → 0.3.0

data/lib/seh/event_bind_disconnector.rb

@@ -0,0 +1,17 @@
+module Seh
+  # EventBindDisconnector should not be used directly. Event#bind and Event#bind_once return instances of EventBindDisconnector.
+  class EventBindDisconnector
+    def initialize disconnect_proc
+      @disconnect_proc = disconnect_proc
+    end
+
+    # Disconnect this bind from its EventTarget
+    def disconnect
+      unless @disconnect_proc.nil?
+        @disconnect_proc.call
+        @disconnect_proc = nil
+      end
+      nil
+    end
+  end
+end

data/lib/seh/event_target.rb

@@ -1,36 +1,44 @@
+require_relative 'event_bind'
+require_relative 'event_bind_disconnector'
+
 module Seh
   module EventTarget
-    def bind( event_type=nil, &block )
-      raise "EventTarget::bind expects a block" unless block_given?
+    def bind event_type=nil, &block
+      raise "expected a block" unless block_given?
       @_binds ||= []
-      bind = Private::EventBind.new( event_type, &block )
+      bind = EventBind.new event_type, &block
       @_binds << bind
-      ->{ @_binds.delete bind }
+      EventBindDisconnector.new ->{ @_binds.delete bind; nil }
     end
 
-    def bind_once( event_type=nil, &block )
+    def bind_once event_type=nil, &block
       return unless block_given?
-      disconnect = self.bind(event_type) { |event| disconnect.call; block.call event }
-      disconnect
+      bind_disconnector = self.bind(event_type) { |event| bind_disconnector.disconnect; block.call event }
+    end
+
+    # @private
+    # Internal use only. Used in Seh::Event.
+    # Override #observers as needed.
+    # @return [EventTarget] - array of other EventTargets observing this EventTarget
+    def observers
+      []
     end
 
-    def each_bind
+    # @private
+    # Internal use only. Used in Seh::Event.
+    # For each bind matching the passed event_types, yield the bind's callback
+    # @param event_types - Array of event types
+    # @yield each bind callback matching the passed event types
+    # @return nil
+    def each_matching_callback event_types
       @_binds ||= []
-      @_binds.dup.each { |b| yield b }
+      @_binds.each { |bind| yield bind.block if bind.event_type.match event_types }
       nil
     end
-  end
 
-  # @private
-  module Private
-    class EventBind
-      attr_reader :event_type, :block
-
-      def initialize( event_type, &block )
-        event_type = EventType.new event_type unless event_type.is_a? EventType
-        @event_type = event_type
-        @block = block
-      end
-    end # EventBind
-  end # Private
+    # An empty class that includes EventTarget
+    class Default
+      include EventTarget
+    end
+  end
 end

data/lib/seh/event_type.rb

@@ -1,56 +1,46 @@
 module Seh
   class EventType
-    attr_reader :type
-
-    def initialize( type )
+    def initialize type
       @type = type
     end
 
-    def match(types)
-      types = [types] unless types.respond_to? :each
-      _match types
-    end
-
-    private
-    def _match(types)
-      return true if not self.type or types.include? self.type
-      false
+    # @param types - an Array of types
+    def match types
+      return true if @type.nil? # define nil to match everything
+      types.include? @type
     end
 
     class And < EventType
-      def initialize(*types)
+      def initialize *types
         @types = []
         types.each { |t| t = EventType.new t unless t.kind_of? EventType ; @types << t }
       end
 
-      private
-      def _match(types)
+      def match types
         @types.each { |t| return false unless t.match types }
         true
       end
     end # And
 
     class Or < EventType
-      def initialize(*types)
+      def initialize *types
         @types = []
         types.each { |t| t = EventType.new t unless t.kind_of? EventType ; @types << t }
       end
 
-      private
-      def _match(types)
+      def match types
         @types.each { |t| return true if t.match types }
         false
       end
     end # Or
 
     class Not < EventType
-      def initialize(type)
+      def initialize type
         type = EventType.new type unless type.kind_of? EventType
         @type = type
       end
 
-      private
-      def _match(types)
+      def match types
         ! @type.match types
       end
     end # Not

data/lib/seh/version.rb

@@ -1,4 +1,4 @@
 module Seh
   # @private
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/seh.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Ryan Berckmans"]
   s.email       = ["ryan.berckmans@gmail.com"]
   s.homepage    = "https://github.com/ryanberckmans/seh"
-  s.summary     = "Structured event handler. Pure ruby event handling similar to w3c dom events; alpha wip."
-  s.description = "#{s.summary} Lots of bells and whistles to support complex event handling as required by stuff like video games. Event handling in a synchronous specific order. Events 'bubble', and event targets can have multiple parents and common ancestors. Staged event callbacks: event.before { 'the united states of' }; event.after { 'america' }. Staged callbacks allow an ancestor to influence affect of event on a descendant: ancestor.before { |event| event.damage *= 2 }; descendant.after { |event| player.health -= event.damage }. Events use 'tag-style' types: event.type :hostile ; event.type :spell. Handle only events which pass a filter: player.bind( Seh::and :hostile, Seh::not( :spell ) ) { |event| 'Hostile non-spell!!' }. Optional event failure: event.fail; event.success { 'yay!' }; event.failure { 'oops!' }. Event inherits from OpenStruct for dynamic properties: event.omgs = 'omgs a dynamic attribute'"
+  s.summary     = "Structured event handler. Pure ruby event handling similar to w3c dom events."
+  s.description = "#{s.summary} Synchronous, local event handling for complex emergent behaviors as required by something like a game engine. v0.3.0 improves a lot on v0.1.0."
 
   s.rubyforge_project = "seh"
 

data/spec/seh/event_bind_disconnector_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+require 'seh/event_bind_disconnector'
+
+module Seh
+  describe EventBindDisconnector do
+    before :each do @proc = ->{ "nice!" } end
+    subject { EventBindDisconnector.new @proc }
+
+    it "calls proc on disconnect" do
+      @proc.should_receive(:call).once
+      subject.disconnect
+    end
+
+    its(:disconnect) { should be_nil }
+
+    it "sets the proc reference to nil on disconnect, so the proc is only ever called once" do
+      @proc.should_receive(:call).once
+      subject.disconnect
+      subject.disconnect
+      subject.disconnect
+    end
+  end
+end

data/spec/seh/event_bind_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+require 'seh/event_bind'
+require 'seh/event_type'
+
+module Seh
+  describe EventBind do
+    before :each do
+      @event_type = EventType.new :some_type
+      @block = ->{ callback! }
+    end
+    subject { EventBind.new @event_type, &@block  }
+    its(:block) { should eq(@block) }
+    its(:event_type) { should eq(@event_type) }
+
+    it "wraps a non-EventType in an EventType" do
+      type = :not_an_EventType
+      EventType.should_receive(:new).with(type).once.and_call_original
+      bind = EventBind.new type, &@block
+      bind.event_type.should be_a(EventType)
+    end
+  end
+end

data/spec/seh/event_spec.rb

@@ -0,0 +1,209 @@
+require 'spec_helper'
+
+require 'seh/event'
+require 'seh/event_target'
+
+module Seh
+  class ObservableEventTarget
+    include EventTarget
+    def initialize
+      @observers = []
+    end
+    attr_accessor :observers
+  end
+
+  describe Event do
+    it "adds a few targets" do
+      target1 = EventTarget::Default.new
+      target2 = EventTarget::Default.new
+      expect { subject.target target1, target2 }.to change{ subject.send :collect_targets }.from(Set.new).to(Set.new << target1 << target2)
+    end
+
+    it "dispatch runs target and then stage callbacks" do
+      subject.should_receive(:run_target_callbacks).once.ordered
+      subject.should_receive(:run_stage_callbacks).once.ordered
+      subject.dispatch
+    end
+
+    it "dispatch may not be run twice" do
+      subject.dispatch
+      expect { subject.dispatch }.to raise_error
+    end
+
+    context "testing abort" do
+      it "does nothing when #abort is called before #dispatch" do
+        subject.abort
+        subject.should_receive(:run_target_callbacks).never
+        subject.should_receive(:run_stage_callbacks).never
+        subject.dispatch
+      end
+
+      it "visits all targets when #abort is called during a target callback" do
+        type = :foo
+
+        target1 = ObservableEventTarget.new
+        target2 = EventTarget::Default.new
+        target3 = EventTarget::Default.new
+        target1.observers << target3
+
+        target1.bind type do |event| event.abort end
+        
+        @result = 0
+
+        target3.bind type do |event| @result += 2 end
+        target2.bind type do |event| @result += 1 end
+        
+        subject.type type
+        subject.target target1, target2
+        subject.dispatch
+        @result.should eq(3)
+      end
+
+      it "finishes the start stage and then stops when #abort is called during a start callback" do
+        @result = 0
+        subject.start do subject.abort end
+        subject.start do @result += 1 end
+        subject.start do @result += 2 end
+        subject.add_stage :never_happens
+        subject.bind :never_happens do @result += 5 end
+        subject.dispatch
+        @result.should eq(3)
+      end
+
+      it "finishes the current stage and then stops when #abort is called during a stage callback" do
+        @result = 0
+        subject.add_stage :does_happens
+        subject.add_stage :never_happens
+        subject.bind :does_happens do @result += 1; subject.abort end
+        subject.bind :does_happens do @result += 2 end 
+        subject.bind :never_happens do @result += 5 end
+        subject.dispatch
+        @result.should eq(3)
+      end
+
+      it "doesn't run finish callbacks when #abort is called during a stage callback" do
+        @result = 0
+        subject.add_stage :does_happens
+        subject.bind :does_happens do @result += 1; subject.abort end
+        subject.finish do @result += 5 end
+        subject.dispatch
+        @result.should eq(1)
+      end
+    end
+
+    context "testing callbacks" do
+      before :each do
+        @counter = 0
+        @callback = ->event{
+          @counter += 1
+        }
+      end
+
+      context "testing stage callbacks" do
+        it "runs a start callback" do
+          expect { subject.start &@callback}.to change{ subject.send :run_stage_callbacks; @counter }.from(0).to(1)
+        end
+        it "runs a finish callback" do
+          expect { subject.finish &@callback}.to change{ subject.send :run_stage_callbacks; @counter }.from(0).to(1)
+        end
+        it "runs a stage callback" do
+          stage = :foo
+          subject.add_stage stage
+          expect { subject.bind stage, &@callback}.to change{ subject.send :run_stage_callbacks; @counter }.from(0).to(1)
+        end
+        it "runs a stage whose stage_decision_block evaluates to true" do
+          @result = 0
+          stage = :should_be_run
+          subject.add_stage stage do true end
+          subject.bind stage do @result += 1 end
+          subject.bind stage do @result += 2 end
+          subject.dispatch
+          @result.should eq(3)
+        end
+        it "skips a stage whose stage_decision_block evaluates to false" do
+          @result = 0
+          stage = :should_not_be_run
+          subject.add_stage stage do false end
+          subject.bind stage do @result += 1 end
+          subject.bind stage do @result += 2 end
+          subject.dispatch
+          @result.should eq(0)
+        end
+        it "runs start before a stage" do
+          result = []
+          subject.add_stage :stage2
+          subject.bind :stage2 do result << :second end
+          subject.start { result << :first }
+          subject.send :run_stage_callbacks
+          result.should eq([:first,:second])
+        end
+        it "runs finish after a stage" do
+          result = []
+          subject.add_stage :stage2
+          subject.bind :stage2 do result << :first end
+          subject.finish { result << :second }
+          subject.send :run_stage_callbacks
+          result.should eq([:first,:second])
+        end
+        it "runs stages the order they were added" do
+          result = []
+          subject.add_stage :stage2
+          subject.add_stage :stage3
+          subject.add_stage :stage4
+          subject.bind :stage4 do result << :third end
+          subject.bind :stage3 do result << :second end
+          subject.bind :stage2 do result << :first end
+          subject.send :run_stage_callbacks
+          result.should eq([:first,:second,:third])
+        end
+      end
+
+      context "testing invoking of target callbacks" do
+        before :each do
+          @target = EventTarget::Default.new
+          @type = :some_type
+          subject.target @target
+          subject.type @type
+        end
+        
+        it "calls a target callback" do
+          expect { @target.bind @type, &@callback }.to change{ subject.send :run_target_callbacks; @counter}.from(0).to(1)
+        end
+
+        it "passes self to a target callback" do
+          @result = nil
+          @target.bind @type do |event| @result = event end
+          subject.send:run_target_callbacks
+          @result.should eq(subject)
+        end
+      end
+    end # testing callbacks
+    
+
+    context "with a target containing a DAG of observers" do
+      before :each do
+        @target1 = ObservableEventTarget.new
+        @observer1 = EventTarget::Default.new
+        @observer2 = EventTarget::Default.new
+        @observer3 = ObservableEventTarget.new
+        @observer4 = ObservableEventTarget.new
+        @observer5 = EventTarget::Default.new
+        
+        @observer3.observers << @observer2
+        @observer3.observers << @observer4
+        @observer4.observers << @observer5 << @observer1
+
+        @target2 = ObservableEventTarget.new
+        @observer6 = EventTarget::Default.new
+
+        @target2.observers << @observer6
+        
+        @target1.observers << @observer1 << @observer2 << @observer3
+      end
+
+      it "collects_targets in a Set which traverses the observer graph" do
+        expect { subject.target @target1, @observer5, @target2 }.to change { subject.send :collect_targets}.from(Set.new).to(Set.new << @target1 << @target2 << @observer1 << @observer2 << @observer3 << @observer4 << @observer5 << @observer6 )
+      end
+    end
+  end
+end

data/spec/seh/event_target_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+require 'seh/event_target'
+require 'seh/event_bind_disconnector'
+
+module Seh
+  module EventTarget
+    describe Default do
+      it { subject.should be_a(EventTarget) }
+
+      its(:observers) { should eq([]) }
+
+      it { subject.each_matching_callback([]).should be_nil }
+
+      it "adds a bind" do
+        event_type = :some_type
+        block = -> { callback! }
+        EventBind.should_receive(:new).with(event_type,&block).once.and_call_original
+        bind_disconnector = subject.bind event_type, &block
+        bind_disconnector.should be_a(EventBindDisconnector)
+      end
+
+      context "with added binds" do
+        before :each do
+          @event_type1 = :another_type
+          @block1 = -> { callback! }
+          @bind_disconnector1 = subject.bind @event_type1, &@block1
+
+          @event_type2 = :second_type
+          @block2 = -> { twocallback! }
+          @bind_disconnector2 = subject.bind @event_type2, &@block2
+
+          @event_type3 = :third_type
+          @block3 = ->event{ "do nothing" }
+          @bind_disconnector3 = subject.bind_once @event_type3, &@block3
+        end
+
+        it "yields the block for a matching bind in each_matching_callback" do
+          expected_blocks = []
+          subject.each_matching_callback([@event_type1]) { |block| expected_blocks << block }
+          expected_blocks.should include(@block1)
+          expected_blocks.size.should eq(1)
+        end
+
+        it "yields both blocks for the matching binds in each_matching_callback" do
+          expected_blocks = []
+          subject.each_matching_callback([@event_type1,@event_type2]) { |block| expected_blocks << block }
+          expected_blocks.should include(@block1)
+          expected_blocks.should include(@block2)
+          expected_blocks.size.should eq(2)
+        end
+
+        it "yields nothing when no binds match the event_types in each_matching_callback" do
+          expected_blocks = []
+          subject.each_matching_callback([:unknown_type]) { |block| expected_blocks << block }
+          expected_blocks.size.should eq(0)
+        end
+
+        it "disconnects bind3 after a single block invocation, since bind3 was connected using bind_once" do
+          expected_blocks = []
+          subject.each_matching_callback([@event_type3]) { |block| expected_blocks << block }
+          expected_blocks.should_not include(@block3) # @block3 would have been wrapped in another block during bind_once, so we don't expect to find it
+          expected_blocks.size.should eq(1) # the single block in the array is the new block wrapping @block3
+          expected_blocks[0].call
+
+          # After @block3 was called, we shouldn't expect to find it anymore
+          expected_blocks.clear
+          expected_blocks.size.should eq(0) # verify clear
+          subject.each_matching_callback([@event_type3]) { |block| expected_blocks << block }
+          expected_blocks.size.should eq(0)
+        end
+
+        context "with bind1 disconnected" do
+          before :each do
+            @bind_disconnector1.disconnect
+          end
+
+          it "yields only the second block in each_matching_callback, since the first was disconnected" do
+            expected_blocks = []
+            subject.each_matching_callback([@event_type1,@event_type2]) { |block| expected_blocks << block }
+            expected_blocks.should include(@block2)
+            expected_blocks.size.should eq(1)
+          end
+        end
+      end
+    end
+  end
+end