seh 0.1.0 → 0.3.0

data/examples/event/hostile.rb

@@ -0,0 +1,11 @@
+module Event
+  class << self
+    def hostile event, aggressor, aggressee
+      event.target aggressor, aggressee
+      event.type :hostile
+      event.aggressor = aggressor
+      event.aggressee = aggressee
+      event
+    end
+  end
+end

data/examples/event/melee_attack.rb

@@ -0,0 +1,32 @@
+require 'seh'
+require_relative "damage"
+require_relative "hostile"
+
+module Event
+  class << self
+    def melee_attack event, attacker, defender, attack_hit, attack_damage
+      hostile event, attacker, defender
+
+      event.target attacker, defender
+      event.type :melee_attack
+
+      event.attacker = attacker
+      event.defender = defender
+      event.attack_hit = attack_hit # true/false if this attack is currently hitting
+      event.attack_damage = attack_damage # damage this attack will do if it hits
+
+      event.add_stage :melee_determine_hit # an opportunity to affect the outcome of attack_hit
+      event.add_stage :melee_miss do !event.attack_hit end # unless attack_hit, run melee_miss
+      event.add_stage :melee_hit do event.attack_hit end # if attack_hit is true, run melee_hit
+
+      event.finish do # when the melee_attack event is over, create a damage event if the attack hit
+        next unless event.attack_hit
+        damage_event = Seh::Event.new
+        damage damage_event, event.attacker, event.defender, event.attack_damage
+        damage_event.dispatch
+      end
+
+      event
+    end
+  end # class << self
+end

data/examples/event_color.rb

@@ -0,0 +1,57 @@
+
+COLORS = {
+  "{@"    =>     "\033[0m", #reset
+  # styles
+  "{!"       =>     "\033[1m", #bold
+  "underlineZZ"  =>     "\033[4m",
+  "blinkZZ"      =>     "\033[5m",
+  "reverseZZ"    =>     "\033[7m",
+  "concealedZZZ"  =>     "\033[8m",
+  # font colors
+  "{FB"      =>     "\033[30m", 
+  "{FR"        =>     "\033[31m",
+  "{FG"      =>     "\033[32m",
+  "{FY"     =>     "\033[33m",
+  "{FU"       =>     "\033[34m",
+  "{FM"    =>     "\033[35m",
+  "{FC"       =>     "\033[36m",
+  "{FW"      =>     "\033[37m",
+  # background colors
+  "{BB"   =>     "\033[40m", 
+  "{BR"     =>     "\033[41m",
+  "{BG"   =>     "\033[42m",
+  "{BY"  =>     "\033[43m",
+  "{BU"    =>     "\033[44m",
+  "{BM" =>     "\033[45m",
+  "{BC"    =>     "\033[46m",
+  "{BW"   =>     "\033[47m" 
+}
+
+def color msg
+  COLORS.each do |color,code|
+    msg.gsub! color, code
+  end
+  msg
+end
+
+FOREGROUND_COLORS = [
+                     "{FR",
+                     "{FG",
+                     "{FY",
+                     "{FU",
+                     "{FM",
+                     "{FC",
+                    ]
+
+# cycle through foreground colors
+def next_foreground_color
+  color = FOREGROUND_COLORS.shift
+  FOREGROUND_COLORS.push color
+  color
+end
+
+EVENT_COLORS = {}
+def puts_color_event event_id, msg
+  EVENT_COLORS[event_id] ||= next_foreground_color
+  puts color "{!#{EVENT_COLORS[event_id]}#{msg}{@"
+end

data/examples/mob.rb

@@ -0,0 +1,10 @@
+require 'seh'
+
+class Mob
+  include Seh::EventTarget
+  attr_accessor :hp, :observers
+  def initialize
+    @hp = 100
+    @observers = []
+  end
+end

data/lib/seh.rb

@@ -1,22 +1,19 @@
-require "seh/version"
-require "seh/event_type"
-require "seh/event_target"
-require "seh/event"
+Dir[File.dirname(__FILE__) + '/seh/*.rb'].each {|file| require file }
 
 module Seh
   class << self
     # @note alias of {EventType::And}
-    def and( *types )
+    def and *types
       EventType::And.new *types
     end
 
     # @note alias of {EventType::Or}
-    def or( *types )
+    def or *types
       EventType::Or.new *types
     end
 
     # @note alias of {EventType::Not}
-    def not( type )
+    def not type
       EventType::Not.new type
     end
   end

data/lib/seh/event.rb

@@ -1,178 +1,161 @@
+require 'set'
 require 'ostruct'
 
 module Seh
