events 0.9.2 → 0.9.3

data/lib/events.rb

@@ -1,6 +1,19 @@
 module Events # :nodoc:
   UncaughtError = Class.new(StandardError)
   
+  class OnceProxy # :nodoc:
+    attr_reader :event, :caller, :delegate
+    
+    def initialize(event, caller, delegate)
+      @event, @caller, @delegate = event, caller, delegate
+    end
+    
+    def call(*args)
+      caller.remove_listener(event, self)
+      delegate.call(*args)
+    end
+  end
+  
   # The Events::Emitter mixin provides a clone of the Node.js EventEmitter API
   # for Ruby.
   # 
@@ -56,20 +69,38 @@ module Events # :nodoc:
       end.any?
     end
     
-    # :call-seq: emitter.on(event, &block) -> emitter
+    # :call-seq: emitter.on(event) {|args...| block} -> emitter
+    # emitter.on(event, proc) -> emitter
     # 
     # Adds a listener to the end of the listeners array for the specified event.
     #   server.on(:connection) do |socket|
     #     puts "someone connected!"
     #   end
     # 
-    def add_listener(event, &block)
-      emit(:new_listener, event, block)
-      listeners(event).push(block)
+    # Rather than a block, can take a second argument of a Proc (or any object
+    # with a #call method).
+    # 
+    def add_listener(event, proc=nil, &block)
+      emit(:new_listener, event, proc || block)
+      listeners(event).push(proc || block)
       self
     end
     alias on add_listener
     
+    
+    # :call-seq: emitter.once(event) {|args...| block} -> emitter
+    # emitter.once(event, proc) -> emitter
+    # 
+    # Adds a one time listener for the event. The listener is invoked only the
+    # first time the event is fired, after which it is removed.
+    #   server.once(:connection) do |socket|
+    #     puts "Ah, we have our first user!"
+    #   end
+    # 
+    def once(event, proc=nil, &block)
+      add_listener(event, OnceProxy.new(event, self, proc || block))
+    end
+    
     # :call-seq: emitter.remove_listener(event, proc) -> emitter
     # 
     # Remove a listener from the listener array for the specified event.

data/readme.rdoc

@@ -37,6 +37,14 @@ Adds a listener to the end of the listeners array for the specified event.
     puts "someone connected!"
   end
 
+  emitter.once(event, &block)
+
+Adds a one time listener for the event. The listener is invoked only the
+first time the event is fired, after which it is removed.
+  server.once(:connection) do |socket|
+    puts "Ah, we have our first user!"
+  end
+
   emitter.remove_listener(event, proc)
 
 Remove a listener from the listener array for the specified event.

data/test/event_emitter_test.rb

@@ -123,4 +123,44 @@ class TestEventEmitter < Test::Unit::TestCase
     assert_equal([listener2], e3.listeners(:hello))
   end
   
+  # /test/simple/test-event-emitter-once.js
+  def test_event_emitter_once
+    e = Events::EventEmitter.new
+    times_hello_emited = 0
+    
+    e.once(:hello) do |a, b|
+      times_hello_emited += 1
+    end
+    
+    e.emit(:hello, "a", "b")
+    e.emit(:hello, "a", "b")
+    e.emit(:hello, "a", "b")
+    e.emit(:hello, "a", "b")
+    
+    assert_equal(1, times_hello_emited)
+  end
+  
+  # /test/simple/test-event-emitter-num-args.js
+  def test_event_emitter_num_args
+    e = Events::EventEmitter.new
+    num_args_emited = []
+    
+    e.on(:num_args) do |*args|
+      num_args = args.length
+      puts "num_args: #{num_args}"
+      num_args_emited.push(num_args)
+    end
+    
+    puts "start"
+    
+    e.emit(:num_args)
+    e.emit(:num_args, nil)
+    e.emit(:num_args, nil, nil)
+    e.emit(:num_args, nil, nil, nil)
+    e.emit(:num_args, nil, nil, nil, nil)
+    e.emit(:num_args, nil, nil, nil, nil, nil)
+    
+    assert_equal([0, 1, 2, 3, 4, 5], num_args_emited)
+  end
+  
 end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: events
 version: !ruby/object:Gem::Version 
-  version: 0.9.2
+  hash: 61
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 3
+  version: 0.9.3
 platform: ruby
 authors: 
 - Matthew Sadler
@@ -9,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-05 00:00:00 +01:00
+date: 2011-01-30 00:00:00 +00:00
 default_executable: 
 dependencies: []
 
@@ -36,21 +42,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Clone of the node.js EventEmitter api for Ruby