= 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.