-  # @private
-  module Private
-    START = 0
-    BEFORE = 100
-
-    BEFORE_SUCCESS = 250
-    BEFORE_FAILURE = 250
-
-    SUCCESS = 500
-    FAILURE = 500
-
-    AFTER_SUCCESS = 750
-    AFTER_FAILURE = 750
-
-    AFTER = 900
-    FINISH = 1000
-
-    class EventData
-      attr_accessor :types, :type_map, :target, :time, :staged_handlers, :success
-
-      def initialize
-        @types = []
-        @type_map = {}
-        @target = nil
-        @time = Time.now
-        @success = true
-
-        # staged handlers
-        @staged_handlers = {}
-      end
-    end
-
-    class EventStateReady
-      class << self
-        def type( data, t )
-          data.types << t
-          apply_type_map data
-        end
-
-        def type_map( data, map = {} )
-          map.each_pair do |type, implied_types|
-            data.type_map[type] ||= []
-            data.type_map[type].concat implied_types
-            data.type_map[type].uniq!
-          end
-          apply_type_map data
-        end
-
-        private
-        def apply_type_map( data )
-          while true
-            original_size = data.types.size
-            data.type_map.each_pair { |type, implied_types| data.types.concat implied_types if data.types.include? type }
-            data.types.uniq!
-            break if original_size = data.types.size
-          end
-        end
-      end
-    end
-
-    class EventStateInflight
-    end
-
-    class EventStateDone
-    end
-  end
-
   class Event < OpenStruct
-    def initialize(target, &block)
-      super()
-      raise "Event expects a target" unless target
-      raise "Event expects the target to include EventTarget" unless target.class.include? EventTarget
-      @state = Private::EventStateReady
-      @data = Private::EventData.new
-      @data.target = target
-      instance_eval(&block) if block
-    end
-
-    def fail
-      @data.success = false
-    end
-
-    def success?
-      @data.success
-    end
-
+    def initialize
+      super
+      @state = :ready
+      @types = Set.new
+      @targets = Set.new
+      @start_callbacks = []
+      @finish_callbacks = []
+      @stage_callbacks = {}
+      @stage_decision_blocks = {}
+      @stages = Set.new
+      @abort = false
+      yield self if block_given?
+    end
+
+    # Dispatch this event, notifying all targets of the event and executing any callbacks.
+    # #dispatch may only be called once
+    # Dispatch algorithm:
+    #  1. determine the full set of targets affected by this event
+    #  2. run callbacks on targets which match this event's types
+    #  3. run stage callbacks contained in this event; typically targets will append stage callbacks to this event using Event#bind, #start, #finish
+    #     Callback execution order:
+    #       start callbacks
+    #       stage callabcks - in the order stages were added
+    #       finish callbacks
+    #     Callbacks in the same stage have arbitrary execution order
+    # @return nil
     def dispatch
-      raise "Event#dispatch may only be called once" unless @state == Private::EventStateReady
-      @state = Private::EventStateInflight
-      collect_targets.each { |t| t.each_bind { |bind| bind.block.call self if bind.event_type.match @data.types } }
-      @data.staged_handlers.each_key.sort.each { |stage| @data.staged_handlers[stage].each { |block| block.call self } }
-      @state = Private::EventStateDone
-    end
-
-    def target
-      @data.target
-    end
-
-    def type( event_type )
-      @state.type @data, event_type
+      raise "Event#dispatch may only be called once" unless @state == :ready
+      @state = :inflight
+      return if @abort
+      run_target_callbacks
+      run_stage_callbacks
+      @state = :done
       nil
     end
 
-    def type_map( map )
-      @state.type_map @data, map
+    # Abort this Event. After #abort is called, some in-progress work may still be completed.
+    # Abort semantics:
+    #   - if #abort is called before #dispatch, #dispatch return immediately, no target will know the event occurred, and no callbacks will be executed
+    #   - if #abort is called by a target while visiting the set of targets, each target will still receive the event but no stage callbacks will be exewcuted
+    #   - if #abort is called during start callbacks, start will complete and no stage or finish callbacks will be run
+    #   - if #abort is called during a stage callback, the current stage will complete and no other stage or finish callbacks will be run
+    #   - if #abort is called during a finish callback, finish will complete, i.e. calling #abort during a finish callbacks is fairly pointless
+    # @return nil
+    def abort
+      @abort = true
       nil
     end
 
-    def match_type( event_type )
-      event_type = EventType.new event_type unless event_type.is_a? EventType
-      event_type.match @data.types
+    # @return true if #abort has been called, false otherwise
+    def aborted?
+      @abort
     end
 
-    def time
-      @data.time.dup
-    end
-
-    def start(&block)
-      staged_handler Private::START, block if block_given?
-    end
-
-    def before(&block)
-      staged_handler Private::BEFORE, block if block_given?
-    end
-
-    def before_success(&block)
-      staged_handler Private::BEFORE_SUCCESS, ->e{ block.call e if e.success? } if block_given?
+    # Add targets to this event. May not be called after or during #dispatch
+    # @param targets - zero or more EventTarget objects to add to this event
+    # @return nil
+    def target *targets
+      raise "Event#target is disallowed after Event#dispatch is called" unless @state == :ready
+      targets.each { |target| @targets << target }
+      nil
     end
 
-    def before_failure(&block)
-      staged_handler Private::BEFORE_FAILURE, ->e{ block.call e unless e.success? } if block_given?
+    # Add event types to this event. May not be called after or during #dispatch
+    # @param types - zero or more types to add to this Event. The Event is simultaneously all of these types
+    # @return nil
+    def type *event_types
+      raise "Event#type is disallowed after Event#dispatch is called" unless @state == :ready
+      event_types.each { |type| @types << type }
+      nil
     end
 
-    def success(&block)
-      staged_handler Private::SUCCESS, ->e{ block.call e if e.success? } if block_given?
+    # Add the passed new stage to this event
+    # @param new_stage - a stage to add to this event
+    # @block - a block with a single parameter |event|; during #dispatch, this block will be called with self immediately prior to executing new_stage's callbacks. new_stage and its callbacks will be skipped (not executed) if this block returns falsy.
+    # @return nil
+    def add_stage new_stage, &stage_decision_block
+      raise "Event#add_stage is disallowed after Event#dispatch is called" unless @state == :ready
+      @stages << new_stage
+      @stage_callbacks[new_stage] ||= []
+      @stage_decision_blocks[new_stage] = stage_decision_block if block_given?
+      nil
     end
 
-    def failure(&block)
-      staged_handler Private::FAILURE, ->e{ block.call e unless e.success? } if block_given?
+    # Return true if this event's types match the passed EventType
+    # @param event_type - an EventType to match against this event's types
+    # @return true or false - result of passed EventType#match on this event's types
+    def match_type? event_type
+      event_type = EventType.new event_type unless event_type.is_a? EventType
+      event_type.match @types
     end
 
-    def after_success(&block)
-      staged_handler Private::AFTER_SUCCESS, ->e{ block.call e if e.success? } if block_given?
+    # Bind the passed block as a callback for the passed stage
+    # @param stage - a stage which has been added using #add_stage
+    # @block - a callback receiving a single parameter, |event|, which will be added to stage's callbacks
+    # @return nil
+    def bind stage, &block
+      @stage_callbacks[stage] << block if block_given?
+      nil
     end
 
-    def after_failure(&block)
-      staged_handler Private::AFTER_FAILURE, ->e{ block.call e unless e.success? } if block_given?
+    # Bind the passed block as a start callback
+    # @block - a callback receiving a single parameter, |event|, which will be added to the start callbacks
+    # @return nil
+    def start &block
+      @start_callbacks << block if block_given?
+      nil
     end
 
-    def after(&block)
-      staged_handler Private::AFTER, block if block_given?
+    # Bind the passed block as a finish callback
+    # @block - a callback receiving a single parameter, |event|, which will be added to the finish callbacks
+    # @return nil
+    def finish &block
+      @finish_callbacks << block if block_given?
+      nil
     end
 
-    def finish(&block)
-      staged_handler Private::FINISH, block if block_given?
+    private
+    # Used in #dispatch, run callbacks that match our types on each target in the target closure
+    def run_target_callbacks
+      collect_targets.each do |target|
+        target.each_matching_callback(@types) { |callback| callback.call self }
+      end
     end
 
-    private
-    def staged_handler( stage, block )
-      @data.staged_handlers[stage] ||= []
-      @data.staged_handlers[stage] << block
-      nil
+    # Used in #dispatch, run the stage callbacks on this event; to be run after each target had a chance to append callbacks
+    # Callback execution order:
+    #  start callbacks
+    #  stage callabcks - in the order stages were added
+    #  finish callbacks
+    # Callbacks in the same stage have arbitrary execution order
+    def run_stage_callbacks
+      return if @abort
+      @start_callbacks.each { |block| block.call self }
+      @stages.each do |stage|
+        return if @abort
+        next if @stage_decision_blocks.key? stage and not @stage_decision_blocks[stage].call self
+        @stage_callbacks[stage].each { |block| block.call self }
+      end
+      return if @abort
+      @finish_callbacks.each { |block| block.call self }
     end
 
+    # Compute the target closure, equal to the set of targets on this event and their observers (and recursive observers)
     def collect_targets
-      targets_working = [@data.target]
-      targets_final = []
-      while t = targets_working.shift do
-        targets_final << t
-        targets_working.concat t.parents if t.respond_to? :parents
-      end
-      targets_final.uniq
+      all_targets = @targets.dup # @targets must remain the original set of targets on this event, and all_targets will be mutated.  NOTE: @targets isn't actually used after collect_targets() is called, so we might remove the .dup()
+      observers = Set.new
+      begin
+        original_size = all_targets.size
+        all_targets.each { |target| observers.merge target.observers }
+        all_targets.merge observers
+      end while all_targets.size != original_size
+      all_targets
     end
   end
 end

data/lib/seh/event_bind.rb

@@ -0,0 +1,15 @@
+require_relative 'event_type'
+
+module Seh
+  # @private
+  # Internal use only. Container for an event_type,block pair bound to an EventTarget. Converts event_type into a Seh::EventType
+  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
+end