observables 0.1.1 → 0.1.2

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2010 Nathan Stults
-
-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.
+Copyright (c) 2010 Nathan Stults
+
+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/README.rdoc

@@ -1,117 +1,117 @@
- = Observables
-
- Observables implements observable arrays and hashes by way of the ActiveModel::Notifier, the same mechanism
- underlying the instrumentation API in Rails3. Observables collections broadcast detailed change information for
- any state-modifying operations, including specific elements added or removed, when that information is practically
- obtainable.
-
- == Installation
-
- Observables is available as a RubyGem:
-
-     gem install observables
-
- == Observing the Observables
-
- === Example:
-
-     #Getting an observable array
-
-     ary = [1,2,3] #or, ary = Observables::Array.new([1,2,3]), or, hsh = Observables::Hash
-     ary.observable? # => false
-     ary.can_be_observable? # => true
-     ary.make_observable => #<Class:#<Array:0x56a84a8>>
-
-     #Setting up a subscription
-
-     subscription = ary.subscribe do |change_type,args|
-         puts "Change type: #{change_type}"
-         puts "Trigger: #{args.trigger}"
-         puts "Changes: #{args.changes.inspect}"
-         puts "---"
-     end
-
-     #Do stuff
-
-     ary << 3
-     #   Change type: before_added
-     #   Trigger: <<
-     #   Changes: {:added=>[3]}
-     #   ---
-     #   Change type: after_added
-     #   Trigger: <<
-     #   Changes: {:added=>[3]}
-     #   => [1,2,3,3]
-
-     #Clean up
-
-     ary.unsubscribe(subscription)
-     ary << 4 # => [1,2,3,3,4]
-
-     #Only listen to after_xxx
-
-     subscription = ary.subscribe(/after/) do |change_type,_|
-     puts "Change type:#{change_type}"
-     end
-
-     ary.concat([9,10,11])
-
-     #   Change type: after_added, changes: {:added=>[9,10,11]}
-     #   => [1,2,3,3,4,9,10,11]
-
- 	ary.replace([3,2,1])
-
- 	#   Change type: after_modified, changed: {:added=>[3,2,1], :removed=>[1,2,3,3,4,9,10,11]}
- 	#	=> [3,2,1]
-
-     #Hashes work too
-
-     hsh = {:a=>:b}
-     hsh.can_be_observable? # => true
-     hsh.make_observable
-     hsh.subscribe { |type,args| ... }
-
- == Special case: ownership
-
- Observables was created to assist in the implementation of proper dirty tracking for in-place modifications
- to embedded collections in ORM's, particularly for documented oriented databases, where
- this is a common situation. In this scenario and similar scenarios, observable collections
- will only be subscribed to by the object that owns them. However, the parent object
- may own any number of child collections. To avoid having to manage myriad subscription
- objects, each observable collection can have a single 'observer' - and will manage the
- subscription to that observer like so:
-
- 	class Owner
- 		def my_array
- 			@my_array
- 		end
-
- 		def my_array=(new_array)
- 			@my_array.clear_observer if @my_array
- 			@my_array = new_array.tap {|a|a.make_observable}
- 			@my_array.set_observer(self, :pattern=>/before/, :callback_method=>:my_array_before_change)
- 			#Acceptable alernatives are:
- 			#  @my_array.set_observer { |type,args| ... }
- 			#  @my_array.set_observer(self, :pattern=>/before/) { |sender,type,args| ... }
- 		end
-
- 		def my_array_before_change(sender,type,args)
- 			#sender = @my_array
- 			#do something interesting, like, say, attribute_will_change!(:my_array)
- 		end
-
- 	end
-
- == Note on Patches/Pull Requests
-
- * Fork the project.
- * Make your feature addition or bug fix.
- * Add tests for it. This is important so I don't break it in a
-   future version unintentionally.
- * Commit, do not mess with rakefile, version, or history.
-   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- * Send me a pull request. Bonus points for topic branches.
-
- == Copyright
-
- Copyright (c) 2010 Nathan Stults. See LICENSE for details.
+ = Observables
+
+ Observables implements observable arrays and hashes by way of the ActiveModel::Notifier, the same mechanism
+ underlying the instrumentation API in Rails3. Observables collections broadcast detailed change information for
+ any state-modifying operations, including specific elements added or removed, when that information is practically
+ obtainable.
+
+ == Installation
+
+ Observables is available as a RubyGem:
+
+     gem install observables
+
+ == Observing the Observables
+
+ === Example:
+
+     #Getting an observable array
+
+     ary = [1,2,3] #or, ary = Observables::Array.new([1,2,3]), or, hsh = Observables::Hash
+     ary.observable? # => false
+     ary.can_be_observable? # => true
+     ary.make_observable => #<Class:#<Array:0x56a84a8>>
+
+     #Setting up a subscription
+
+     subscription = ary.subscribe do |change_type,args|
+         puts "Change type: #{change_type}"
+         puts "Trigger: #{args.trigger}"
+         puts "Changes: #{args.changes.inspect}"
+         puts "---"
+     end
+
+     #Do stuff
+
+     ary << 3
+     #   Change type: before_added
+     #   Trigger: <<
+     #   Changes: {:added=>[3]}
+     #   ---
+     #   Change type: after_added
+     #   Trigger: <<
+     #   Changes: {:added=>[3]}
+     #   => [1,2,3,3]
+
+     #Clean up
+
+     ary.unsubscribe(subscription)
+     ary << 4 # => [1,2,3,3,4]
+
+     #Only listen to after_xxx
+
+     subscription = ary.subscribe(/after/) do |change_type,args|
+         puts "Change type:#{change_type}, changes: #{args.changes}"
+     end
+
+     ary.concat([9,10,11])
+
+     #   Change type: after_added, changes: {:added=>[9,10,11]}
+     #   => [1,2,3,3,4,9,10,11]
+
+     ary.replace([3,2,1])
+
+     #Change type: after_modified, changed: {:added=>[3,2,1], :removed=>[1,2,3,3,4,9,10,11]}
+     #	=> [3,2,1]
+
+     #Hashes work too
+
+     hsh = {:a=>:b}
+     hsh.can_be_observable? # => true
+     hsh.make_observable
+     hsh.subscribe { |type,args| ... }
+
+ == Special case: ownership
+
+ Observables was created to assist in the implementation of proper dirty tracking for in-place modifications
+ to embedded collections in ORM's, particularly for documented oriented databases, where
+ this is a common situation. In this scenario and similar scenarios, observable collections
+ will only be subscribed to by the object that owns them. However, the parent object
+ may own any number of child collections. To avoid having to manage myriad subscription
+ objects, each observable collection can have a single 'observer' - and will manage the
+ subscription to that observer like so:
+
+ 	class Owner
+ 		def my_array
+ 			@my_array
+ 		end
+
+ 		def my_array=(new_array)
+ 			@my_array.clear_observer if @my_array
+ 			@my_array = new_array.tap {|a|a.make_observable}
+ 			@my_array.set_observer(self, :pattern=>/before/, :callback_method=>:my_array_before_change)
+ 			#Acceptable alernatives are:
+ 			#  @my_array.set_observer { |sender,type,args| ... }
+ 			#  @my_array.set_observer(self, :pattern=>/before/) { |sender,type,args| ... }
+ 		end
+
+ 		def my_array_before_change(sender,type,args)
+ 			#sender == @my_array
+ 			#do something interesting, like, say, attribute_will_change!(:my_array)
+ 		end
+
+ 	end
+
+ == Note on Patches/Pull Requests
+
+ * Fork the project.
+ * Make your feature addition or bug fix.
+ * Add tests for it. This is important so I don't break it in a
+   future version unintentionally.
+ * Commit, do not mess with rakefile, version, or history.
+   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+ * Send me a pull request. Bonus points for topic branches.
+
+ == Copyright
+
+ Copyright (c) 2010 Nathan Stults. See LICENSE for details.

