From 73732302509b86d4e3161b3caa0dc9ce6a5fa476 Mon Sep 17 00:00:00 2001 From: Dave Copeland Date: Sun, 15 May 2011 15:16:13 -0400 Subject: [PATCH 5/6] clean up and add documentation to Observrable --- lib/observer.rb | 59 ++++++++++++++++++++++++++++-------------------------- 1 files changed, 31 insertions(+), 28 deletions(-) diff --git a/lib/observer.rb b/lib/observer.rb index ee3f01b..22ec6e6 100644 --- a/lib/observer.rb +++ b/lib/observer.rb @@ -1,30 +1,30 @@ # -# observer.rb implements the _Observer_ object-oriented design pattern. The +# Implementation of the _Observer_ object-oriented design pattern. The # following documentation is copied, with modifications, from "Programming # Ruby", by Hunt and Thomas; http://www.rubycentral.com/book/lib_patterns.html. # -# == About -# -# The Observer pattern, also known as Publish/Subscribe, provides a simple +# See Observable for more info. + +# The Observer pattern (also known as publish/subscribe) provides a simple # mechanism for one object to inform a set of interested third-party objects # when its state changes. # # == Mechanism # -# In the Ruby implementation, the notifying class mixes in the +Observable+ +# The notifying class mixes in the +Observable+ # module, which provides the methods for managing the associated observer # objects. # -# The observers must implement the +update+ method to receive notifications. +# The observers must implement a method called +update+ to receive notifications. # # The observable object must: -# * assert that it has +changed+ -# * call +notify_observers+ +# * assert that it has +#changed+ +# * call +#notify_observers+ # -# == Example +# === Example # # The following example demonstrates this nicely. A +Ticker+, when run, -# continually receives the stock +Price+ for its +@symbol+. A +Warner+ is a +# continually receives the stock +Price+ for its @symbol. A +Warner+ is a # general observer of the price, and two warners are demonstrated, a +WarnLow+ # and a +WarnHigh+, which print a warning if the price is below or above their # set limits, respectively. @@ -108,19 +108,17 @@ # Current price: 112 # Current price: 79 # --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 79 - - -# -# Implements the Observable design pattern as a mixin so that other objects can -# be notified of changes in state. See observer.rb for details and an example. -# module Observable # - # Add +observer+ as an observer on this object. +observer+ will now receive - # notifications. The second optional argument specifies a method to notify - # updates, of which default value is +update+. + # Add +observer+ as an observer on this object. so that it will receive + # notifications. # + # +observer+:: the object that will be notified of changes. + # +func+:: Symbol naming the method that will be called when this Observable has changes. + # This method must return true for +observer.respond_to?+ and will + # receive *arg when #notify_observers is called, where *arg + # is the value passed to #notify_observers by this Observable def add_observer(observer, func=:update) @observer_peers = {} unless defined? @observer_peers unless observer.respond_to? func @@ -130,15 +128,16 @@ module Observable end # - # Delete +observer+ as an observer on this object. It will no longer receive + # Remove +observer+ as an observer on this object so that it will no longer receive # notifications. # + # +observer+:: An observer of this Observable def delete_observer(observer) @observer_peers.delete observer if defined? @observer_peers end # - # Delete all observers associated with this object. + # Remove all observers associated with this object. # def delete_observers @observer_peers.clear if defined? @observer_peers @@ -159,12 +158,15 @@ module Observable # Set the changed state of this object. Notifications will be sent only if # the changed +state+ is +true+. # + # +state+:: Boolean indicating the changed state of this Observable. + # def changed(state=true) @observer_state = state end # - # Query the changed state of this object. + # Returns true if this object's state has been changed since the last + # #notify_observers call. # def changed? if defined? @observer_state and @observer_state @@ -175,16 +177,17 @@ module Observable end # - # If this object's changed state is +true+, invoke the update method in each - # currently associated observer in turn, passing it the given arguments. The - # changed state is then set to +false+. + # Notify observers of a change in state *if* this object's changed state is +true+. + # This will invoke the method named in #add_observer, pasing *arg. + # The changed state is then set to +false+. # + # *arg:: Any arguments to pass to the observers. def notify_observers(*arg) if defined? @observer_state and @observer_state if defined? @observer_peers - @observer_peers.each { |k, v| - k.send v, *arg - } + @observer_peers.each do |k, v| + k.send v, *arg + end end @observer_state = false end -- 1.7.3.4