events 0.9.0

data/lib/events.rb

@@ -0,0 +1,81 @@
+module Events # :nodoc:
+  
+  # The Events::Emitter mixin provides a clone of the Node.js EventEmitter API
+  # for Ruby.
+  # 
+  # Instances of classes including Events::Emitter will emit events, events are
+  # represented by symbols, underscored in the usual Ruby fashion. Examples:
+  # :connection, :data, :message_begin
+  # 
+  # Blocks can be attached to objects to be executed when an event is emitted,
+  # these blocks are called listeners.
+  # 
+  # All EventEmitters emit the event :new_listener when new listeners are added,
+  # this listener is provided with the event and new listener added.
+  # Example:
+  #   server.add_listener(:new_listener) do |event, listener|
+  #     puts "added new listener #{listener} for event #{event}"
+  #   end
+  #   
+  #   server.add_listener(:connection) do |socket|
+  #     puts "someone connected!"
+  #   end
+  # Outputs "added new listener #<Proc:0x0000000000000000@example.rb:12> for
+  # event connection".
+  # 
+  module Emitter
+    
+    # :call-seq: emitter.listeners(event) -> array
+    # 
+    # Returns an array of listeners for the specified event. This array can be
+    # manipulated, e.g. to remove listeners.
+    # 
+    def listeners(event)
+      (@listeners ||= Hash.new {|hash, key| hash[key] = []})[event]
+    end
+    
+    # :call-seq: emitter.emit(event[, arguments...]) -> bool
+    # 
+    # Execute each of the listeners in order with the supplied arguments.
+    # 
+    def emit(event, *args)
+      listeners(event).each do |listener|
+        listener.call(*args)
+      end.any?
+    end
+    
+    # :call-seq: emitter.add_listener(event, &block) -> emitter
+    # 
+    # Adds a listener to the end of the listeners array for the specified event.
+    #   server.add_listener(:connection) do |socket|
+    #     puts "someone connected!"
+    #   end
+    # 
+    def add_listener(event, &block)
+      emit(:new_listener, event, block)
+      listeners(event).push(block)
+      self
+    end
+    
+    # :call-seq: emitter.remove_listener(event, proc) -> emitter
+    # 
+    # Remove a listener from the listener array for the specified event.
+    # 
+    def remove_listener(event, proc)
+      listeners(event).delete(proc)
+      self
+    end
+  end
+  
+  # The Events::EventEmitter class provides a clone of the Node.js EventEmitter
+  # API for Ruby.
+  # 
+  # It simply includes the Events::Emitter module, and is provided as a
+  # convenience for those who wish to inherit from a class.
+  # 
+  # See Events::Emitter for more.
+  # 
+  class EventEmitter
+    include Emitter
+  end
+end

data/readme.rdoc

@@ -0,0 +1,51 @@
+=Events::Emitter
+
+The Events::Emitter mixin provides a clone of the Node.js EventEmitter API for
+Ruby.
+
+Instances of classes including Events::Emitter will emit events, events are
+represented by symbols, underscored in the usual Ruby fashion. Examples:
+:connection, :data, :message_begin
+
+Blocks can be attached to objects to be executed when an event is emitted, these
+blocks are called listeners.
+
+All EventEmitters emit the event :new_listener when new listeners are added,
+this listener is provided with the event and new listener added.
+Example:
+  server.add_listener(:new_listener) do |event, listener|
+    puts "added new listener #{listener} for event #{event}"
+  end
+  
+  server.add_listener(:connection) do |socket|
+    puts "someone connected!"
+  end
+Outputs "added new listener #<Proc:0x0000000000000000@example.rb:12> for event
+connection".
+
+==Events::EventEmitter
+
+The Events::EventEmitter class is provided as a convenience for those who wish
+to inherit from a class. It simply includes the Events::Emitter module.
+
+==Methods
+
+  emitter.add_listener(event, &block)
+
+Adds a listener to the end of the listeners array for the specified event.
+  server.add_listener(:connection) do |socket|
+    puts "someone connected!"
+  end
+
+  emitter.remove_listener(event, proc)
+
+Remove a listener from the listener array for the specified event.
+
+  emitter.listeners(event)
+
+Returns an array of listeners for the specified event. This array can be
+manipulated, e.g. to remove listeners.
+
+  emitter.emit(event[, arguments...])
+
+Execute each of the listeners in order with the supplied arguments.

data/test/event_emitter_test.rb

@@ -0,0 +1,67 @@
+require "test/unit"
+require "../lib/events"
+
+# Tests transliterated from javascript originals at http://github.com/ry/node/
+class TestEventEmitter < Test::Unit::TestCase
+  
+  # /test/simple/test-event-emitter-add-listeners.js
+  def test_event_emitter_add_listeners
+    e = Events::EventEmitter.new
+    
+    events_new_listener_emited = []
+    times_hello_emited = 0
+    
+    e.add_listener(:new_listener) do |event, listener|
+      puts "new_listener: #{event}"
+      events_new_listener_emited.push(event)
+    end
+    
+    e.add_listener(:hello) do |a, b|
+      puts "hello"
+      times_hello_emited += 1
+      assert_equal("a", a)
+      assert_equal("b", b)
+    end
+    
+    puts "start"
+    
+    e.emit(:hello, "a", "b")
+    
+    assert_equal([:hello], events_new_listener_emited)
+    assert_equal(1, times_hello_emited)
+  end
+  
+  # /test/simple/test-event-emitter-modify-in-emit.js
+  def test_event_emitter_modify_in_emit
+    callbacks_called = []
+    
+    e = Events::EventEmitter.new
+    
+    @callback1 = Proc.new do
+      callbacks_called.push(:callback1)
+      e.add_listener(:foo, &@callback2)
+      e.remove_listener(:foo, @callback1)
+    end
+    
+    @callback2 = Proc.new do
+      callbacks_called.push(:callback2)
+      e.remove_listener(:foo, @callback2)
+    end
+    
+    e.add_listener(:foo, &@callback1)
+    assert_equal(1, e.listeners(:foo).length)
+    
+    e.emit(:foo)
+    assert_equal(1, e.listeners(:foo).length)
+    assert_equal([:callback1], callbacks_called)
+    
+    e.emit(:foo)
+    assert_equal(0, e.listeners(:foo).length)
+    assert_equal([:callback1, :callback2], callbacks_called)
+    
+    e.emit(:foo)
+    assert_equal(0, e.listeners(:foo).length)
+    assert_equal([:callback1, :callback2], callbacks_called)
+  end
+  
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: events
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Matthew Sadler
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-07 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: The Events::Emitter mixin provides a clone of the Node.js EventEmitter API for Ruby.
+email: mat@sourcetagsandcodes.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- readme.rdoc
+files: 
+- lib/events.rb
+- test/event_emitter_test.rb
+- readme.rdoc
+has_rdoc: true
+homepage: http://github.com/matsadler/rb-event-emitter
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- readme.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Clone of the node.js EventEmitter api for Ruby
+test_files: 
+- test/event_emitter_test.rb