* lib/observer.rb: Improve documentation. Patch by David Copeland.
[Ruby 1.9 - Bug #4707] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31599 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
parent
61a5a6393d
commit
1234af557b
@ -1,3 +1,8 @@
|
|||||||
|
Tue May 17 06:50:40 2011 Eric Hodel <drbrain@segment7.net>
|
||||||
|
|
||||||
|
* lib/observer.rb: Improve documentation. Patch by David Copeland.
|
||||||
|
[Ruby 1.9 - Bug #4707]
|
||||||
|
|
||||||
Tue May 17 06:42:53 2011 Eric Hodel <drbrain@segment7.net>
|
Tue May 17 06:42:53 2011 Eric Hodel <drbrain@segment7.net>
|
||||||
|
|
||||||
* lib/logger.rb: Improve documentation. Patch by David Copeland.
|
* lib/logger.rb: Improve documentation. Patch by David Copeland.
|
||||||
|
@ -1,33 +1,34 @@
|
|||||||
#
|
#
|
||||||
# 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
|
# following documentation is copied, with modifications, from "Programming
|
||||||
# Ruby", by Hunt and Thomas; http://www.rubycentral.com/book/lib_patterns.html.
|
# Ruby", by Hunt and Thomas; http://www.rubycentral.com/book/lib_patterns.html.
|
||||||
#
|
#
|
||||||
# == About
|
# See Observable for more info.
|
||||||
#
|
|
||||||
# The Observer pattern, also known as Publish/Subscribe, provides a simple
|
# The Observer pattern (also known as publish/subscribe) provides a simple
|
||||||
# mechanism for one object to inform a set of interested third-party objects
|
# mechanism for one object to inform a set of interested third-party objects
|
||||||
# when its state changes.
|
# when its state changes.
|
||||||
#
|
#
|
||||||
# == Mechanism
|
# == 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
|
# module, which provides the methods for managing the associated observer
|
||||||
# objects.
|
# 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:
|
# The observable object must:
|
||||||
# * assert that it has +changed+
|
# * assert that it has +#changed+
|
||||||
# * call +notify_observers+
|
# * call +#notify_observers+
|
||||||
#
|
#
|
||||||
# == Example
|
# === Example
|
||||||
#
|
#
|
||||||
# The following example demonstrates this nicely. A +Ticker+, when run,
|
# 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 <tt>@symbol</tt>. A +Warner+
|
||||||
# general observer of the price, and two warners are demonstrated, a +WarnLow+
|
# is a general observer of the price, and two warners are demonstrated, a
|
||||||
# and a +WarnHigh+, which print a warning if the price is below or above their
|
# +WarnLow+ and a +WarnHigh+, which print a warning if the price is below or
|
||||||
# set limits, respectively.
|
# above their set limits, respectively.
|
||||||
#
|
#
|
||||||
# The +update+ callback allows the warners to run without being explicitly
|
# The +update+ callback allows the warners to run without being explicitly
|
||||||
# called. The system is set up with the +Ticker+ and several observers, and the
|
# called. The system is set up with the +Ticker+ and several observers, and the
|
||||||
@ -108,19 +109,20 @@
|
|||||||
# Current price: 112
|
# Current price: 112
|
||||||
# Current price: 79
|
# Current price: 79
|
||||||
# --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 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
|
module Observable
|
||||||
|
|
||||||
#
|
#
|
||||||
# Add +observer+ as an observer on this object. +observer+ will now receive
|
# Add +observer+ as an observer on this object. so that it will receive
|
||||||
# notifications. The second optional argument specifies a method to notify
|
# notifications.
|
||||||
# updates, of which default value is +update+.
|
|
||||||
#
|
#
|
||||||
|
# +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 <tt>*arg</tt> when #notify_observers is called, where
|
||||||
|
# <tt>*arg</tt> is the value passed to #notify_observers by this
|
||||||
|
# Observable
|
||||||
def add_observer(observer, func=:update)
|
def add_observer(observer, func=:update)
|
||||||
@observer_peers = {} unless defined? @observer_peers
|
@observer_peers = {} unless defined? @observer_peers
|
||||||
unless observer.respond_to? func
|
unless observer.respond_to? func
|
||||||
@ -130,15 +132,16 @@ module Observable
|
|||||||
end
|
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
|
||||||
# notifications.
|
# receive notifications.
|
||||||
#
|
#
|
||||||
|
# +observer+:: An observer of this Observable
|
||||||
def delete_observer(observer)
|
def delete_observer(observer)
|
||||||
@observer_peers.delete observer if defined? @observer_peers
|
@observer_peers.delete observer if defined? @observer_peers
|
||||||
end
|
end
|
||||||
|
|
||||||
#
|
#
|
||||||
# Delete all observers associated with this object.
|
# Remove all observers associated with this object.
|
||||||
#
|
#
|
||||||
def delete_observers
|
def delete_observers
|
||||||
@observer_peers.clear if defined? @observer_peers
|
@observer_peers.clear if defined? @observer_peers
|
||||||
@ -159,12 +162,15 @@ module Observable
|
|||||||
# Set the changed state of this object. Notifications will be sent only if
|
# Set the changed state of this object. Notifications will be sent only if
|
||||||
# the changed +state+ is +true+.
|
# the changed +state+ is +true+.
|
||||||
#
|
#
|
||||||
|
# +state+:: Boolean indicating the changed state of this Observable.
|
||||||
|
#
|
||||||
def changed(state=true)
|
def changed(state=true)
|
||||||
@observer_state = state
|
@observer_state = state
|
||||||
end
|
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?
|
def changed?
|
||||||
if defined? @observer_state and @observer_state
|
if defined? @observer_state and @observer_state
|
||||||
@ -175,16 +181,19 @@ module Observable
|
|||||||
end
|
end
|
||||||
|
|
||||||
#
|
#
|
||||||
# If this object's changed state is +true+, invoke the update method in each
|
# Notify observers of a change in state *if* this object's changed state is
|
||||||
# currently associated observer in turn, passing it the given arguments. The
|
# +true+.
|
||||||
# changed state is then set to +false+.
|
|
||||||
#
|
#
|
||||||
|
# This will invoke the method named in #add_observer, pasing <tt>*arg</tt>.
|
||||||
|
# The changed state is then set to +false+.
|
||||||
|
#
|
||||||
|
# <tt>*arg</tt>:: Any arguments to pass to the observers.
|
||||||
def notify_observers(*arg)
|
def notify_observers(*arg)
|
||||||
if defined? @observer_state and @observer_state
|
if defined? @observer_state and @observer_state
|
||||||
if defined? @observer_peers
|
if defined? @observer_peers
|
||||||
@observer_peers.each { |k, v|
|
@observer_peers.each do |k, v|
|
||||||
k.send v, *arg
|
k.send v, *arg
|
||||||
}
|
end
|
||||||
end
|
end
|
||||||
@observer_state = false
|
@observer_state = false
|
||||||
end
|
end
|
||||||
|
Loading…
x
Reference in New Issue
Block a user