onfire 0.1.0

data/README.textile

@@ -0,0 +1,231 @@
+h1. Onfire
+
+_Have bubbling events and observers in all your Ruby objects._
+
+
+h2. Introduction
+
+If you think "bubbling events" sounds awesome and should definitly be used in your project, you're lame. However, if you answer "yes" to at least one of the following requirements you're in. If not, go and use Ruby's great @Observable@ mixin.
+
+*Do you...?*
+* prefer *decoupled systems*, where observers don't wanna know the observed object (as @Observable#add_observer@ requires)?
+* rather intend to *observe _events_*, not business objects alone?
+* have a *tree-like* data structure? Bubbling events only make sense in a hierarchical environment where observers and event sources form a tree.
+* miss a *stop!* command which prevents the event from further propagation? 
+
+h2. Example
+
+Let's assume you have a set of @User@ objects with roles, like "CEO", "Manager", and "Developer". You just decided to implement some messaging system where developers can complain, managers can ignore, and the CEO is trying to control.
+
+<pre>
+    CEO:             bill
+                    |    |
+    Managers:   mike      matz
+                          |  |
+    Developers:        dave  didi  
+</pre>
+
+If _dave_ would complain about a new policy (which implies exclusive usage of Win PCs only) it would bubble up to his manager _matz_ and then to _bill_, who'd fire _dave_ right away.
+
+As _matz_ somehow likes his developers he would try to prevent his boss _bill_ from overhearing the conversation or make the complainment management-compatible. Good guy _matz_.
+
+
+h2. Installation
+
+<pre>
+  $ sudo gem install onfire
+</pre>
+
+
+h2. Usage
+
+First, you extend your @User@ class to be "on fire".
+
+<pre>
+  class User < ...
+    include Onfire
+</pre>
+
+
+As your @User@ objects don't have a tree structure *you* implement *@#parent@*. That's the *only requirement Onfire has* to the class it's mixed into.
+
+*@#parent@* would return the boss object of the asked instance.
+
+<pre>
+  dave.parent      # => matz
+  matz.parent      # => bill
+  bill.parent	   # => nil
+</pre>
+
+There's your hierarchical tree structure.
+
+h2. Fireing events
+
+Now _dave_ issues the bad circumstances in his office:
+
+<pre>
+  dave.fire :thatSucks
+</pre>
+
+So far, nothing would happen as no one in the startup is observing that event.
+
+h2. Responding to events
+
+Anyway, a real CEO should respond to complainments from his subordinates.
+
+<pre>
+  bill.on :thatSucks do puts "who's that?" end
+</pre>
+
+Now _bill_ would at least find out somebody's crying.
+
+<pre>
+  > dave.fire :thatSucks
+  => "who's that?"           # by bill
+</pre>
+
+That's right, the *Onfire API* is just the two public methods 
+* *@#on@* for responding to events and 
+* *@#fire@* for triggering those 
+
+
+h2. Bubbling events
+
+_matz_ being a good manager wants to mediate, so he takes part in the game:
+
+<pre>
+  matz.on :thatSucks do puts "dave, sshhht!" end
+</pre>
+
+Which results in
+
+<pre>
+  > dave.fire :thatSucks
+  => "dave, sshhht!"         # by matz
+  => "who's that?"           # by bill
+</pre>
+
+
+h2. Using the @Event@ object
+
+Of course _bill_ wants to find out who's the subversive element, so he just askes the revealing *Event* object.
+
+<pre>
+  bill.on :thatSucks do |event| event.source.fire! end
+</pre>
+
+That's bad for _dave_, as he's unemployed now.
+
+
+h2. Intercepting events
+
+As _dave_ has always been on time, _matz_ just swallows any offending messages for now.
+
+<pre>
+  matz.on :thatSucks do |event| event.stop! end
+</pre>
+
+That leads to an event that's stopped at _matz_. It won't propagate further up to the big boss.
+
+<pre>
+  > dave.fire :thatSucks
+  => "dave, sshhht!"         # first, by matz
+  => nil                     # second, matz stops the event.
+</pre>
+
+h2. Organic event filtering
+
+What happens if _mike_ wants to be a good manager, too?
+
+<pre>
+  mike.on :thatSucks do puts "take it easy, dude!" end
+</pre>
+
+When _dave_ starts to cry, there's no _mike_ involved:
+
+<pre>
+  > dave.fire :thatSucks
+  => "dave, sshhht!"         # by matz
+  => nil
+</pre>
+
+Obviously, the @:thatSucks@ event triggered by _dave_ never passes _mike_ as he is on a completely different tree branch. The event travels from _dave_ to _matz_ up to _bill_.
+
+That is dead simple, however it is a clear way to observe only *particular events*. When _mike_ calls @#on@ he limits his attention to events from his branch - his developers - only.
+
+h2. Event source filtering
+
+After a while discontent moves over to _didi_.
+
+<pre>
+  > didi.fire :thatSucks
+  => "dave, sshhht!"         # first, by matz
+  => nil
+</pre>
+
+_didi_ is a lamer and _matz_ always prefered working with _dave_ so he changes his tune.
+
+<pre>
+  matz.on :thatSucks do |event| event.stop! if event.source == dave end
+</pre>
+
+That's unfair!
+
+<pre>
+  > dave.fire :thatSucks
+  => "dave, sshhht!"         # by matz
+  => nil                     # dave still got a job.
+  > didi.fire :thatSucks
+  => "fired!"                # didi's event travels up to boss who fires him.
+</pre>
+
+_matz_ is lazy, so he explicity lets Onfire handle the filtering:
+
+<pre>
+  matz.on :thatSucks, :from => dave do |event| event.stop! end
+</pre>
+
+which will result in the same bad outcome for _didi_.
+
+h2. Responding with instance methods
+
+Nevertheless _matz_ is trying to keep himself clean, so he refactors the handler block to an instance method.
+
+<pre>
+  matz.instance_eval do
+    def shield_dave(event)
+      event.stop!
+    end
+  end
+  
+  matz.on :thatSucks, :from => dave, :do => :shield_dave
+</pre>
+
+Awesome shit!
+
+h2. Who's using it?
+* Right now, Onfire is used as clean, small event engine in "Apotomo":http://github.com/apotonick/apotomo, that's stateful widgets for Ruby and Rails.
+
+h2. License
+
+Copyright (c) 2010, Nick Sutterer 
+
+The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,62 @@
+# encoding: utf-8
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), 'lib', 'onfire', 'version')
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the onfire library.'
+Rake::TestTask.new(:test) do |test|
+  test.libs << ['lib', 'test']
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+
+# Gem managment tasks.
+#
+# == Bump gem version (any):
+#
+#   rake version:bump:major
+#   rake version:bump:minor
+#   rake version:bump:patch
+#
+# == Generate gemspec, build & install locally:
+#
+#   rake gemspec
+#   rake build
+#   sudo rake install
+#
+# == Git tag & push to origin/master
+#
+#   rake release
+#
+# == Release to Gemcutter.org:
+#
+#   rake gemcutter:release
+#
+begin
+  gem 'jeweler'
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |spec|
+    spec.name         = "onfire"
+    spec.version      = ::Onfire::VERSION
+    spec.summary      = %{Have bubbling events and observers in all your Ruby objects.}
+    spec.description  = spec.summary
+    spec.homepage     = "http://github.com/apotonick/onfire"
+    spec.authors      = ["Nick Sutterer"]
+    spec.email        = "apotonick@gmail.com"
+
+    spec.files = FileList["[A-Z]*", File.join(*%w[{lib,test} ** *]).to_s]
+
+    # spec.add_dependency 'activesupport', '>= 2.3.0' # Dependencies and minimum versions?
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler - or one of its dependencies - is not available. " <<
+  "Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end