data/lib/observables.rb

@@ -1,15 +1,15 @@
-require 'rubygems'
-
-base_dir = File.dirname(__FILE__)
-[
-  'base',
-  'array_watcher',
-  'hash_watcher',
-  'collections',
-  'version'
-].each {|req| require File.join(base_dir,'observables',req)}
-
-Dir[File.join(base_dir,"observables","extensions","*.rb")].each {|ext|require ext}
-
-module Observables
+require 'rubygems'
+
+base_dir = File.dirname(__FILE__)
+[
+  'base',
+  'array_watcher',
+  'hash_watcher',
+  'collections',
+  'version'
+].each {|req| require File.join(base_dir,'observables',req)}
+
+Dir[File.join(base_dir,"observables","extensions","*.rb")].each {|ext|require ext}
+
+module Observables
 end

data/lib/observables/array_watcher.rb

@@ -1,50 +1,50 @@
-
-module Observables
-  module ArrayWatcher
-    include Observables::Base
-
-    ADD_METHODS =       :<<, :push, :concat, :insert, :unshift
-    MODIFIER_METHODS =  :collect!, :map!, :flatten!, :replace, :reverse!, :sort!, :fill
-    REMOVE_METHODS =    :clear, :compact!, :delete, :delete_at, :delete_if, :pop, :reject!, :shift, :slice!, :uniq!
-
-    #[]= can either be an add method or a modifier method depending on
-    #if the previous key exists
-    def []=(*args)
-      change_type = args[0] >= length ? :added : :modified
-      changes = changes_for(change_type,:"[]=",*args)
-      changing(change_type,:trigger=>:"[]=", :changes=>changes) {super}
-    end
-
-    override_mutators :added=>    ADD_METHODS,
-                      :modified=> MODIFIER_METHODS,
-                      :removed=>  REMOVE_METHODS
-
-    def changes_for(change_type, trigger_method, *args, &block)
-      prev = self.dup.to_a
-      if change_type == :added
-        case trigger_method
-          when :"[]=" then lambda {{:added=>args[-1]}}
-          when :<<, :push, :unshift then lambda {{:added=>args}}
-          when :concat then lambda {{:added=>args[0]}}
-          when :insert then lambda {{:added=>args[1..-1]}}
-          else lambda { |cur| {:added=>(cur - prev).uniq }}
-        end
-      elsif change_type == :removed
-        case trigger_method
-          when :delete then lambda {{:removed=>args}}
-          when :delete_at then lambda {{:removed=>[prev[args[0]]]}}
-          when :delete_if, :reject! then lambda {{:removed=>prev.select(&block)}}
-          when :pop then lambda {{:removed=>[prev[-1]]}}
-          when :shift then lambda {{:removed=>[prev[0]]}}
-          else lambda { |cur| {:removed=>(prev - cur).uniq }}
-        end
-      else
-        case trigger_method
-          when :replace then lambda {{:removed=>prev, :added=>args[0]}}
-          when :"[]=" then lambda {{:removed=>[prev[*args[0..-2]]].flatten, :added=>[args[-1]].flatten}}
-          else lambda {|cur|{:removed=>prev.uniq, :added=>cur}}
-        end
-      end
-    end
-  end
-end
+
+module Observables
+  module ArrayWatcher
+    include Observables::Base
+
+    ADD_METHODS =       :<<, :push, :concat, :insert, :unshift
+    MODIFIER_METHODS =  :collect!, :map!, :flatten!, :replace, :reverse!, :sort!, :fill
+    REMOVE_METHODS =    :clear, :compact!, :delete, :delete_at, :delete_if, :pop, :reject!, :shift, :slice!, :uniq!
+
+    #[]= can either be an add method or a modifier method depending on
+    #if the previous key exists
+    def []=(*args)
+      change_type = args[0] >= length ? :added : :modified
+      changes = changes_for(change_type,:"[]=",*args)
+      changing(change_type,:trigger=>:"[]=", :changes=>changes) {super}
+    end
+
+    override_mutators :added=>    ADD_METHODS,
+                      :modified=> MODIFIER_METHODS,
+                      :removed=>  REMOVE_METHODS
+
+    def changes_for(change_type, trigger_method, *args, &block)
+      prev = self.dup.to_a
+      if change_type == :added
+        case trigger_method
+          when :"[]=" then lambda {{:added=>args[-1]}}
+          when :<<, :push, :unshift then lambda {{:added=>args}}
+          when :concat then lambda {{:added=>args[0]}}
+          when :insert then lambda {{:added=>args[1..-1]}}
+          else lambda { |cur| {:added=>(cur - prev).uniq }}
+        end
+      elsif change_type == :removed
+        case trigger_method
+          when :delete then lambda {{:removed=>args}}
+          when :delete_at then lambda {{:removed=>[prev[args[0]]]}}
+          when :delete_if, :reject! then lambda {{:removed=>prev.select(&block)}}
+          when :pop then lambda {{:removed=>[prev[-1]]}}
+          when :shift then lambda {{:removed=>[prev[0]]}}
+          else lambda { |cur| {:removed=>(prev - cur).uniq }}
+        end
+      else
+        case trigger_method
+          when :replace then lambda {{:removed=>prev, :added=>args[0]}}
+          when :"[]=" then lambda {{:removed=>[prev[*args[0..-2]]].flatten, :added=>[args[-1]].flatten}}
+          else lambda {|cur|{:removed=>prev.uniq, :added=>cur}}
+        end
+      end
+    end
+  end
+end

data/lib/observables/base.rb

@@ -1,94 +1,97 @@
-require 'active_support/concern'
-require "active_support/notifications/fanout"
-require 'active_support/core_ext/object/duplicable'
-require 'active_support/core_ext/array/extract_options'
-
-module Observables
-  module Base
-    extend ActiveSupport::Concern
-
-    module InstanceMethods
-      def notifier
-        @notifier ||= ActiveSupport::Notifications::Fanout.new
-      end
-
-      def subscribe(pattern=nil,&block)
-        notifier.subscribe(pattern,&block)
-      end
-
-      def unsubscribe(subscriber)
-        notifier.unsubscribe(subscriber)
-      end
-
-      def dup
-        super.tap {|s|s.make_observable}
-      end
-
-      def set_observer(*args,&block)
-        clear_observer
-        opts = args.extract_options!
-        @_observer_owner = args.pop
-        pattern = opts[:pattern] || /.*/
-        callback_method = opts[:callback_method] || :child_changed
-        @_owner_subscription = subscribe(pattern) do |*args|
-          block ? block.call(self,*args) :
-                  (@_observer_owner.send(callback_method,self,*args) if @_observer_owner && @_observer_owner.respond_to?(callback_method))
-        end
-      end
-
-      def clear_observer
-        unsubscribe(@_owner_subscription) if @_owner_subscription
-        @_owner_subscription = nil
-      end
-
-      protected
-
-      def changing(change_type,opts={})
-        args = create_event_args(change_type,opts)
-        notifier.publish "before_#{change_type}".to_sym, args
-        yield.tap do
-          notifier.publish "after_#{change_type}".to_sym, args
-        end
-      end
-
-      def create_event_args(change_type,opts={})
-        args = {:change_type=>change_type, :current_values=>self}.merge(opts)
-        class << args
-          def changes
-            chgs, cur_values = self[:changes], self[:current_values]
-            chgs && chgs.respond_to?(:call) ? chgs.call(cur_values) : chgs
-          end
-
-          def method_missing(method)
-            self.keys.include?(method) ? self[method] : super
-          end
-        end
-        args.delete(:current)
-        args
-      end
-
-      def changes_for(change_type,trigger_method,*args,&block)
-        #This method should return a lambda that takes the current
-        #value of the collection as an argument, and returns
-        #the expected changes that will result from trigger_method
-        nil
-      end
-    end
-
-    module ClassMethods
-      def override_mutators(change_groups)
-        change_groups.each_pair do |change_type,methods|
-          methods.each do |method|
-            class_eval <<-EOS
-              def #{method}(*args,&block)
-                changes = changes_for(:#{change_type},:#{method},*args,&block)
-                changing(:#{change_type},:trigger=>:#{method}, :changes=>changes){super}
-              end
-            EOS
-          end
-        end
-      end
-    end
-
-  end
-end
+require 'active_support/concern'
+require "active_support/notifications/fanout"
+require 'active_support/core_ext/object/duplicable'
+require 'active_support/core_ext/array/extract_options'
+
+module Observables
+  module Base
+    extend ActiveSupport::Concern
+
+    module InstanceMethods
+      def notifier
+        @notifier ||= ActiveSupport::Notifications::Fanout.new
+      end
+
+      def subscribe(pattern=nil,&block)
+        notifier.subscribe(pattern,&block)
+      end
+
+      def unsubscribe(subscriber)
+        notifier.unsubscribe(subscriber)
+      end
+
+      def dup
+        #This check is necessary in case a proxy is made observable,
+        #with an impementation of dup that returns its non-observable
+        #target
+        super.tap {|s| s.make_observable if s.respond_to?(:make_observable) }
+      end
+
+      def set_observer(*args,&block)
+        clear_observer
+        opts = args.extract_options!
+        @_observer_owner = args.pop
+        pattern = opts[:pattern] || /.*/
+        callback_method = opts[:callback_method] || :child_changed
+        @_owner_subscription = subscribe(pattern) do |*args|
+          block ? block.call(self,*args) :
+                  (@_observer_owner.send(callback_method,self,*args) if @_observer_owner && @_observer_owner.respond_to?(callback_method))
+        end
+      end
+
+      def clear_observer
+        unsubscribe(@_owner_subscription) if @_owner_subscription
+        @_owner_subscription = nil
+      end
+
+      protected
+
+      def changing(change_type,opts={})
+        args = create_event_args(change_type,opts)
+        notifier.publish "before_#{change_type}".to_sym, args
+        yield.tap do
+          notifier.publish "after_#{change_type}".to_sym, args
+        end
+      end
+
+      def create_event_args(change_type,opts={})
+        args = {:change_type=>change_type, :current_values=>self}.merge(opts)
+        class << args
+          def changes
+            chgs, cur_values = self[:changes], self[:current_values]
+            chgs && chgs.respond_to?(:call) ? chgs.call(cur_values) : chgs
+          end
+
+          def method_missing(method)
+            self.keys.include?(method) ? self[method] : super
+          end
+        end
+        args.delete(:current)
+        args
+      end
+
+      def changes_for(change_type,trigger_method,*args,&block)
+        #This method should return a lambda that takes the current
+        #value of the collection as an argument, and returns
+        #the expected changes that will result from trigger_method
+        nil
+      end
+    end
+
+    module ClassMethods
+      def override_mutators(change_groups)
+        change_groups.each_pair do |change_type,methods|
+          methods.each do |method|
+            class_eval <<-EOS
+              def #{method}(*args,&block)
+                changes = changes_for(:#{change_type},:#{method},*args,&block)
+                changing(:#{change_type},:trigger=>:#{method}, :changes=>changes){super}
+              end
+            EOS
+          end
+        end
+      end
+    end
+
+  end
+end