eventful 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+=== 1.0.0 / 2009-06-18
+
+* Initial release
+

data/Manifest.txt

@@ -0,0 +1,6 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/eventful.rb
+test/test_eventful.rb

data/README.txt

@@ -0,0 +1,124 @@
+= Eventful
+
+* http://github.com/jcoglan/eventful
+
++Eventful+ is a small extension on top of Ruby's +Observable+ module that
+implements named events, block listeners and event bubbling. It allows
+much more flexible event handling behaviour than is typically allowed
+by +Observable+, which requires listeners to be objects that implement
++update+ and provides no simple way of calling subsets of observers based
+on event type.
+
+
+== Installation
+
+  sudo gem install eventful
+
+
+== Examples
+
+Make a class listenable by mixing +Eventful+ into it:
+
+  class Watcher
+    include Eventful
+  end
+
+Register event listeners using +on+ with an event name and a block.
+Publish events using +fire+ with the event name. The block accepts
+the object that published the event, along with any parameters passed
+to +fire+.
+
+  w = Watcher.new
+  
+  w.on(:filechange) { |watcher, path| puts path }
+  w.on(:filedelete) { |watcher, path| puts "#{ watcher } deleted #{ path }" }
+  
+  w.fire(:filechange, '/path/to/file.txt')
+  w.fire(:filedelete, '/tmp/pids/event.pid')
+  
+  # prints...
+  # /path/to/file.txt
+  # #<Watcher:0xb7b485a4> deleted /tmp/pids/event.pid
+
+The +on+ method returns the +Observer+ object used to represent the listener,
+so you can remove it using +delete_observer+.
+
+  obs = w.on(:filechange) { |watcher| ... }
+  
+  # listener will not fire after this
+  w.delete_observer(obs)
+
+
+=== Method chains instead of blocks
+
+Instead of passing a block, you can add behaviour to objects by chaining
+method calls after the +on+ call. For example:
+
+  class Logger
+    include Eventful
+    
+    def print(message)
+      puts message
+    end
+  end
+  
+  log = Logger.new
+  log.on(:receive).print "Received message"
+  
+  # Calls `log.print "Received message"`
+  log.fire(:receive)
+
+
+=== Events that bubble
+
+When you +fire+ an event, the event 'bubbles' up the type system. What
+this means is that you can listen to events on all the instances of a
+class just by placing an event listener on the class itself. As above,
+the listener is called with the instance that fired the event.
+
+  Logger.on(:receive) { |log, msg| puts "#{ log } :: #{ msg }" }
+  
+  l1, l2 = Logger.new, Logger.new
+  
+  l1.fire(:receive, 'The first message')
+  l2.fire(:receive, 'Another event')
+  
+  # prints...
+  # #<Logger:0xb7bf103c> :: The first message
+  # #<Logger:0xb7bf1028> :: Another event
+
+Method chains can also be used, and they will be replayed on the instance
+that initiated the event.
+
+  # Calls `log.print "Received message"`
+  
+  Logger.on(:receive).print "Received message"
+  
+  log = Logger.new
+  log.fire(:receive)
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009 James Coglan
+
+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,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'eventful' do |p|
+  # self.rubyforge_name = 'eventfulx' # if different than 'eventful'
+  p.developer('James Coglan', 'jcoglan@googlemail.com')
+  p.extra_deps = %w[methodphitamine]
+end
+
+# vim: syntax=ruby

data/lib/eventful.rb

@@ -0,0 +1,108 @@
+require 'observer'
+require 'rubygems'
+require 'methodphitamine'
+
+# Adds named event publishing capabilities to the class that includes it.
+# Actually composed of three modules: +Observable+ (from Ruby stdlib),
+# +ObservableWithBlocks+, and +Eventful+ itself. See +README+ for examples.
+module Eventful
+  VERSION = '1.0.0'
+  
+  # The +Observer+ class is used to wrap blocks in an object that implements
+  # +update+, so it can be used with +Observable+. It extends <tt>Methodphitamine::It</tt>,
+  # meaning it can store any methods called on it and replay them later on any
+  # object. This is used to implement blockless event handlers.
+  class Observer < Methodphitamine::It
+    # Initalize using a block. The block will be called when the observed
+    # object sends notifications.
+    def initialize(&block)
+      super()
+      @block = block
+    end
+    
+    # Called by the observed object inside +Observable+ to publish events.
+    def update(*args)
+      @block.call(*args)
+    end
+    
+    # Patch these back in after Methodphitamine removes them. They are
+    # needed for +Observable+ to handle the object properly.
+    %w[respond_to? hash send].each do |sym|
+      define_method(sym) do |*args|
+        Object.instance_method(sym).bind(self).call(*args)
+      end
+    end
+  end
+  
+  # Extends the +Observable+ module and allows it to accept blocks as observers.
+  # This is a distinct module because I often want to do this without using
+  # named events.
+  module ObservableWithBlocks
+    include Observable
+    
+    # Adds an observer to the object. The observer may be an object implementing
+    # +update+, or a block that will be called when the object notifies observers.
+    # If a block is passed, we return the wrapping +Observer+ object so it can
+    # removed using +delete_observer+.
+    def add_observer(*args, &block)
+      return super unless block_given?
+      observer = Observer.new(&block)
+      add_observer(observer)
+      observer
+    end
+  end
+  
+  # Mix in block observer support
+  include ObservableWithBlocks
+  
+  # Registers a named event handler on the target object that will only fire
+  # when the object publishes events with the given name. The handler should
+  # be a block that will accept the object that fired the event, along with
+  # and data published with the event. Returns a <tt>Methodphitamine::It</tt>
+  # instance that will be replayed on the publishing object when the event fires.
+  #
+  # See +README+ for examples.
+  def on(event, &block)
+    observer = add_observer do |*args|
+      type, data = args[1], [args[0]] + args[2..-1]
+      if type == event
+        block ||= observer.to_proc
+        block.call(*data)
+      end
+    end
+  end
+  
+  # Fires a named event on the target object. The first argument should be a
+  # symbol representing the event name. Any subsequent arguments are passed
+  # listeners along with the publishing object. The event bubbles up the type
+  # system so that you can listen to all objects of a given type by regsitering
+  # listeners on their class.
+  def fire(*args)
+    return self if defined?(@observer_state) and not @observer_state
+    
+    receiver = (Hash === args.first) ? args.shift[:receiver] : self
+    args = [receiver] + args
+    
+    changed(true)
+    notify_observers(*args)
+    changed(true)
+    
+    args[0] = {:receiver => receiver}
+    self.class.ancestors.grep(Eventful).each &it.fire(*args)
+    
+    self
+  end
+  
+  # Classes that +include+ +Eventful+ are also extended with it, so that event
+  # listeners can be registered on a class to fire whenever an instance of
+  # that class publishes an event.
+  def self.included(base)
+    base.extend(self)
+  end
+  
+  # Extend +Eventful+ with itself so you can listen to all eventful objects
+  # using <tt>Eventful.on(:eventname) { handle_event() }</tt>.
+  extend(self)
+  
+end
+

data/test/test_eventful.rb

@@ -0,0 +1,85 @@
+require "test/unit"
+require "eventful"
+require "set"
+
+class Foo
+  include Eventful
+  attr_reader :count
+  
+  def initialize
+    @count = 0
+  end
+  
+  def bump!(x = 1)
+    @count += x
+  end
+end
+
+class Bar
+  include Eventful
+end
+
+class TestEventful < Test::Unit::TestCase
+  def setup
+    [Foo, Bar, Eventful].each &it.delete_observers
+  end
+  
+  def test_named_events
+    ayes, noes = 0, 0
+    f = Foo.new
+    f.on(:aye) { |foo, x| ayes += x }
+    obs = f.on(:noe) { |foo, x| noes += x }
+    
+    f.fire(:aye, 1)
+    assert_equal 1, ayes
+    assert_equal 0, noes
+    f.fire(:noe, 3)
+    assert_equal 1, ayes
+    assert_equal 3, noes
+    
+    f.delete_observer(obs)
+    f.fire(:noe, 3)
+    assert_equal 1, ayes
+    assert_equal 3, noes
+  end
+  
+  def test_chaining
+    f = Foo.new
+    f.on(:aye).bump! 2
+    f.on(:noe).bump! -1
+    
+    2.times { f.fire(:aye) }
+    f.fire(:noe)
+    
+    assert_equal 3, f.count
+  end
+  
+  def test_bubbling
+    bar1, bar2 = Bar.new, Bar.new
+    list = []
+    Bar.on(:aye) { |r| list << r }
+    Eventful.on(:aye) { |r| list << r }
+    Eventful.on(:noe) { |r| list << r }
+    
+    bar1.fire(:aye)
+    assert_equal  [bar1, bar1], list
+    bar2.fire(:noe)
+    assert_equal  [bar1, bar1, bar2], list
+    
+    Bar.fire(:aye)
+    assert_equal  [bar1, bar1, bar2, Bar], list
+    Bar.fire(:noe)
+    assert_equal  [bar1, bar1, bar2, Bar], list
+  end
+  
+  def test_chaining_on_bubble
+    f1, f2 = Foo.new, Foo.new
+    Foo.on(:aye).bump! 5
+    f1.fire(:aye)
+    assert_equal 5, f1.count
+    assert_equal 0, f2.count
+    f2.fire(:aye)
+    assert_equal 5, f1.count
+    assert_equal 5, f2.count
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: eventful
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- James Coglan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-18 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: methodphitamine
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.0
+    version: 
+description: ""
+email: 
+- jcoglan@googlemail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/eventful.rb
+- test/test_eventful.rb
+has_rdoc: true
+homepage: http://github.com/jcoglan/eventful
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+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: eventful
+rubygems_version: 1.3.3
+signing_key: 
+specification_version: 3
+summary: ""
+test_files: 
+- test/test_eventful.rb