data/lib/onfire/event.rb

@@ -0,0 +1,31 @@
+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>.
+  class Event
+    
+    attr_accessor :type, :source, :data
+    
+    def initialize(type=nil, source=nil, data=nil)
+      @type       = type
+      @source     = source
+      @data       = data
+    end
+    
+    def stopped?
+      @stopped ||= false
+    end
+    
+    # Stop event bubbling.
+    def stop!
+      @stopped = true
+    end
+    
+    ### FIXME: what about serialization? should we simply forget the source?
+    def _dump(depth)
+      ""
+    end
+    def self._load(str)
+      ::Onfire::Event.new
+    end
+  end
+end

data/lib/onfire/event_table.rb

@@ -0,0 +1,27 @@
+module Onfire
+  # Keeps all event handlers attached to one object.
+  class EventTable
+    attr_accessor :source2evt
+    
+    def initialize
+      @source2evt = {}
+    end
+    
+    def add_handler(handler, opts)
+      event_type    = opts[:event_type]
+      source_name   = opts[:source_name] || nil
+      
+      handlers_for(event_type, source_name) << handler
+    end
+    
+    def handlers_for(event_type, source_name=nil)
+      evt_types = source2evt[source_name] ||= {}
+      evt_types[event_type] ||= []
+    end
+    
+    # Returns all handlers, with :from first, then catch-all.
+    def all_handlers_for(event_type, source_name)
+      handlers_for(event_type, source_name) + handlers_for(event_type, nil)
+    end
+  end
+end

data/lib/onfire/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Onfire
+  VERSION = '0.1.0'.freeze
+end

data/lib/onfire.rb

@@ -0,0 +1,52 @@
+require 'onfire/event'
+require 'onfire/event_table'
+
+module Onfire
+  def on(event_type, options={}, &block)
+    table_options = {}
+    table_options[:event_type]  = event_type
+    table_options[:source_name] = options[:from] if options[:from]
+    
+    if block_given?
+      return attach_event_handler(block, table_options)
+    end
+    
+    attach_event_handler(options[:do], table_options)
+  end
+  
+  def fire(event_type)
+    bubble_event Event.new(event_type, self)
+  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
+  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)
+      event_table.all_handlers_for(event.type, event.source)
+    end
+end

data/test/event_table_test.rb

