eventually 0.0.1 → 0.1.0

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+coverage

data/README.md

@@ -1,6 +1,6 @@
 # Eventually
 
-`Eventually` is a module that facilitates evented callback management *similar* to the [EventEmitter API](http://nodejs.org/docs/v0.4.7/api/events.html) in NodeJS. Support for Ruby's various lambda-ish callback styles is heavily baked in, so using blocks, lambdas, procs, or event detached methods works out of the box, batteries included. Simply include `Eventually` in the class you will be emitting events from, register some listeners and fire away.
+`Eventually` is a module that facilitates evented callback management *similar* to the [EventEmitter API](http://nodejs.org/docs/v0.4.7/api/events.html) in NodeJS. Support for Ruby's various callback styles is heavily baked in, so using blocks, lambdas, procs, or even detached methods works out of the box, batteries included. Simply include `Eventually` in the class you will be emitting events from, register some listeners and fire away.
 
 ```ruby
 class Car
@@ -36,7 +36,7 @@ The previous snippet acts mostly as documentation.
 
 ## Callback arity validation
 
-However, sometimes you want to be sure that a given registered callback will conform to your event interface, so specify an **arity validation**. Let's add another event to our definition and ensure that callbacks registering for that event must have an arity of 1.
+However, sometimes you want to be sure that a given registered callback will conform to your event interface, so specify an **arity validation**. Let's add another event to our definition and ensure that callbacks registering for that event must have an arity of 1. This will also raise an error if you attempt to emit an event with the wrong argument arity.
 
 ```ruby
 class Car
@@ -74,6 +74,7 @@ car = Car.new
 car.on(:turning) do
   puts 'the car is turning'
 end
+```
 
 *See the **examples/scrict.rb** file for more on this.*
 

data/eventually.gemspec

@@ -20,4 +20,6 @@ Gem::Specification.new do |s|
 
   # specify any dependencies here; for example:
   s.add_development_dependency "rspec"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "simplecov"
 end

data/lib/eventually.rb

@@ -1,4 +1,8 @@
-require "eventually/version"
+require 'eventually/version'
+require 'eventually/event'
+require 'eventually/callable'
+require 'eventually/validation/arity'
+require 'eventually/validation/max_listeners'
 
 # Eventually is a module that facilitates evented callback
 # management similar to the EventEmitter API in NodeJS.
@@ -11,10 +15,13 @@ require "eventually/version"
 module Eventually
   def self.included(base)
     base.extend(ClassMethods)
+    base.emits(:listener_added, :arity => 1)
   end
   
   module ClassMethods
-    NO_CHECK_ARITY = -1
+    NO_CHECK_ARITY = -2
+    DEFAULT_MAX_LISTENERS = 10
+    
     attr_accessor :emittable_events
     
     # Define an event or list of events
@@ -47,6 +54,19 @@ module Eventually
       emittable.key?(evt.to_sym)
     end
     
+    # Return the maximum number of listeners before
+    # we'll start printing memory warnings.
+    # Default max is 10
+    def max_listeners
+      @max_listeners ||= DEFAULT_MAX_LISTENERS
+    end
+    
+    # Set the maximum listener number. Setting this max
+    # to 0 indicates unlimited listeners allowed.
+    def max_listeners= max
+      @max_listeners = max
+    end
+    
     # Puts instances into strict mode. This does two things:
     #   - Raise an error if registering a callback for an event
     #     that has not already been pre-defined (e.g. with #emits)
@@ -62,7 +82,7 @@ module Eventually
       @strict = false
     end
     
-    # Are we strict or not
+    # Report on strict mode
     def strict?
       @strict || false
     end
@@ -86,9 +106,10 @@ module Eventually
     
     # Shorthand predicate to determine if a given event is 
     # "emittable" or "registerable"
-    def can_emit_or_register?(event)
+    def emittable?(event)
       !strict? || emits?(event)
     end
+    alias :registerable? :emittable?
     
     private
     
@@ -102,24 +123,26 @@ module Eventually
   # 
   # Usage: see Eventually#emit or examples directory
   #
-  def on(event, callable=nil, &blk)
-    raise "Event type :#{event} will not be emitted. Use #{self.class.name}.emits(:#{event})" unless self.class.can_emit_or_register?(event)
-    
-    cbk = nil
-    if callable.respond_to?(:call)
-      cbk = callable
-    elsif block_given? && !blk.nil?
-      cbk = blk
-    else
-      raise 'Cannot register callback. Neither callable nor block was given'
-    end
+  def on(evt_name, callable=nil, &blk)
+    evt_name = evt_name.to_sym unless evt_name.is_a?(Symbol)
     
-    # if self.class.validates_arity?(event) && cbk.arity != (expected_arity = self.class.arity_for_event(event))
-    unless valid_event_arity?(event, cbk.arity)
-      raise "Invalid callback arity for event :#{event} (expected #{self.class.arity_for_event(event)}, received #{cbk.arity})"
-    end
+    cb = Eventually::Callable.new(callable, blk)
+    Eventually::Validation::Arity.new(evt_name, self, cb.arity).raise_unless_valid!
+    
+    event = get_event(evt_name)
+    event.add_callable(cb)
+    emit(:listener_added, cb)
     
-    (__registered__[event.to_sym] ||= []) << cbk
+    Eventually::Validation::MaxListeners.new(self).warn_unless_valid!
+    [event, cb]
+  end
+  
+  # Event registration method which will remove the given
+  # callback after it is invoked. See Eventually#on for registration details.
+  def once(event, callable=nil, &blk)
+    event, cb = on(event, callable, &blk)
+    cb.availability = :once
+    [event, cb]
   end
   
   # Emit the payload arguments back to the registered listeners
@@ -141,29 +164,46 @@ module Eventually
   #   end
   #   car.stop # this will indirectly invoke the above callback
   #
-  def emit(event, *payload)
-    raise "Event type :#{event} cannot be emitted. Use #{self.class.name}.emits(:#{event})" unless self.class.can_emit_or_register?(event)
-    
-    unless valid_event_arity?(event, payload.length)
-      raise "Invalid emit arity for event :#{event} (expected #{self.class.arity_for_event(event)}, received #{payload.length})"
-    end
-    
-    (__registered__[event.to_sym] || []).each do |cbk|
-      cbk.call(*payload)
-    end
+  def emit(evt_name, *payload)
+    evt_name = evt_name.to_sym unless evt_name.is_a?(Symbol)
+    event = get_event(evt_name)
+    Eventually::Validation::Arity.new(evt_name, self, payload.length).raise_unless_valid!
+    event.emit(*payload)
+  end
+  
+  # Report the number of listeners across all registered events
+  def num_listeners
+    _events.values.inject(0){|acc, evt| acc + evt.callables.size}
+  end
+  
+  # Report the number of registered listeners for the given event
+  def listeners(event)
+    get_event(event).callables.map(&:callable)
   end
   
-  # Shorthand predicate to determine if the given cbk for this event
-  # has a valid arity amount
-  def valid_event_arity?(event, arity_count)
-    expected_arity = self.class.arity_for_event(event)
-    !self.class.validates_arity?(event) || arity_count == expected_arity
+  # Remove the given listener callback from the given event callback list
+  def remove_listener(event, cbk)
+    get_event(event).remove_callable(cbk)
+  end
+  
+  # Remove all listener callbacks for the given event
+  def remove_all_listeners(event)
+    get_event(event).remove_all_callables
   end
   
   private
   
-  def __registered__
-    @__registered__ ||= {}
+  def _events
+    @_events ||= {}
+  end
+  
+  def get_event(event)
+    evt = _events[event]
+    unless evt
+      evt = Eventually::Event.new(event, self.class.registerable?(event))
+      _events[event] = evt
+    end
+    evt
   end
   
 end

data/lib/eventually/callable.rb

@@ -0,0 +1,34 @@
+require 'forwardable'
+require 'eventually/validation/arity'
+
+module Eventually
+  class Callable
+    extend Forwardable
+    attr_reader :callable
+    attr_accessor :availability
+    
+    delegate [:arity, :call, :to_proc] => :@callable
+    
+    def initialize(callable, block, availability=:continuous)
+      @callable = pick_callable(callable, block)
+      @availability = availability
+    end
+    
+    def pick_callable(c, b)
+      cb = nil
+      if c.respond_to?(:call)
+        cb = c
+      elsif !b.nil?
+        cb = b
+      else
+        raise 'Cannot register callable. Neither callable nor block was given.'
+      end
+    end
+    
+    def continuous?
+      @availability == :continuous
+    end
+    
+  end
+end
+  

data/lib/eventually/event.rb

@@ -0,0 +1,47 @@
+require 'eventually'
+require 'eventually/callable'
+
+module Eventually
+  class Event
+    attr_reader :name, :callables
+    
+    def initialize(name, emittable=true)
+      @name = name.to_sym
+      @emittable = !!emittable
+      @callables = []
+    end
+    
+    def add_callable(callable)
+      raise "Event type :#{name} will not be emitted." unless emittable?
+      @callables << callable if callable_valid?(callable)
+    end
+    
+    def remove_callable(callable_to_remove)
+      if callable_valid?(callable_to_remove)
+        delete_handler = proc{|callable| callable == callable_to_remove }
+      else
+        delete_handler = proc{|callable| callable.callable == callable_to_remove }
+      end
+      @callables.delete_if(&delete_handler)
+    end
+    
+    def remove_all_callables
+      @callables = []
+    end
+    
+    def emit(*payload)
+      raise "Event type :#{name} cannot be emitted." unless emittable?
+      @callables.each {|callable| callable.call(*payload) }
+      @callables.delete_if {|callable| !callable.continuous? }
+    end
+    
+    def callable_valid?(callable)
+      callable.is_a?(Eventually::Callable)
+    end
+    
+    def emittable?
+      @emittable
+    end
+    alias :registerable? :emittable?
+  end
+end

data/lib/eventually/validation/arity.rb

@@ -0,0 +1,22 @@
+require 'eventually/callable'
+module Eventually
+  module Validation
+    class Arity
+      attr_reader :expected, :received
+      def initialize(event, emitter, arity)
+        @event = event
+        @emitter = emitter
+        @arity = @received = arity
+        @expected = @emitter.class.arity_for_event(@event)
+      end
+      
+      def valid?
+        !@emitter.class.validates_arity?(@event) || @received == @expected
+      end
+      
+      def raise_unless_valid!
+        raise "Arity validation failed for event :#{@event} (expected #{@expected}, received #{@received})" unless valid?
+      end
+    end
+  end
+end

data/lib/eventually/validation/max_listeners.rb

@@ -0,0 +1,17 @@
+module Eventually
+  module Validation
+    class MaxListeners
+      def initialize(emitter)
+        @emitter = emitter
+      end
+      
+      def valid?
+        @emitter.class.max_listeners == 0 || @emitter.num_listeners <= @emitter.class.max_listeners
+      end
+      
+      def warn_unless_valid!
+        puts "Warning: #{@emitter.class.name} has more than #{@emitter.class.max_listeners} registered listeners." unless valid?
+      end
+    end
+  end
+end

data/lib/eventually/version.rb

@@ -1,3 +1,3 @@
 module Eventually
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/lib/callable_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+require 'eventually/callable'
+
+describe Eventually::Callable do
+  let(:cb_lambda) { lambda{ :lambda } }
+  let(:cb_proc) { proc{ :proc } }
+  let(:cb_block) { proc{ :block } }
+  let(:cb_method) { def callable_meth; :meth end; method(:callable_meth) }
+  let(:availability) { :continuous }
+  
+  subject { Eventually::Callable.new(cb_lambda, cb_block, availability) }
+  its(:callable) { should eq cb_lambda }
+  its(:availability) { should eq availability }
+  
+  context 'when callable arg is' do
+    context 'a lambda' do
+      subject { Eventually::Callable.new(cb_lambda, nil) }
+      its(:callable) { should eq cb_lambda }
+    end
+    context 'a proc' do
+      subject { Eventually::Callable.new(cb_proc, nil) }
+      its(:callable) { should eq cb_proc }
+    end
+    context 'a detached method' do
+      subject { Eventually::Callable.new(cb_method, nil) }
+      its(:callable) { should eq cb_method }
+    end
+  end
+  
+  context 'when callable arg is not valid' do
+    context 'and block arg is valid' do
+      subject { Eventually::Callable.new(nil, cb_block) }
+      its(:callable) { should eq cb_block }
+    end
+    
+    context 'and block arg is valid' do
+      it 'raises an error that provided callable(s) were invalid' do
+        expect {
+          Eventually::Callable.new(nil, nil)
+        }.should raise_error(/Cannot register callable\. Neither callable nor block was given\./)
+      end
+    end
+  end
+  
+  describe '#continuous?' do
+    context 'when availability is :continuous' do
+      subject { Eventually::Callable.new(cb_lambda, nil, :continuous) }
+      its(:availability) { should eq :continuous }
+      its(:continuous?) { should be_true }
+    end
+    
+    context 'when availability is :continuous' do
+      subject { Eventually::Callable.new(cb_lambda, nil, :once) }
+      its(:availability) { should eq :once }
+      its(:continuous?) { should be_false }
+    end
+  end
+  
+  context 'delegation' do
+    it 'delegates :arity to callable' do
+      subject.arity.should eq subject.callable.arity
+    end
+    it 'delegates :call to callable' do
+      subject.call.should eq subject.callable.call
+    end
+    it 'delegates :to_proc to callable' do
+      subject.to_proc.should eq subject.callable.to_proc
+    end
+  end
+end

data/spec/lib/event_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+require 'eventually/event'
+
+describe Eventually::Event do
+  let(:event_name) { :started }
+  let(:callable) { Eventually::Callable.new(lambda{}, nil) }
+  
+  subject { Eventually::Event.new(event_name) }
+  its(:name) { should eq event_name }
+  its(:emittable?) { should be_true }
+  its(:callables) { should be_instance_of(Array) }
+  its(:callables) { should be_empty }
+  
+  describe '#add_callable' do
+    it 'adds a callable object to the callables array' do
+      subject.add_callable(callable)
+      subject.callables.should eq [callable]
+    end
+    
+    it 'skips adding invalid callable objects to callables array' do
+      subject.add_callable(nil)
+      subject.add_callable(1)
+      subject.add_callable("hello, world")
+      subject.callables.should be_empty
+    end
+    
+    context 'when event is not emittable' do
+      it 'raises an error' do
+        evt = Eventually::Event.new(event_name, false)
+        expect { evt.add_callable(callable) }.to raise_error(/Event type :#{event_name} will not be emitted\./)
+      end
+    end
+  end
+  
+  describe '#remove_callable' do
+    it 'removes raw callable' do
+      evt = Eventually::Event.new(event_name)
+      raw_callable = lambda{}
+      callable = Eventually::Callable.new(raw_callable, nil)
+      evt.add_callable(callable)
+      evt.callables.should have(1).item
+      evt.remove_callable(raw_callable)
+      evt.callables.should be_empty
+    end
+    
+    it 'removes wrapped raw callable' do
+      evt = Eventually::Event.new(event_name)
+      callable = Eventually::Callable.new(lambda{}, nil)
+      evt.add_callable(callable)
+      evt.callables.should have(1).item
+      evt.remove_callable(callable)
+      evt.callables.should be_empty
+    end
+  end
+  
+  describe '#remove_all_callables' do
+    it 'clears out all registered callables' do
+      evt = Eventually::Event.new(event_name)
+      evt.add_callable(Eventually::Callable.new(lambda{}, nil))
+      evt.add_callable(Eventually::Callable.new(lambda{}, nil))
+      evt.add_callable(Eventually::Callable.new(lambda{}, nil))
+      evt.add_callable(Eventually::Callable.new(lambda{}, nil))
+      evt.add_callable(Eventually::Callable.new(lambda{}, nil))
+      evt.callables.should have(5).items
+      evt.remove_all_callables
+      evt.callables.should be_empty
+    end
+  end
+  
+  describe '#emit' do
+    context 'when not emittable' do
+      it 'raises an error' do
+        evt = Eventually::Event.new(event_name, false)
+        expect { evt.emit(:data) }.to raise_error(/Event type :#{event_name} cannot be emitted\./)
+      end
+    end
+
+    it 'calls each listener callback' do
+      evt = Eventually::Event.new(event_name)
+      cbs = [
+        Eventually::Callable.new(lambda{}, nil),
+        Eventually::Callable.new(lambda{}, nil),
+        Eventually::Callable.new(lambda{}, nil),
+        Eventually::Callable.new(lambda{}, nil),
+        Eventually::Callable.new(lambda{}, nil)
+      ]
+      cbs.each do |cb|
+        evt.add_callable(cb)
+        cb.should_receive(:call).once.with(:data)
+      end
+      evt.emit(:data)
+    end
+    
+    context 'when some callables are one-time callable' do
+      it 'removes the one-time callable callables from the callables list' do
+        evt = Eventually::Event.new(event_name)
+        cbs = [
+          Eventually::Callable.new(lambda{}, nil),
+          Eventually::Callable.new(lambda{}, nil, :once),
+          Eventually::Callable.new(lambda{}, nil, :once),
+          Eventually::Callable.new(lambda{}, nil, :once),
+          Eventually::Callable.new(lambda{}, nil)
+        ]
+        cbs.each do |cb|
+          evt.add_callable(cb)
+          cb.should_receive(:call).once.with(:data)
+        end
+        evt.callables.should have(5).items
+        evt.emit(:data)
+        evt.callables.should have(2).items
+      end
+    end
+  end
+  
+end

data/spec/lib/eventually_spec.rb

@@ -8,12 +8,27 @@ describe Eventually do
   before(:each) do
     Emitter.disable_strict!
     Emitter.emits_none
+    Emitter.emits(:listener_added, :arity => 1)
+    Emitter.max_listeners = 10
   end
   
   let(:emitter) { Emitter.new }
   let(:defined_events) { [:one, :two, :three] }
   
   context 'external api' do
+    describe '.max_listeners' do
+      it 'returns the number of listeners allowed before memory warnings are printed' do
+        Emitter.max_listeners.should eq 10
+      end
+    end
+    
+    describe '.max_listeners=' do
+      it 'sets the max number of listeners to allow before printing memory warnings' do
+        Emitter.max_listeners = 20
+        Emitter.max_listeners.should eq 20
+      end
+    end
+    
     describe '.emits_none' do
       it 'clears out emitter definitions' do
         Emitter.emits(:jigger)
@@ -36,7 +51,7 @@ describe Eventually do
       
       it 'provides a list of pre-defined emittable events' do
         Emitter.emits(*defined_events)
-        Emitter.emits.should eq defined_events
+        Emitter.emits.should eq [:listener_added, defined_events].flatten
       end
       
       describe '.enable_strict!' do
@@ -97,51 +112,32 @@ describe Eventually do
             Emitter.emits(:jigger, arity: 5)
             Emitter.arity_for_event(:jigger).should eq 5
             Emitter.emits(:pingpong)
-            Emitter.arity_for_event(:pingpong).should eq -1        
+            Emitter.arity_for_event(:pingpong).should eq -2        
             Emitter.arity_for_event(:nonevent).should eq nil
           end
         end
       end
     end
     
-    it 'allows event registration with lambda' do
-      emitter.on(:start, lambda{ puts 'hi' })
-    end
-    
-    it 'allows event registration with proc' do
-      emitter.on(:start, proc{ puts 'hi' })
-    end
-    
-    it 'allows event registration with block' do
-      emitter.on(:start) do
-        puts 'hi'
-      end
-    end
-    
-    it 'allows event registration with detached method' do
-      def event_handler; end
-      emitter.on(:start, method(:event_handler))
-    end
-    
     it 'allows multiple registrations for a given event' do
       emitter.on(:start) { puts 'hello' }
       emitter.on(:start) { puts 'world' }
     end
     
-    describe '.can_emit_or_register?' do
+    describe '.emittable?' do
       context 'when strict mode enabled' do
         before { Emitter.enable_strict! }
         context 'when given event is registered' do
           it 'returns true' do
             Emitter.emits(:known)
             Emitter.emits?(:known).should be_true
-            Emitter.can_emit_or_register?(:known).should be_true
+            Emitter.emittable?(:known).should be_true
           end
         end
         context 'when given event is not registered' do
           it 'returns false' do
             Emitter.emits?(:unknown).should be_false
-            Emitter.can_emit_or_register?(:unknown).should be_false
+            Emitter.emittable?(:unknown).should be_false
           end
         end
       end
@@ -152,20 +148,64 @@ describe Eventually do
           it 'returns true' do
             Emitter.emits(:known)
             Emitter.emits?(:known).should be_true
-            Emitter.can_emit_or_register?(:known).should be_true
+            Emitter.emittable?(:known).should be_true
           end
         end
         context 'when given event is not registered' do
           it 'returns true' do
             Emitter.emits?(:unknown).should be_false
-            Emitter.can_emit_or_register?(:unknown).should be_true
+            Emitter.emittable?(:unknown).should be_true
           end
         end
       end
     end
   end
   
-  context 'when emitting events' do    
+  describe '#on' do
+    it 'raises an error when a given callback is invalid' do
+      expect { emitter.on(:start, nil, &nil)  }.should raise_error(/Cannot register callable/)
+      expect { emitter.on(:start, 10_000)     }.should raise_error(/Cannot register callable/)
+      expect { emitter.on(:start, "callback") }.should raise_error(/Cannot register callable/)
+    end
+    
+    context 'when arity validation is enabled' do
+      before { Emitter.emits(:hello_world, arity: 2) }
+      it 'accepts a callback with matching arity' do
+        expect {
+          emitter.on(:hello_world) do |param1, param2|
+            # callback will not be invoked
+          end
+        }.should_not raise_error
+      end
+      
+      it 'rejects a callback if the given arity is not exact' do
+        expect {
+          emitter.on(:hello_world) do |param1, param2, param3|
+            # callback will not be invoked
+          end
+        }.should raise_error(/Arity validation failed for event :hello_world \(expected 2, received 3\)/)
+      end
+    end
+    
+    context 'when detecting potential memory leaks' do
+      it 'writes a warning to stdout when > 10 listeners are added' do
+        $stdout.should_receive(:puts).once.with('Warning: Emitter has more than 10 registered listeners.')
+        (emitter.class.max_listeners+1).times do
+          emitter.on(:some_event, lambda{})
+        end
+      end
+
+      it 'will not print a warning if max_listeners is set to 0' do
+        emitter.class.max_listeners = 0
+        $stdout.should_not_receive(:puts).with('Warning: Emitter has more than 10 registered listeners.')
+        1000.times do
+          emitter.on(:some_event, lambda{})
+        end
+      end
+    end
+  end
+  
+  describe '#emit' do    
     let(:emitter) { Emitter.new }
     let(:watcher) { Watcher.new }
     
@@ -186,7 +226,6 @@ describe Eventually do
       def proc_callback
         proc{|payload| @value += payload }
       end
-      
       def update_method(payload)
         @value += payload
       end
@@ -216,14 +255,18 @@ describe Eventually do
     it_behaves_like 'emitting an event', :method
     it_behaves_like 'emitting an event', :proc
     
-    it 'emits nothing when no event callbacks are given' do
-      expect { emitter.__send__(:emit, :hullabaloo) }.should_not raise_error
+    it 'emits an event on the emitter when a new listener is added' do
+      callback_to_add = lambda{ puts 'hi' }
+      listener_id = nil
+      emitter.on(:listener_added) do |listener|
+        listener_id = listener.callable.object_id
+      end
+      emitter.on(:some_event, callback_to_add)
+      listener_id.should eq callback_to_add.object_id
     end
     
-    it 'raises an error when a given callback is invalid' do
-      expect { emitter.on(:start, nil, &nil)  }.should raise_error(/Cannot register callback/)
-      expect { emitter.on(:start, 10_000)     }.should raise_error(/Cannot register callback/)
-      expect { emitter.on(:start, "callback") }.should raise_error(/Cannot register callback/)
+    it 'emits nothing when no event callbacks are given' do
+      expect { emitter.__send__(:emit, :hullabaloo) }.should_not raise_error
     end
     
     it 'invokes registered callbacks in a FIFO manner' do
@@ -244,33 +287,18 @@ describe Eventually do
     end
     
     context 'when arity validation is enabled' do
-      before { Emitter.emits(:hello_world, arity: 2) }
-      it 'accepts a callback with matching arity' do
-        expect {
-          emitter.on(:hello_world) do |param1, param2|
-            #not invoked
-          end
-        }.should_not raise_error
-      end
-      
-      it 'rejects a callback if the given arity is not exact' do
-        expect {
-          emitter.on(:hello_world) do |param1, param2, param3|
-            #not invoked
-          end
-        }.should raise_error(/Invalid callback arity for event :hello_world \(expected 2, received 3\)/)
-      end
-      
-      it 'accepts emitting an event when arity is valid' do
+      it 'emits the event when arity is valid' do
+        emitter.class.emits(:hello_world, arity: 2)
         expect {
           emitter.__send__(:emit, :hello_world, "hello", "world")
         }.should_not raise_error
       end
       
       it 'rejects emitting an event when the arity is not exact' do
+        emitter.class.emits(:hello_world, arity: 2)
         expect {
           emitter.__send__(:emit, :hello_world, "hello")
-        }.should raise_error(/Invalid emit arity for event :hello_world \(expected 2, received 1\)/)
+        }.should raise_error(/Arity validation failed for event :hello_world \(expected 2, received 1\)/)
       end
     end
     
@@ -286,40 +314,76 @@ describe Eventually do
         end
       end
     end
-    
-    describe '#valid_event_arity?' do
-      context 'when arity is validated for event' do
-        context 'and the arity matches' do
-          it 'doesn\'t raise an error' do
-            Emitter.emits(:jump, arity: 2)
-            expect {
-              emitter.on(:jump) do |param1, param2|
-                puts 'hi'
-              end
-            }.should_not raise_error
-          end
-        end
-        context 'and the arity does not match' do
-          it 'raises an error' do
-            Emitter.emits(:jump, arity: 2)
-            expect {
-              emitter.on(:jump) do |param1|
-                puts 'hi'
-              end
-            }.should raise_error(/expected 2, received 1/)
-          end
-        end
+  end
+  
+  describe '#once' do
+    it 'registers to an event for one time only, then releases the registration' do
+      value = 1
+      emitter.once(:start) do
+        value += 1
       end
-      context 'when arity is not for event' do
-        it 'doesn\'t raise an error' do
-          Emitter.emits?(:jump).should be_false
-          expect {
-            emitter.on(:jump) do |param1, param2|
-              puts 'hi'
-            end
-          }.should_not raise_error
-        end
+      listener_count = emitter.num_listeners
+      
+      emitter.__send__(:emit, :start)
+      emitter.__send__(:emit, :start)
+      value.should eq 2
+      emitter.num_listeners.should eq(listener_count - 1)
+    end
+  end
+  
+  describe '#remove_listener' do
+    it 'removes a given event callback' do
+      value = 1
+      cbk = lambda{ value += 1 }
+      emitter.on(:some_event, cbk)
+      emitter.__send__(:emit, :some_event)
+      value.should eq 2
+      emitter.remove_listener(:some_event, cbk)
+      emitter.__send__(:emit, :some_event)
+      value.should eq 2
+    end
+  end
+  
+  describe '#remove_all_listeners' do
+    it 'removes all listeners for the given event' do
+      value = 1
+      emitter.on(:some_event) do
+        value += 1
+      end
+      emitter.on(:some_event) do
+        value += 5
+      end
+      emitter.on(:some_event) do
+        value += 10
       end
+      emitter.__send__(:emit, :some_event)
+      value.should eq 17
+      
+      emitter.remove_all_listeners(:some_event)
+      emitter.__send__(:emit, :some_event)
+      value.should eq 17
     end
   end
+  
+  describe '#listeners' do
+    it 'returns a list of listener callbacks for the given event' do
+      cb1 = lambda{}
+      cb2 = lambda{}
+      cb3 = lambda{}
+      emitter.on(:some_event, cb1)
+      emitter.on(:some_event, cb2)
+      emitter.on(:some_event, cb3)
+      emitter.listeners(:some_event).should eq [cb1, cb2, cb3]
+    end
+  end
+  
+  describe '#num_listeners' do
+    it 'counts all listeners across all events' do
+      emitter.on(:event1, lambda{})
+      emitter.on(:event2, lambda{})
+      emitter.on(:event3, lambda{})
+      emitter.num_listeners.should eq 3
+    end
+  end
+  
 end

data/spec/lib/validation/arity_spec.rb

@@ -0,0 +1,73 @@
+require 'spec_helper'
+require 'eventually/validation/arity'
+
+unless defined?(ArityEmitter)
+  class ArityEmitter
+    include Eventually
+    emits :started, arity: 1
+    emits :stopped
+  end
+end
+
+describe Eventually::Validation::Arity do
+  let(:emitter) { ArityEmitter.new }
+  
+  describe '#valid?' do
+    context 'when arity defined for event' do
+      context 'and arity does not match' do
+        subject { Eventually::Validation::Arity.new(:started, emitter, 2) }
+        it 'is invalid' do
+          subject.valid?.should eq false
+          subject.expected.should eq 1
+          subject.received.should eq 2
+        end
+      end
+      context 'and arity matches' do
+        subject { Eventually::Validation::Arity.new(:started, emitter, 1) }
+        it 'is valid' do
+          subject.valid?.should eq true
+          subject.expected.should eq 1
+          subject.received.should eq 1
+        end
+      end
+    end
+    context 'when event is defined' do
+      context 'and arity is not defined' do
+        subject { Eventually::Validation::Arity.new(:stopped, emitter, 3) }
+        it 'is valid' do
+          subject.valid?.should eq true
+          subject.expected.should eq -2
+          subject.received.should eq 3
+        end
+      end
+    end
+    context 'when event is not defined' do
+      context 'and arity is not defined' do
+        subject { Eventually::Validation::Arity.new(:something_else, emitter, 3) }
+        it 'is valid' do
+          subject.valid?.should eq true
+          subject.expected.should eq nil
+          subject.received.should eq 3
+        end
+      end
+    end
+  end
+  
+  describe '#raise_unless_valid!' do
+    subject { Eventually::Validation::Arity.new(:an_event, emitter, 0)}
+    
+    context 'when not valid' do
+      it 'does not raise an error' do
+        subject.stub(:valid?).and_return(true)
+        expect { subject.raise_unless_valid! }.should_not raise_error
+      end
+    end
+    
+    context 'when not valid' do
+      it 'raises an error' do
+        subject.stub(:valid?).and_return(false)
+        expect { subject.raise_unless_valid! }.should raise_error
+      end
+    end
+  end
+end

data/spec/lib/validation/max_listeners_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+require 'eventually/validation/max_listeners'
+
+unless defined?(MaxListenerEmitter)
+  class MaxListenerEmitter
+    include Eventually
+  end
+end
+
+describe Eventually::Validation::MaxListeners do
+  let(:emitter) { MaxListenerEmitter.new }
+  subject { Eventually::Validation::MaxListeners.new(emitter) }
+
+  describe '#valid?' do
+    context 'when max_listeners is non-zero positive integer' do
+      context 'when num_listeners is less than or equal to max_listeners' do
+        it 'is valid' do
+          emitter.class.max_listeners = 5
+          5.times{|i| emitter.on("event"+i.to_s, lambda{}) }
+          subject.valid?.should eq true
+        end
+      end
+      context 'when num_listeners is greater than max_listeners' do
+        it 'is not valid' do
+          emitter.class.max_listeners = 3
+          5.times{|i| emitter.on("event"+i.to_s, lambda{}) }
+          subject.valid?.should eq false
+        end
+      end
+    end
+    context 'when max_listeners is zero' do
+      it 'is valid' do
+        emitter.class.max_listeners = 0
+        1000.times{|i| emitter.on("event"+i.to_s, lambda{}) }
+        subject.valid?.should eq true
+      end
+    end
+  end
+  
+  describe '#warn_unless_valid!' do
+    context 'when not valid' do
+      it 'does not raise an error' do
+        subject.stub(:valid?).and_return(true)
+        $stdout.should_not_receive(:puts)
+        subject.warn_unless_valid!
+      end
+    end
+    
+    context 'when not valid' do
+      it 'raises an error' do
+        subject.stub(:valid?).and_return(false)
+        $stdout.should_receive(:puts).with(/Warning: MaxListenerEmitter has more than \d+ registered listeners\./)
+        subject.warn_unless_valid!
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,3 +1,5 @@
 $LOAD_PATH << File.expand_path('../lib', File.dirname(__FILE__))
+require 'simplecov'
+SimpleCov.start
 require 'eventually'
-require 'rspec'
+require 'rspec'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eventually
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-20 00:00:00.000000000Z
+date: 2011-12-21 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2153560520 !ruby/object:Gem::Requirement
+  requirement: &2161573120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,29 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153560520
+  version_requirements: *2161573120
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &2161572700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2161572700
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &2152246440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2152246440
 description: Eventually is an event library built to loosely mirror the NodeJS EventEmitter
   API.
 email:
@@ -40,8 +62,16 @@ files:
 - examples/basic.rb
 - examples/strict.rb
 - lib/eventually.rb
+- lib/eventually/callable.rb
+- lib/eventually/event.rb
+- lib/eventually/validation/arity.rb
+- lib/eventually/validation/max_listeners.rb
 - lib/eventually/version.rb
+- spec/lib/callable_spec.rb
+- spec/lib/event_spec.rb
 - spec/lib/eventually_spec.rb
+- spec/lib/validation/arity_spec.rb
+- spec/lib/validation/max_listeners_spec.rb
 - spec/spec_helper.rb
 homepage: http://www.rand9.com
 licenses: []
@@ -69,5 +99,10 @@ specification_version: 3
 summary: Eventually is an event library built to loosely mirror the NodeJS EventEmitter
   API.
 test_files:
+- spec/lib/callable_spec.rb
+- spec/lib/event_spec.rb
 - spec/lib/eventually_spec.rb
+- spec/lib/validation/arity_spec.rb
+- spec/lib/validation/max_listeners_spec.rb
 - spec/spec_helper.rb
+has_rdoc: