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