@@ -0,0 +1,30 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class EventTableTest < Test::Unit::TestCase
+
+  context "An EventTable" do
+    setup do
+      @head = Onfire::EventTable.new
+    end
+    
+    should "return an empty array when it can't find handlers" do
+      @head.add_handler :drink, :source_name => :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
+      
+      assert_equal [:sip], @head.handlers_for(:dry, :mouth)
+      assert_equal [:sip], @head.all_handlers_for(:dry, :mouth)
+      
+      assert_equal [:drink, :eat], @head.handlers_for(:hungry, :stomach)
+      assert_equal [:drink, :eat, :have_desert], @head.all_handlers_for(:hungry, :stomach)
+    end
+  end
+end

data/test/event_test.rb

@@ -0,0 +1,28 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class EventTest < Test::Unit::TestCase
+  context "An event" do
+    should "accept its type and source in the constructor" do
+      event = Onfire::Event.new(:click, :source)
+      
+      assert_equal :click,  event.type
+      assert_equal :source, event.source
+    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 "stop if needed" do
+      event = Onfire::Event.new
+      
+      assert ! event.stopped?
+      event.stop!
+      assert event.stopped?
+    end
+  end
+end

data/test/onfire_test.rb

@@ -0,0 +1,260 @@
+require File.dirname(__FILE__) + '/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
+      assert_kind_of Onfire::EventTable, table
+      assert_equal 0, table.size
+    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 { 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{obj.list << 1}, :event_type => :click)
+      obj.event_table.add_handler(lambda{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')
+      @nice_guest  = mock('nice guest')
+      @bad_guest   = mock('bad guest')
+      
+      @nice_guest.parent = @barkeeper
+      @bad_guest.parent  = @barkeeper
+    end
+    
+    context "the #on method" do
+      context "with the :from option for filtering" do
+        setup do
+          @barkeeper.on(:order, :from => @nice_guest) {@barkeeper.list << 'be nice'}
+          @barkeeper.on(:order, :from => @bad_guest)  {@barkeeper.list << 'ignore'}
+          @barkeeper.on(:order, :from => @bad_guest)  {@barkeeper.list << 'throw out'}
+        end
+      
+        should "invoke the handler for the nice guest only" do
+          @nice_guest.fire :order
+          assert_equal ['be nice'], @barkeeper.list
+        end
+        
+        should "invoke both handlers for the bad guest only" do
+          @bad_guest.fire :order
+          assert_equal ['ignore', 'throw out'], @barkeeper.list
+        end
+        
+        should "invoke an additional catch-all handler" do
+          @barkeeper.on(:order) {@barkeeper.list << 'have a drink yourself'}
+          @nice_guest.fire :order
+          assert_equal ['be nice', 'have a drink yourself'], @barkeeper.list
+        end
+        
+        should "invoke another handler when :from is nil" do
+          @barkeeper.on(:order, :from => nil) {@barkeeper.list << 'have a drink yourself'}
+          @nice_guest.fire :order
+          assert_equal ['be nice', 'have a drink yourself'], @barkeeper.list
+        end
+        
+        should "invoke :from handlers before it processes catch-all handlers" do
+          @barkeeper.on(:order)                         {@barkeeper.list << 'have a drink yourself'}
+          @barkeeper.on(:order, :from => @nice_guest)   {@barkeeper.list << 'bring out toast'}
+          @nice_guest.fire :order
+          assert_equal ['be nice', 'bring out toast', 'have a drink yourself'], @barkeeper.list
+        end
+      end
+      
+      context "with a callable object" do
+        setup do
+          @callable = Class.new.new
+          @callable.instance_eval do
+            def call(event)
+              source = event.source
+              return source.list << 'order from barkeeper' if source.root?
+              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.fire :order
+          assert_equal ['order from barkeeper'], @barkeeper.list
+          
+          @nice_guest.fire :order
+          assert_equal ['order from barkeeper', 'order from guest'], @barkeeper.list
+        end
+      end
+    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
+      end
+    end
+    
+  end
+  
+  context "calling #fire" do
+    setup do
+      @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
+      
+      assert_equal [1], @obj.list
+    end
+    
+    should "not invoke same handlers for :symbol or 'string' event names" do
+      @obj.on :click do @obj.list << 1 end
+      @obj.fire 'click'
+      
+      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
+    
+  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

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'shoulda'
+require 'onfire'
+
+class Onfire::EventTable
+  def size
+    source2evt.inject(0)do |memo, evts| 
+      memo + evts[1].inject(0) {|sum, h| sum + h[1].size} # h => [key, value].
+    end || 0
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: onfire
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Nick Sutterer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-19 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Have bubbling events and observers in all your Ruby objects.
+email: apotonick@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- README.textile
+- Rakefile
+- lib/onfire.rb
+- lib/onfire/event.rb
+- lib/onfire/event_table.rb
+- lib/onfire/version.rb
+- test/event_table_test.rb
+- test/event_test.rb
+- test/onfire_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/apotonick/onfire
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Have bubbling events and observers in all your Ruby objects.
+test_files: 
+- test/onfire_test.rb
+- test/test_helper.rb
+- test/event_table_test.rb
+- test/event_test.rb