onfire 0.1.2 → 0.2.0

data/CHANGES.textile

@@ -1,3 +1,10 @@
+h2. 0.2.0
+
+h3. Changes
+  * Bubbling now happens in Event. Removed Onfire#bubble_event and friends. This is a lot more flexible and simpler.
+  * Changed option for @#on@: @:do@ is now @:call@.
+
+
 h2. 0.1.2
 
 h3. Changes

data/lib/onfire.rb

@@ -2,54 +2,60 @@ require 'onfire/event'
 require 'onfire/event_table'
 
 module Onfire
+  # Attachs an event observer to the receiver which is called by a matching event.
+  #
+  # The handler might be a block receiving the triggering event.
+  #
+  #   matz.on :applaus do |evt|
+  #     puts "grin"
+  #   end
+  #
+  # You can also pass a callable object as handler.
+  #
+  #   class GrinHandler
+  #     def call(evt)
+  #       puts "grin"
+  #     end
+  #   end
+  #
+  #   matz.on :applaus, :do => GrinHandler.new
+  #
+  # The +:from+ option allows conditional filtering.
+  # 
+  #   matz.on :applaus, :from => audience do |evt|
+  #
+  # This handler is called only if +audience+ trigger the +:applaus+ event.
   def on(event_type, options={}, &block)
-    table_options = {}
-    table_options[:event_type]  = event_type
-    table_options[:source_name] = options[:from] if options[:from]
+    options[:event_type] = event_type
     
-    if block_given?
-      return attach_event_handler(block, table_options)
-    end
-    
-    attach_event_handler(options[:do], table_options)
+    event_table.add_handler(block || options[:call], options)
   end
   
+  # Fires an event which will bubble up starting from the receiver. While bubbling,
+  # the events checks the traversed object for matching observers and calls the handlers
+  # in the order they were attached.
+  #
+  # Notice that you can append payload data to the event object.
+  #    
+  #   fire :click, :time => Time.now
+  #
+  # The payload is accessable in the +data+ attribute.
+  #
+  #   evt.data[:time] # => 2011-03-12 11:25:57 +0100
   def fire(event_type, data={})
-    bubble_event event_for(event_type, self, data)
-  end
-  
-  def bubble_event(event)
-    process_event(event) # locally process event, then climb up.
-    return if root?
-    
-    parent.bubble_event(event)
-  end
-  
-  def process_event(event)
-    local_event_handlers(event).each do |proc|
-      return if event.stopped?
-      proc.call(event)
-    end
-  end
-  
-  def root?
-    !parent
+    event_for(event_type, self, data).bubble!
   end
   
   def event_table
     @event_table ||= Onfire::EventTable.new
   end
-    
-protected
-  def attach_event_handler(proc, table_options)
-    event_table.add_handler(proc, table_options)
-  end
   
-  # Get all handlers from self for the passed event.
-  def local_event_handlers(event)
+  # Get all handlers from self for the passed event (interface for Event).
+  def handlers_for_event(event)
     event_table.all_handlers_for(event.type, event.source)
   end
   
+protected
   # Factory method for creating the event. Override if you want your own event.
   def event_for(*args)
     Event.new(*args)

data/lib/onfire/debugging.rb

@@ -0,0 +1,37 @@
+module Onfire
+  class Event
+    module Debugging
+      def self.included(base)
+        base.extend ClassMethods
+      end
+      
+      module ClassMethods
+        # Blocks added with #debug are executed on every node while traversing up.
+        #
+        #   Event.debug do |node, evt|
+        #     puts "traversing #{node}"
+        #   end
+        def debug(&block)
+          debug_blocks << block
+        end
+        
+        def debug_blocks
+          @debug_blocks ||= []
+        end
+      end
+      
+      def process_node(node)
+        self.class.debug_blocks.each do |debugger|
+          debugger.call(node, self, node.handlers_for_event(self))
+        end
+        
+        super
+      end
+      
+      # Currently unused.
+      def call_handler(proc, node)
+        super
+      end
+    end
+  end
+end

