observatory 0.0.1 → 0.1.0

data/.gitignore

@@ -1,3 +1,4 @@
 doc
 .yardoc
 _site
+pkg

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    observatory (0.0.1)
+    observatory (0.1.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
     bluecloth (2.1.0)
-    rake (0.8.7)
-    yard (0.6.8)
+    rake (0.9.0)
+    yard (0.7.1)
 
 PLATFORMS
   ruby
@@ -16,5 +16,5 @@ PLATFORMS
 DEPENDENCIES
   bluecloth (~> 2.1)
   observatory!
-  rake (~> 0.8)
-  yard (~> 0.6)
+  rake (~> 0.9)
+  yard (~> 0.7)

data/Rakefile

@@ -12,7 +12,7 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-YARD::Rake::YardocTask.new do |t| 
-  t.files   = ['lib/**/*.rb', 'app/**/*.rb', '-', 'LICENSE', 'HISTORY'] 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'app/**/*.rb', '-', 'LICENSE', 'HISTORY']
   t.options = %w{--title Observatory -m markdown}
-end
+end

data/lib/observatory/dispatcher.rb

@@ -1,33 +1,38 @@
 module Observatory
   # The Dispatcher is the central repository of all registered observers, and
   # is used by observables to send out signals to these observers.
-  # 
+  #
   # A dispatcher is not a singleton object, which means you may very well have
   # several dispatcher objects in your program, keeping track of different
   # stacks of observers and observables. Note that this requires you to pass
   # your dispatcher object around using dependency injection.
-  # 
+  #
   # ## For observables
-  # 
+  #
   # The stack of observers for any given signal is kept in {#observers}. When
   # using {#notify}, {#notify_until} or {#filter} all observers in the stack
   # will be called.
-  # 
+  #
   # ### Notification methods
-  # 
+  #
   # Observable objects may use the following methods to trigger their
   # observers:
-  # 
+  #
   # * {#notify} to call all observers.
   # * {#notify_until} to call observers until one stops the chain.
   # * {#filter} to let all observers alter a given value.
-  # 
+  #
   # ## For observers
-  # 
+  #
   # An object that observes another object is an observer, and it can
   # register itself with the {Dispatcher} to listen to a signal that
   # observable objects may issue.
-  # 
+  #
+  # An observer may be anything that is callable, but will usually
+  # be a method, block or Proc object. You may optionally specify an
+  # explicit priority for an observer, to make sure it gets called before
+  # or after other observers.
+  #
   # @example Using {#connect} to register a new observer
   #   class Logger
   #     def log(event)
@@ -36,10 +41,10 @@ module Observatory
   #   end
   #   logger = Logger.new
   #   dispatcher.connect('post.publish', logger.method(:log))
-  # 
+  #
   # @example Using {#disconnect} to unregister an observer
   #   dispatcher.disconnect('post.publish', logger.method(:log))
-  # 
+  #
   # @example Using {#notify} to let other objects know something has happened
   #   class Post
   #     include Observable
@@ -49,14 +54,14 @@ module Observatory
   #       # do publication stuff here
   #     end
   #   end
-  # 
+  #
   # @example Using {#notify_until} to delegate saving a record to another object
   #   class Post
   #     def save
   #       notify_until 'post.save', :title => title
   #     end
   #   end
-  # 
+  #
   # @example Using {#filter} to let observers modify the output of the title attribute
   #   class Post
   #     def title
@@ -71,17 +76,23 @@ module Observatory
     def initialize
       @observers = {}
     end
-    
+
     # Register a observer for a given signal.
-    # 
+    #
     # Instead of adding a method or Proc object to the stack, you could
     # also use a block. Either the observer argument or the block is required.
-    # 
+    #
+    # Optionally, you could pass in an options hash as the last argument, that
+    # can specify an explicit priority. When omitted, an internal counter starting
+    # from 1 will be used. To make sure your observer is called last, specify
+    # a high, **positive** number. To make sure your observer is called first, specify
+    # a high, **negative** number.
+    #
     # @example Using a block as an observer
     #   dispatcher.connect('post.publish') do |event|
     #     puts "Post was published"
     #   end