data/lib/onfire/event.rb

@@ -1,11 +1,12 @@
 module Onfire
-  # An Event is born in #fire and is passed up the ancestor chain of the triggering datastructure.
-  # It carries a <tt>type</tt>, the fireing widget <tt>source</tt> and arbitrary payload <tt>data</tt>.
+  # An event carries a type, source, and optional payload. Calling #bubble! it starts at 
+  # its source and traverses up the hierarchy using #parent. 
+  # On every node it calls #handlers_for_event on the node while calling returned procs.
   class Event
     
     attr_accessor :type, :source, :data
     
-    def initialize(type=nil, source=nil, data=nil)
+    def initialize(type, source, data=nil)
       @type       = type
       @source     = source
       @data       = data
@@ -20,12 +21,25 @@ module Onfire
       @stopped = true
     end
     
-    ### FIXME: what about serialization? should we simply forget the source?
-    def _dump(depth)
-      ""
-    end
-    def self._load(str)
-      ::Onfire::Event.new
+    module ProcessingMethods
+      def bubble!
+        node = source
+        # in a real visitor pattern, the visited would call #process_node.
+        begin process_node(node) end while node = node.parent
+      end
+      
+      def process_node(node)
+        node.handlers_for_event(self).each do |proc|
+          return if stopped?
+          call_handler(proc, node)
+        end
+      end
+      
+      def call_handler(proc, node)
+        proc.call(self)
+      end
     end
+    
+    include ProcessingMethods
   end
 end

data/lib/onfire/event_table.rb

@@ -9,7 +9,7 @@ module Onfire
     
     def add_handler(handler, opts)
       event_type    = opts[:event_type]
-      source_name   = opts[:source_name] || nil
+      source_name   = opts[:from] || nil
       
       handlers_for(event_type, source_name) << handler
     end

data/lib/onfire/version.rb

@@ -1,3 +1,3 @@
 module Onfire
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/test/debugging_test.rb

@@ -0,0 +1,56 @@
+require 'test_helper'
+require 'onfire/debugging'
+
+class DebuggingTest < Test::Unit::TestCase
+  attr_reader :list
+  
+  context "mixing in the Debugging module" do
+    setup do
+      @barkeeper  = mock('barkeeper')
+      @guest      = mock('guest')
+      @guest.parent = @barkeeper
+      
+      
+      @evt_class = Class.new(Onfire::Event)
+      @evt_class.class_eval do
+        include Onfire::Event::Debugging
+      end
+    end
+    
+    context ".debug" do
+      should "set debug_event_blocks" do
+        @proc_1 = Proc.new {}
+        @proc_2 = Proc.new {}
+        
+        @evt_class.debug &@proc_1
+        @evt_class.debug &@proc_1
+        
+        assert_equal [@proc_1, @proc_2], @evt_class.debug_blocks
+      end
+    end
+    
+    context "#bubble!" do
+      setup do
+        @list = ""
+        @evt_class.debug do |node, evt|
+          list << "@ #{node.name} with event type #{evt.type}"
+        end
+      end
+      
+      should "be invoked at every node" do
+        @evt_class.new(:cheers, @barkeeper).bubble!
+        
+        assert_equal "@ barkeeper with event type cheers", list
+      end
+      
+      should "call the debug blocks at every processing step" do
+        @guest.on :cheers do
+          list << " | Cheers!"
+        end
+        @evt_class.new(:cheers, @guest).bubble!
+        
+        assert_equal "@ guest with event type cheers | Cheers!@ barkeeper with event type cheers", @list
+      end
+    end
+  end
+end

data/test/event_table_test.rb

@@ -8,17 +8,17 @@ class EventTableTest < Test::Unit::TestCase
     end
     
     should "return an empty array when it can't find handlers" do
-      @head.add_handler :drink, :source_name => :stomach, :event_type => :thirsty
+      @head.add_handler :drink, :from => :stomach, :event_type => :thirsty
       
       assert_equal [], @head.handlers_for(    :hungry, :stomach)
       assert_equal [], @head.all_handlers_for(:hungry, :stomach)
     end
     
     should "return handlers in the same order as they were added" do
-      @head.add_handler :drink,         :source_name => :stomach, :event_type => :hungry
-      @head.add_handler :eat,           :source_name => :stomach, :event_type => :hungry
-      @head.add_handler :sip,           :source_name => :mouth,   :event_type => :dry
-      @head.add_handler :have_desert,                             :event_type => :hungry
+      @head.add_handler :drink,         :from => :stomach,  :event_type => :hungry
+      @head.add_handler :eat,           :from => :stomach,  :event_type => :hungry
+      @head.add_handler :sip,           :from => :mouth,    :event_type => :dry
+      @head.add_handler :have_desert,                       :event_type => :hungry
       
       assert_equal [:sip], @head.handlers_for(:dry, :mouth)
       assert_equal [:sip], @head.all_handlers_for(:dry, :mouth)

data/test/event_test.rb

@@ -2,7 +2,7 @@ require 'test_helper'
 
 class EventTest < Test::Unit::TestCase
   context "An event" do
-    should "accept its type and source in the constructor" do
+    should "accept type and source in the constructor" do
       event = Onfire::Event.new(:click, :source)
       
       assert_equal :click,  event.type
@@ -10,14 +10,6 @@ class EventTest < Test::Unit::TestCase
       assert_nil  event.data
     end
     
-    should "be fine without any parameters at all" do
-      event = Onfire::Event.new
-      
-      assert_nil  event.type
-      assert_nil  event.source
-      assert_nil  event.data
-    end
-    
     should "accept payload data" do
       event = Onfire::Event.new(:drag, :source, :target => 'me')
       
@@ -27,7 +19,7 @@ class EventTest < Test::Unit::TestCase
     end
     
     should "stop if needed" do
-      event = Onfire::Event.new
+      event = Onfire::Event.new(:drag, :source)
       
       assert ! event.stopped?
       event.stop!
@@ -35,3 +27,103 @@ class EventTest < Test::Unit::TestCase
     end
   end
 end
+  
+class EventFunctionalTest < Test::Unit::TestCase
+  context "#bubble!" do
+    setup do
+      @guest      = mock('guest')
+      @barkeeper  = mock("barkeeper")
+      @event      = Onfire::Event.new(:cheers, @guest)
+      @event.data = {:list => []}
+    end
+    
+    should "visit a root source without handlers" do
+      @event.bubble!
+      assert_equal [], @event.data[:list]
+    end
+    
+    should "visit the source with multiple handlers when it's root" do
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "yo"
+      end
+      
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "man"
+      end
+      
+      @event.bubble!
+      assert_equal ["yo", "man"], @event.data[:list]
+    end
+    
+    should "call appropriate handlers, only" do
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "yo"
+      end
+      
+      @guest.on :drink do |evt|
+        evt.data[:list] << "yummy"
+      end
+      
+      @event.bubble!
+      assert_equal %w(yo), @event.data[:list]
+    end
+    
+    should "visit all elements in the path" do
+      @guest.parent = @barkeeper
+      
+      @barkeeper.on :cheers do |evt|
+        evt.data[:list] << "Thanks!" 
+      end
+      
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "yo!"
+      end
+      
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "Cheers!"
+      end
+      
+      @event.bubble!
+      assert_equal %w(yo! Cheers! Thanks!), @event.data[:list]
+    end
+    
+    should "invoke handlers in correct order when having nested triggers" do
+      list = []
+      @guest.parent = @barkeeper
+      
+      @guest.on :cheers do
+        list << 'Cheers!'
+        @guest.fire :order
+      end
+      @guest.on :cheers do
+        list << 'Hey!'
+      end
+      @barkeeper.on :cheers do
+        list << 'Thanks.'
+      end
+      @barkeeper.on :order do
+        list << 'Enjoy.'
+      end
+      
+      @event.bubble!
+      
+      assert_equal %w(Cheers! Enjoy. Hey! Thanks.), list
+    end
+    
+    should "not invoke any handler after being stopped" do
+      @guest.parent = @barkeeper
+      
+      @barkeeper.on :cheers do |evt|
+        evt.data[:list] << "Thanks!" 
+      end
+      
+      @guest.on :cheers do |evt|
+        evt.data[:list] << "yo!"
+        evt.stop!
+      end
+      
+      @event.bubble!
+      assert_equal %w(yo!), @event.data[:list]
+    end
+  end
+end

data/test/onfire_test.rb

@@ -1,21 +1,6 @@
 require 'test_helper'
 
 class OnfireTest < Test::Unit::TestCase
-  def mock(name='my_mock')
-    obj = Class.new do
-      attr_accessor :list
-      attr_accessor :name
-      attr_accessor :parent
-      
-      include Onfire
-      
-      def initialize(name)
-        @name = name
-        @list = []
-      end
-    end.new(name)
-  end
-  
   context "including Onfire" do
     should "provide event_table accessors to an emtpy table" do
       table = mock.event_table
@@ -24,74 +9,6 @@ class OnfireTest < Test::Unit::TestCase
     end
   end
   
-  context "#process_event" do
-    setup do
-      @event = Onfire::Event.new(:click, mock)
-    end
-    
-    
-    should "not fill #list as there are no event handlers attached" do
-      obj = mock
-      obj.process_event(@event)
-      
-      assert_equal [], obj.list
-    end
-    
-    should "invoke exactly one proc and thus push `1` onto #list" do
-      obj = mock
-      obj.event_table.add_handler(lambda { |evt| obj.list << 1 }, :event_type => :click)
-      
-      obj.process_event(@event)
-      
-      assert_equal [1], obj.list
-    end
-    
-    should "not invoke procs for another event_type" do
-      obj = mock
-      obj.event_table.add_handler(lambda { |evt| obj.list << 1 }, :event_type => :click)
-      obj.event_table.add_handler(lambda { |evt| obj.list << 2 }, :event_type => :drop) # don't call me!
-      
-      obj.process_event(@event)
-      
-      assert_equal [1], obj.list
-    end
-  end
-  
-  context "calling #on" do
-    setup do
-      @obj    = mock
-      @event  = Onfire::Event.new(:click, @obj)
-    end
-    
-    context "with a block" do
-      should "add a handler to the event_table when called with a block" do
-        @obj.on :click do
-          @obj.list << 1
-        end
-        
-        @obj.process_event(@event)
-        assert_equal [1], @obj.list
-      end
-      
-      should "invoke two handlers if called twice" do
-        @obj.on :click do @obj.list << 1 end
-        @obj.on :click do @obj.list << 2 end
-        
-        @obj.process_event(@event)
-        assert_equal [1,2], @obj.list
-      end
-      
-      should "receive the triggering event as parameter" do
-        @obj.on :click do |evt|
-          @obj.list << evt
-        end
-        
-        @obj.process_event(@event)
-        assert_equal [@event], @obj.list
-      end
-    end
-  end
-  
   context "In the bar" do
     setup do
       @barkeeper   = mock('barkeeper')
@@ -146,14 +63,14 @@ class OnfireTest < Test::Unit::TestCase
           @callable.instance_eval do
             def call(event)
               source = event.source
-              return source.list << 'order from barkeeper' if source.root?
+              return source.list << 'order from barkeeper' unless source.parent
               source.parent.list << 'order from guest'
             end
           end
         end
         
         should "add a handler to the local event_table" do
-          @barkeeper.on :order, :do => @callable
+          @barkeeper.on :order, :call => @callable
           
           @barkeeper.fire :order
           assert_equal ['order from barkeeper'], @barkeeper.list
@@ -165,21 +82,6 @@ class OnfireTest < Test::Unit::TestCase
     end
     
     
-    context "stopping events" do
-      should "not invoke any handler after the guest kills it" do
-        @nice_guest.on(:order) {@nice_guest.list << 'thirsty?'}
-        @nice_guest.on(:order) do |evt|
-          @nice_guest.list << 'money?'
-          evt.stop!
-        end
-        @barkeeper.on(:order)  {@nice_guest.list << 'draw a beer'}
-        @nice_guest.fire :order
-        
-        assert_equal ['thirsty?', 'money?'], @nice_guest.list
-      end
-    end
-    
-    
     context "#event_table" do
       should "expose the EventTable to the public" do
         assert_kind_of ::Onfire::EventTable, @barkeeper.event_table
@@ -193,12 +95,6 @@ class OnfireTest < Test::Unit::TestCase
       @obj = mock
     end
     
-    should "be of no relevance when there are no handlers attached" do
-      @obj.fire :click
-      
-      assert_equal [], @obj.list
-    end
-    
     should "invoke the attached matching handler" do
       @obj.on :click do @obj.list << 1 end
       @obj.fire :click
@@ -213,32 +109,6 @@ class OnfireTest < Test::Unit::TestCase
       assert_equal [], @obj.list
     end
     
-    
-    should "invoke handlers in the correct order when bubbling" do
-      # we use @obj for recording the chat.
-      bar   = mock('bar')
-      guest = mock('guest')
-      
-      guest.parent = bar
-      guest.on :thirsty do
-        @obj.list << 'A beer!'
-        guest.fire :order
-      end
-      guest.on :thirsty do
-        @obj.list << 'Hurry up, man!'
-      end
-      bar.on :thirsty do
-        @obj.list << 'Thanks.'
-      end
-      bar.on :order do
-        @obj.list << 'There you go.'
-      end
-      
-      guest.fire :thirsty
-      
-      assert_equal ['A beer!', 'There you go.', 'Hurry up, man!', 'Thanks.'], @obj.list
-    end
-    
     should "allow appending arbitrary data to the event" do
       # we use @obj for recording the chat.
       bar   = mock('bar')
@@ -282,21 +152,4 @@ class OnfireTest < Test::Unit::TestCase
       end
     end
   end
-  
-  
-  context "#root?" do
-    setup do
-      @obj    = mock
-    end
-    
-    should "return false if we got parents" do
-      @obj.parent = :daddy
-      assert !@obj.root?
-    end
-    
-    should "return true if we're at the top" do
-      assert @obj.root?
-    end
-  end
-  
 end

data/test/test_helper.rb

@@ -8,4 +8,19 @@ class Onfire::EventTable
       memo + evts[1].inject(0) {|sum, h| sum + h[1].size} # h => [key, value].
     end || 0
   end
-end
+end
+
+class Test::Unit::TestCase
+  def mock(name='my_mock')
+    obj = Class.new do
+      include Onfire
+      
+      attr_accessor :list, :name, :parent
+      
+      def initialize(name)
+        @name = name
+        @list = []
+      end
+    end.new(name)
+  end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Nick Sutterer
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-08 00:00:00 +01:00
+date: 2011-03-12 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -33,10 +33,12 @@ files:
 - README.textile
 - Rakefile
 - lib/onfire.rb
+- lib/onfire/debugging.rb
 - lib/onfire/event.rb
 - lib/onfire/event_table.rb
 - lib/onfire/version.rb
 - onfire.gemspec
+- test/debugging_test.rb
 - test/event_table_test.rb
 - test/event_test.rb
 - test/onfire_test.rb