-    # 
+    #
     # @example Using a method as an observer
     #   class Reporter
     #     def log(event)
@@ -89,42 +100,98 @@ module Observatory
     #     end
     #   end
     #   dispatcher.connect('post.publish', Reporter.new.method(:log))
-    # 
-    # @param [String] signal is the name used by the observable to trigger
-    #   observers
-    # @param [#call] observer is the Proc or method that will react to
-    #   an event issued by an observable.
+    #
+    # @example Determining observer call order using priority
+    #   dispatcher.connect('pulp', :priority => 10) do
+    #     puts "I dare you!"
+    #   end
+    #   dispatcher.connect('pulp', :priority => -10) do
+    #     puts "I double-dare you!"
+    #   end
+    #   # output when "pulp" is triggered:
+    #   "I double-dare you!"
+    #   "I dare you!"
+    #
+    # @overload connect(signal, observer, options = {})
+    #   @param [String] signal is the name used by the observable to trigger
+    #     observers
+    #   @param [#call] observer is the Proc or method that will react to
+    #     an event issued by an observable.
+    #   @param [Hash] options is an optional Hash of additional options.
+    #   @option options [Fixnum] :priority is the priority of this observer
+    #     in the stack of all observers for this signal. A higher number means
+    #     lower priority. Negative numbers are allowed.
+    # @overload connect(signal, options = {}, &block)
+    #   @param [String] signal is the name used by the observable to trigger
+    #     observers
+    #   @param [Hash] options is an optional Hash of additional options.
+    #   @option options [Fixnum] :priority is the priority of this observer
+    #     in the stack of all observers for this signal. A higher number means
+    #     lower priority. Negative numbers are allowed.
     # @return [#call] the added observer
-    def connect(signal, observer = nil, &block)
-      if observer.nil?
-        if block_given?
-          observer = block
+    def connect(signal, *args, &block)
+      # ugly argument parsing.
+      # Make sure that there is either a block given, or that the second argument is
+      # something callable. If there is a block given, the second argument, if given,
+      # must be a Hash which defaults to an empty Hash. If there is no block given,
+      # the third optional argument must be Hash.
+      if block_given?
+        observer = block
+        if args.size == 1 && args.first.is_a?(Hash)
+          options = args.first
+        elsif args.size == 0
+          options = {}
         else
-          raise ArgumentError, 'Use a block, method or proc to specify an observer'
+          raise ArgumentError, 'When given a block, #connect only expects a signal and options hash as arguments'
+        end
+      else
+        observer = args.shift
+        raise ArgumentError, 'Use a block, method or proc to specify an observer' unless observer.respond_to?(:call)
+        if args.any?
+          options = args.shift
+          raise ArgumentError, '#connect only expects a signal, method and options hash as arguments' unless options.is_a?(Hash) || args.any?
+        else
+          options = {}
         end
       end
+
+      observer_with_priority = {
+        :observer => observer,
+        :priority => (options[:priority] || next_internal_priority)
+      }
+
+      # Initialize the list of observers for this signal and add this observer
       observers[signal] ||= []
-      observers[signal] << observer
+      observers[signal] << observer_with_priority
+
+      # Sort all observers on priority
+      observers[signal].sort! do |a,b|
+        a[:priority] <=> b[:priority]
+      end
+
+      observer
     end
 
     # Removes an observer from a signal stack, so it no longer gets triggered.
-    # 
+    #
     # @param [String] signal is the name of the stack to remove the observer
     #   from.
     # @param [#call] observer is the original observer to remove.
     # @return [#call, nil] the removed observer or nil if it could not be found
     def disconnect(signal, observer)
       return nil unless observers.key?(signal)
-      observers[signal].delete(observer)
+      observers[signal].delete_if do |observer_with_priority|
+        observer_with_priority[:observer] == observer
+      end
     end
 
     # Send out a signal to all registered observers using a new {Event}
     # instance. The {Event#signal} will be used to determine the stack of
     # {#observers} to use.
-    # 
+    #
     # Using {#notify} allows observers to take action at a given time during
     # program execution, such as logging important events.
-    # 
+    #
     # @param [Event]
     # @return [Event]
     def notify(event)
@@ -136,9 +203,9 @@ module Observatory
 
     # Same as {#notify}, but halt execution as soon as an observer has
     # indicated it has handled the event by returning a non-falsy value.
-    # 
+    #
     # An event that was acted upon by an observer will be marked as processed.
-    # 
+    #
     # @param [Event]
     # @see Event#process!
     # @return [Event]
@@ -151,10 +218,10 @@ module Observatory
 
     # Let all registered observers modify a given value. The observable can
     # then use the {Event#return_value} to get the filtered result back.
-    # 
+    #
     # You could use {#filter} to let observers modify arguments to a method
     # before continuing to work on them (just an example).
-    # 
+    #
     # @param [Event]
     # @param [Object] value
     # @return [Event]
@@ -168,8 +235,15 @@ module Observatory
 
   private
 
+    def next_internal_priority
+      @next_internal_priority ||= 0
+      @next_internal_priority += 1
+    end
+
     def each(signal, &block)
-      (observers[signal] || []).each(&block)
+      (observers[signal] || []).each do |observer_with_priority|
+        yield observer_with_priority[:observer]
+      end
     end
   end
 end

data/lib/observatory/version.rb

@@ -1,3 +1,3 @@
 module Observatory
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/observatory.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ['Arjan van der Gaag']
   s.email       = ['arjan@arjanvandergaag.nl']
-  s.homepage    = ""
+  s.homepage    = 'http://avdgaag.github.com/observatory'
   s.summary     = "A simple implementation of the observer pattern for Ruby programs."
   s.description = %q{Observatory is a simple gem to facilitate loosely-coupled communication between Ruby objects. It implements the observer design pattern so that your objects can publish events that other objects can subscribe to. Observatory provides some syntactic sugar and methods to notify events, filter values and allow observing objects to stop the filter chain. Observatory is inspired by the Event Dispatcher Symfony component.}
 
@@ -18,8 +18,8 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  
-  s.add_development_dependency 'yard',      '~>0.6'
+
+  s.add_development_dependency 'yard',      '~>0.7'
   s.add_development_dependency 'bluecloth', '~>2.1'
-  s.add_development_dependency 'rake',      '~>0.8'
+  s.add_development_dependency 'rake',      '~>0.9'
 end

data/test/dispatcher_test.rb

@@ -5,42 +5,73 @@ class DispatcherTest < Test::Unit::TestCase
     @dispatcher = Dispatcher.new
     @method = method(:example_observer_method)
   end
-  
+
   def example_observer_method
     # does nothing
   end
-  
+
   def test_should_start_with_empty_list_of_observers
     assert_equal({}, @dispatcher.observers)
   end
-  
+
   def test_connecting_an_observer_using_a_method
     @dispatcher.connect('signal', @method)
-    assert @dispatcher.observers['signal'].include?(@method)
+    assert @dispatcher.observers['signal'].map { |o| o[:observer] }.include?(@method)
   end
-  
-  def test_connecting_an_oversver_using_a_block
+
+  def test_connecting_an_observer_using_a_block
     @dispatcher.connect('signal') do
       # does nothing
     end
     assert_equal 1, @dispatcher.observers['signal'].size
   end
-  
+
+  def test_connecting_an_observer_with_a_priority
+    assert_nothing_raised { @dispatcher.connect('signal', @method, :priority => 5) }
+  end
+
+  def test_observers_are_called_in_order
+    guinea_pig = 'foo'
+    @dispatcher.connect('signal', :priority => 10) do
+      guinea_pig = guinea_pig.upcase!
+    end
+    @dispatcher.connect('signal', :priority => 5) do
+      guinea_pig << 'bar'
+    end
+    @dispatcher.notify(Event.new('observable', 'signal'))
+    assert_equal 'FOOBAR', guinea_pig
+  end
+
+  def test_observers_without_priority_remain_in_order_of_adding
+    guinea_pig = 'foo'
+    @dispatcher.connect('signal') do
+      guinea_pig << 'bar'
+    end
+    @dispatcher.connect('signal') do
+      guinea_pig << 'baz'
+    end
+    @dispatcher.connect('signal', :priority => -1) do
+      guinea_pig << 'qux'
+    end
+    @dispatcher.notify(Event.new('observable', 'signal'))
+    assert_equal 'fooquxbarbaz', guinea_pig
+  end
+
   def test_connecting_nothing_should_raise_exception
     assert_raise(ArgumentError) { @dispatcher.connect('signal') }
   end
-  
+
   def test_disconnecting_a_new_observer_returns_nil
     assert_nil @dispatcher.disconnect('signal', @method)
   end
-  
+
   def test_disconnecting_an_exisiting_observer_removes_it_from_stack
     @dispatcher.connect('signal', @method)
     assert_equal 1, @dispatcher.observers['signal'].size
     @dispatcher.disconnect('signal', @method)
     assert_equal 0, @dispatcher.observers['signal'].size
   end
-  
+
   def test_notify_calls_all_observers
     flag1 = false
     flag2 = false
@@ -50,7 +81,7 @@ class DispatcherTest < Test::Unit::TestCase
     assert flag1
     assert flag2
   end
-  
+
   def test_notify_calls_all_observers_in_order
     output = ''
     @dispatcher.connect('signal') { output << 'a' }
@@ -58,7 +89,7 @@ class DispatcherTest < Test::Unit::TestCase
     @dispatcher.notify(Event.new('observable', 'signal'))
     assert_equal('ab', output)
   end
-  
+
   def test_using_notify_until_calls_all_observers_until_one_returns_true
     output = ''
     @dispatcher.connect('signal') { output << 'a'; true }
@@ -66,11 +97,11 @@ class DispatcherTest < Test::Unit::TestCase
     @dispatcher.notify_until(Event.new('observable', 'signal'))
     assert_equal('a', output)
   end
-  
+
   def test_using_filter_uses_original_value_as_default_return_value
     assert_equal 'foo', @dispatcher.filter(Event.new('observable', 'signal'), 'foo').return_value
   end
-  
+
   def test_using_filter_uses_adjusted_value_as_default_return_value
     @dispatcher.connect('signal') { |e,v| v.upcase }
     assert_equal 'FOO', @dispatcher.filter(Event.new('observable', 'signal'), 'foo').return_value

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: observatory
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Arjan van der Gaag
@@ -15,27 +15,26 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-01 00:00:00 Z
+date: 2011-05-26 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: yard
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  type: :development
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 7
+        hash: 5
         segments: 
         - 0
-        - 6
-        version: "0.6"
-  type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: bluecloth
+        - 7
+        version: "0.7"
+  requirement: *id001
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  name: yard
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -45,23 +44,24 @@ dependencies:
         - 2
         - 1
         version: "2.1"
-  type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
+  requirement: *id002
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  name: bluecloth
+- !ruby/object:Gem::Dependency 
+  type: :development
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 27
+        hash: 25
         segments: 
         - 0
-        - 8
-        version: "0.8"
-  type: :development
-  version_requirements: *id003
+        - 9
+        version: "0.9"
+  requirement: *id003
+  prerelease: false
+  name: rake
 description: Observatory is a simple gem to facilitate loosely-coupled communication between Ruby objects. It implements the observer design pattern so that your objects can publish events that other objects can subscribe to. Observatory provides some syntactic sugar and methods to notify events, filter values and allow observing objects to stop the filter chain. Observatory is inspired by the Event Dispatcher Symfony component.
 email: 
 - arjan@arjanvandergaag.nl
@@ -93,7 +93,7 @@ files:
 - test/observer_test.rb
 - test/test_helper.rb
 - watch_tests.rb
-homepage: ""
+homepage: http://avdgaag.github.com/observatory
 licenses: []
 
 post_install_message: