swerling-cosell 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+pkg/
+doc/

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.1 / 2009-07-07
+
+* initial release

data/README.rdoc

@@ -0,0 +1,187 @@
+cosell
+    by Steven Swerling
+    http://tab-a.slot-z.net
+
+== DESCRIPTION:
+
+Cosell is a minimal implementation of the 'Announcements' observer
+framework, originally introduced in VisualWorks Smalltalk 7.4 as a
+replacement for 'triggerEvent' style of event notification.  Instead of
+triggering events identified by symbols, the events are first class
+objects.  For rationale, please see the original blog posting by Vassili
+Bykov (refs below).
+
+*Lineage*
+
+This implementation is loosely based on Lukas Renggli's tweak of Colin Putney's
+Squeak implementation of Vassili Bykov's Announcements framework for
+VisualWorks Smalltalk.  (Specifically Announcements-lr.13.mcz was used as
+a reference.)
+
+Liberties where taken during the port. In particular, the Announcer class
+in the Smalltalk version is implemented here as a ruby module which can be
+mixed into any object. Also, in this implementation any object (or class)
+can serve as an announcement, so no Announcement class is implemented. 
+
+The ability to queue announcements in the background is built into cosell.
+
+<b>The Name 'Cosell'</b>
+
+I chose the name 'Cosell' because 
+
+a. Howard Cosell is an iconic event announcer
+b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced scads of results about ruby meetups, conferences, and the like. So I went with something a bit cryptic but hopefully a little more searchable. 
+
+*See*
+
+* {Original blog posting describing Announcments by Vassili Bykov}[http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?entry=3310034894]
+* {More info on the Announcements Framework}[http://wiki.squeak.org/squeak/5734]
+
+== FEATURE
+
+* Announcements-style event observer framework
+* Easy way to queue events in background
+
+== PROBLEMS
+
+* None known. Should work in ruby 1.8 and 1.9.
+
+== SYNOPSIS:
+
+
+  (this example is in the [gem]/example/basic_example.rb file)
+
+  #
+  #  Will produce the following output:
+  #
+  #       And now a word from our sponsor: 'the'
+  #       End of round 1
+  #       End of round 2
+  #       End of round 3
+  #       End of round 4
+  #       End of round 5
+  #       End of round 6
+  #       End of round 7
+  #       End of round 8
+  #       End of round 9
+  #       End of round 10
+  #       End of round 11
+  #       End of round 12
+  #       End of round 13
+  #       End of round 14
+  #       TKO!
+          
+  require 'rubygems'
+  require 'cosell'
+
+  # An announcer
+  class Howard
+    include Cosell
+  end
+
+  # a receiver of the announcements
+  class Television
+    def show(ann, opts={})
+      puts ann.to_s(opts)
+    end
+  end
+
+  # Some announcements
+  class Announcement
+    def to_s(opts={})
+      self.class.to_s + '!'
+    end
+  end
+  class WordFromOurSponsor < Announcement
+    attr_accessor :word
+    def to_s(opts={})
+      "And now a word from our sponsor: '#{word}'"
+    end
+  end
+  class EndOfRound < Announcement
+    def to_s(opts={})
+      "End of round #{opts[:round]}"
+    end
+  end
+  class KnockOut < Announcement; end
+  class TKO < KnockOut; end
+
+
+  # ------- Start announcing -------
+
+  # Create an announcer, and a subscriber
+  round = 1
+  howard = Howard.new
+  tv = Television.new
+  howard.when_announcing(WordFromOurSponsor, KnockOut) { |ann| tv.show(ann) }
+
+  # Make an announcement
+  announcement = WordFromOurSponsor.new
+  announcement.word = 'the'
+  howard.announce(announcement) 
+    # => And know a word from our sponsors: 'the' 
+
+  # Make another announcement 
+  howard.announce(EndOfRound) 
+    # => nothing, you haven't subscribed yet to EndOfRound. Tree fell, nobody heard. Didn't happen.
+
+  # Create a second subscription
+  eor_subscription = lambda do |ann|
+    tv.show(ann, :round => round) 
+    round += 1 
+  end
+  howard.when_announcing(EndOfRound, &eor_subscription)
+
+  # Tell the announcer to use a background announcments queue
+  # Only allow the announcer to broadcast 5 announcments at a time
+  # before going to sleep for 0.05 seconds
+  howard.queue_announcements!(:sleep_time => 0.05, :announcements_per_cycle => 5)
+
+  # Start making announcments (they will be queueud in the background)
+  14.times {howard.announce(EndOfRound)} 
+
+  sleep 0.05 # announcements for the first 5 rounds appear
+  sleep 0.05 # announcements for the next 5 rounds
+  sleep 0.05 # announcements for end of the next 4 rounds (there is not 15th round
+  sleep 0.05 # no announcements, all the announcements have been announced
+
+  # queue the final announcment
+  howard.announce(TKO) 
+      # => TKO!
+
+  sleep 0.05 # the TKO is broadcast
+
+== REQUIREMENTS:
+
+* ruby, rubygems
+
+== INSTALL:
+
+
+  gem install swerling-cosell --source http://gems.github.com
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 
+
+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.txt

@@ -0,0 +1,187 @@
+cosell
+    by Steven Swerling
+    http://tab-a.slot-z.net
+
+== DESCRIPTION:
+
+Cosell is a minimal implementation of the 'Announcements' observer
+framework, originally introduced in VisualWorks Smalltalk 7.4 as a
+replacement for 'triggerEvent' style of event notification.  Instead of
+triggering events identified by symbols, the events are first class
+objects.  For rationale, please see the original blog posting by Vassili
+Bykov (refs below).
+
+*Lineage*
+
+This implementation is loosely based on Lukas Renggli's tweak of Colin Putney's
+Squeak implementation of Vassili Bykov's Announcements framework for
+VisualWorks Smalltalk.  (Specifically Announcements-lr.13.mcz was used as
+a reference.)
+
+Liberties where taken during the port. In particular, the Announcer class
+in the Smalltalk version is implemented here as a ruby module which can be
+mixed into any object. Also, in this implementation any object (or class)
+can serve as an announcement, so no Announcement class is implemented. 
+
+The ability to queue announcements in the background is built into cosell.
+
+<b>The Name 'Cosell'</b>
+
+I chose the name 'Cosell' because 
+
+a. Howard Cosell is an iconic event announcer
+b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced scads of results about ruby meetups, conferences, and the like. So I went with something a bit cryptic but hopefully a little more searchable. 
+
+*See*
+
+* {Original blog posting describing Announcments by Vassili Bykov}[http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?entry=3310034894]
+* {More info on the Announcements Framework}[http://wiki.squeak.org/squeak/5734]
+
+== FEATURE
+
+* Announcements-style event observer framework
+* Easy way to queue events in background
+
+== PROBLEMS
+
+* None known. Should work in ruby 1.8 and 1.9.
+
+== SYNOPSIS:
+
+
+  (this example is in the [gem]/example/basic_example.rb file)
+
+  #
+  #  Will produce the following output:
+  #
+  #       And now a word from our sponsor: 'the'
+  #       End of round 1
+  #       End of round 2
+  #       End of round 3
+  #       End of round 4
+  #       End of round 5
+  #       End of round 6
+  #       End of round 7
+  #       End of round 8
+  #       End of round 9
+  #       End of round 10
+  #       End of round 11
+  #       End of round 12
+  #       End of round 13
+  #       End of round 14
+  #       TKO!
+          
+  require 'rubygems'
+  require 'cosell'
+
+  # An announcer
+  class Howard
+    include Cosell
+  end
+
+  # a receiver of the announcements
+  class Television
+    def show(ann, opts={})
+      puts ann.to_s(opts)
+    end
+  end
+
+  # Some announcements
+  class Announcement
+    def to_s(opts={})
+      self.class.to_s + '!'
+    end
+  end
+  class WordFromOurSponsor < Announcement
+    attr_accessor :word
+    def to_s(opts={})
+      "And now a word from our sponsor: '#{word}'"
+    end
+  end
+  class EndOfRound < Announcement
+    def to_s(opts={})
+      "End of round #{opts[:round]}"
+    end
+  end
+  class KnockOut < Announcement; end
+  class TKO < KnockOut; end
+
+
+  # ------- Start announcing -------
+
+  # Create an announcer, and a subscriber
+  round = 1
+  howard = Howard.new
+  tv = Television.new
+  howard.when_announcing(WordFromOurSponsor, KnockOut) { |ann| tv.show(ann) }
+
+  # Make an announcement
+  announcement = WordFromOurSponsor.new
+  announcement.word = 'the'
+  howard.announce(announcement) 
+    # => And know a word from our sponsors: 'the' 
+
+  # Make another announcement 
+  howard.announce(EndOfRound) 
+    # => nothing, you haven't subscribed yet to EndOfRound. Tree fell, nobody heard. Didn't happen.
+
+  # Create a second subscription
+  eor_subscription = lambda do |ann|
+    tv.show(ann, :round => round) 
+    round += 1 
+  end
+  howard.when_announcing(EndOfRound, &eor_subscription)
+
+  # Tell the announcer to use a background announcments queue
+  # Only allow the announcer to broadcast 5 announcments at a time
+  # before going to sleep for 0.05 seconds
+  howard.queue_announcements!(:sleep_time => 0.05, :announcements_per_cycle => 5)
+
+  # Start making announcments (they will be queueud in the background)
+  14.times {howard.announce(EndOfRound)} 
+
+  sleep 0.05 # announcements for the first 5 rounds appear
+  sleep 0.05 # announcements for the next 5 rounds
+  sleep 0.05 # announcements for end of the next 4 rounds (there is not 15th round
+  sleep 0.05 # no announcements, all the announcements have been announced
+
+  # queue the final announcment
+  howard.announce(TKO) 
+      # => TKO!
+
+  sleep 0.05 # the TKO is broadcast
+
+== REQUIREMENTS:
+
+* ruby, rubygems
+
+== INSTALL:
+
+
+  gem install swerling-cosell --source http://gems.github.com
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 
+
+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/Rakefile

@@ -0,0 +1,41 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'cosell'
+
+task :default => 'spec:run'
+
+PROJ.name = 'cosell'
+PROJ.authors = 'Steven Swerling'
+PROJ.email = 'sswerling@yahoo.com'
+PROJ.url = 'http://github.com/swerling/TODO'
+PROJ.version = Cosell::VERSION
+PROJ.rubyforge.name = 'cosell'
+
+PROJ.spec.opts << '--color'
+
+PROJ.rdoc.opts = ["--inline-source"]
+
+namespace :my do
+  namespace :gem do
+    task :package => [:clobber] do
+      sh "rm -rf #{File.join(File.dirname(__FILE__), 'pkg')}"
+      sh "rm -rf #{File.join(File.dirname(__FILE__), 'doc')}"
+      Rake::Task['gem:package'].invoke
+    end
+  end
+end
+

data/cosell.gemspec

@@ -0,0 +1,64 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{cosell}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Steven Swerling"]
+  s.date = %q{2009-07-18}
+  s.description = %q{Cosell is a minimal implementation of the 'Announcements' observer
+framework, originally introduced in VisualWorks Smalltalk 7.4 as a
+replacement for 'triggerEvent' style of event notification.  Instead of
+triggering events identified by symbols, the events are first class
+objects.  For rationale, please see the original blog posting by Vassili
+Bykov (refs below).
+
+*Lineage*
+
+This implementation is loosely based on Lukas Renggli's tweak of Colin Putney's
+Squeak implementation of Vassili Bykov's Announcements framework for
+VisualWorks Smalltalk.  (Specifically Announcements-lr.13.mcz was used as
+a reference.)
+
+Liberties where taken during the port. In particular, the Announcer class
+in the Smalltalk version is implemented here as a ruby module which can be
+mixed into any object. Also, in this implementation any object (or class)
+can serve as an announcement, so no Announcement class is implemented. 
+
+The ability to queue announcements in the background is built into cosell.
+
+<b>The Name 'Cosell'</b>
+
+I chose the name 'Cosell' because 
+
+a. Howard Cosell is an iconic event announcer
+b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced scads of results about ruby meetups, conferences, and the like. So I went with something a bit cryptic but hopefully a little more searchable. 
+
+*See*
+
+* {Original blog posting describing Announcments by Vassili Bykov}[http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?entry=3310034894]
+* {More info on the Announcements Framework}[http://wiki.squeak.org/squeak/5734]}
+  s.email = %q{sswerling@yahoo.com}
+  s.extra_rdoc_files = ["History.txt", "README.rdoc", "README.txt"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "README.txt", "Rakefile", "cosell.gemspec", "example/basic_example.rb", "example/cat_whisperer.rb", "lib/cosell.rb", "lib/cosell/announcer.rb", "lib/cosell/monkey.rb", "spec/cosell_spec.rb", "spec/spec_helper.rb"]
+  s.homepage = %q{http://github.com/swerling/TODO}
+  s.rdoc_options = ["--inline-source", "--main", "README.txt"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{cosell}
+  s.rubygems_version = %q{1.3.3}
+  s.summary = %q{Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk 7}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bones>, [">= 2.4.0"])
+    else
+      s.add_dependency(%q<bones>, [">= 2.4.0"])
+    end
+  else
+    s.add_dependency(%q<bones>, [">= 2.4.0"])
+  end
+end

data/example/basic_example.rb

@@ -0,0 +1,99 @@
+#
+#  Will produce the following output:
+#
+#       And now a word from our sponsor: 'the'
+#       End of round 1
+#       End of round 2
+#       End of round 3
+#       End of round 4
+#       End of round 5
+#       End of round 6
+#       End of round 7
+#       End of round 8
+#       End of round 9
+#       End of round 10
+#       End of round 11
+#       End of round 12
+#       End of round 13
+#       End of round 14
+#       TKO!
+        
+require 'rubygems'
+require 'cosell'
+
+# An announcer
+class Howard
+  include Cosell
+end
+
+# a receiver of the announcements
+class Television
+  def show(ann, opts={})
+    puts ann.to_s(opts)
+  end
+end
+
+# Some announcements
+class Announcement
+  def to_s(opts={})
+    self.class.to_s + '!'
+  end
+end
+class WordFromOurSponsor < Announcement
+  attr_accessor :word
+  def to_s(opts={})
+    "And now a word from our sponsor: '#{word}'"
+  end
+end
+class EndOfRound < Announcement
+  def to_s(opts={})
+    "End of round #{opts[:round]}"
+  end
+end
+class KnockOut < Announcement; end
+class TKO < KnockOut; end
+
+
+# ------- Start announcing -------
+
+# Create an announcer, and a subscriber
+round = 1
+howard = Howard.new
+tv = Television.new
+howard.when_announcing(WordFromOurSponsor, KnockOut) { |ann| tv.show(ann) }
+
+# Make an announcement
+announcement = WordFromOurSponsor.new
+announcement.word = 'the'
+howard.announce(announcement) 
+   # => And know a word from our sponsors: 'the' 
+
+# Make another announcement 
+howard.announce(EndOfRound) 
+  # => nothing, you haven't subscribed yet to EndOfRound. Tree fell, nobody heard. Didn't happen.
+
+# Create a second subscription
+eor_subscription = lambda do |ann|
+  tv.show(ann, :round => round) 
+  round += 1 
+end
+howard.when_announcing(EndOfRound, &eor_subscription)
+
+# Tell the announcer to use a background announcments queue
+# Only allow the announcer to broadcast 5 announcments at a time
+# before going to sleep for 0.05 seconds
+howard.queue_announcements!(:sleep_time => 0.05, :announcements_per_cycle => 5)
+
+# Start making announcments (they will be queueud in the background)
+14.times {howard.announce(EndOfRound)} 
+
+sleep 0.05 # announcements for the first 5 rounds appear
+sleep 0.05 # announcements for the next 5 rounds
+sleep 0.05 # announcements for end of the next 4 rounds (there is not 15th round
+sleep 0.05 # no announcements, all the announcements have been announced
+
+# queue the final announcment
+howard.announce(TKO) 
+    # => TKO!
+
+sleep 0.05 # the TKO is broadcast

data/example/cat_whisperer.rb

@@ -0,0 +1,87 @@
+#
+# Sits by window, talks to cats
+#
+class CatWhisperer
+  include Cosell::Announcer
+end
+
+#
+# events that occur in the home
+#
+class SomeoneEnteringHome
+  attr_accessor :who_is_entering
+end
+class OwnerEnteringHome < SomeoneEnteringHome; end
+class BurglerEnteringHome < SomeoneEnteringHome; end
+class DogEnteringHome < SomeoneEnteringHome; end
+class BirdEnteringHome < SomeoneEnteringHome; end
+
+#
+# participants
+#
+class Cat
+end
+class NormalSizedCat < Cat
+  def deal_with_dog(dog)
+    if dog.running_at_cat?(self)
+      puts "run to bookshelf; climb bookshelf; feign indifference"
+    else
+      puts "feign indifference; saunter to bookshelf; climb bookshelf; feign indifference"
+    end
+  end
+  def deal_with_burgler(burgler)
+    puts "feign indifference"
+  end
+  def deal_with_owner(owner)
+    puts "feign indifference while slowly sauntering towards owner; " \
+       + "nuzzle owner; receive affection; try to feign indifference; break down and start purring"
+  end
+
+end
+
+class ReallyBigCat < Cat
+  def eat(who)
+    puts "Really big cat eats #{who}"
+  end
+  def deal_with_burgler(burgler)
+    eat('burgler')
+  end
+  def deal_with_owner(owner)
+    eat('owner')
+  end
+  def deal_with_dog(owner)
+    eat('dog')
+  end
+end
+
+cat_whisperer = CatWhisperer.new
+really_big_cat = ReallyBigCat.new
+regular_cat = NormalSizedCat.new
+
+#
+# wire up events
+#
+cat_whisperer.when_announcing(DogEnteringHome) do |event|
+  cat.deal_with_dog(event.who_is_entering)
+  rally_big_cat.deal_with_dog(event.who_is_entering)
+end
+cat_whisperer.when_announcing(DogEnteringHome, :send => |event|
+  cat.deal_with_dog(event.who_is_entering)
+  rally_big_cat.deal_with_dog(event.who_is_entering)
+end
+
+cat_whisperer.when_announcing(OwnerEnteringHome) do |event|
+  cat.deal_with_person(dog_entering_event.who_is_entering)
+  rally_big_cat.deal_with_dog(dog_entering_event.who_is_entering)
+end
+
+cat_whisperer.when_announcing(BurglerEnteringHome) do |event|
+  cat.deal_with_person(event.who_is_entering)
+  rally_big_cat.deal_with_dog(event.who_is_entering)
+end
+
+#
+# Mayhem ensues
+#
+cat_whisperer.announce(OwnerEnteringHome.new)
+ # => 

data/lib/cosell.rb

@@ -0,0 +1,48 @@
+module Cosell 
+
+  # :stopdoc:
+  VERSION = '0.0.1'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+  # :startdoc:
+
+end  # module Cosell
+
+Cosell.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/cosell/announcer.rb

@@ -0,0 +1,223 @@
+require 'logger'
+
+module Cosell
+
+    def initialize *args
+      initialize_cosell!
+      super
+    end
+
+    #
+    #
+    #           ANNOUNCEMENTS QUEUE
+    #
+    #
+
+    # Place all announcments in a queue, and make announcements in a background thread.
+    #
+    # Options:
+    #    :sleep_time => how long to sleep (in seconds) after making a batch of announchements 
+    #                   default: 0.01
+    #    :announcements_per_cycle => how many announcements to make before sleeping for sleep_time
+    #                   default: 25
+    #    :logger => a logger. Where to log exceptions and warnings.
+    #
+    # Note: at the moment, this method may only be called once, and cannot be undone. There is
+    # no way to interrupt the thread.
+    
+    def queue_announcements!(opts = {})
+
+      self.initialize_cosell_if_needed
+
+      # kill off the last queue first
+      if self.announcements_thread
+        kill_queue!
+        sleep 0.01
+        queue_announcements! opts
+      end
+
+      self.should_queue_announcements = true
+      @__announcements_queue ||= Queue.new
+
+      how_many_per_cycle = opts[:announcements_per_cycle] || 25
+      cycle_duration = opts[:sleep_time] || 0.01
+      self.queue_logger = opts[:logger]
+      count = 0
+
+      self.announcements_thread = Thread.new do 
+        begin
+          loop do
+            if queue_killed?
+              self.kill_announcement_queue = false
+              self.announcements_thread = nil
+              log "Announcement queue killed with #{self.announcements_queue.size} announcements still queued", :info
+              break
+            else
+              self.announce_now! self.announcements_queue.pop
+              count += 1
+              if (count%how_many_per_cycle).eql?(0)
+                log "Announcement queue finished batch of #{how_many_per_cycle}, sleeping for #{cycle_duration} sec", :debug
+                count = 0
+                sleep cycle_duration
+              end
+            end
+          end
+        rescue Exception => x
+          log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error
+        end
+      end
+
+    end
+
+    #
+    #
+    #           SUBSCRIBE/MAKE ANNOUNCEMENTS 
+    #
+    #
+
+    # Pass in an anouncement class (or array of announcement classes), along with a block defining the 
+    # action to be taken when an announcment of one of the specified classes is announced by this announcer.
+    # (see Cossell::Announcer for full explanation)
+    def subscribe *announce_classes, &block
+
+      self.initialize_cosell_if_needed
+
+      Array(announce_classes).each do |announce_class|
+        raise "Can only subscribe to classes. Not a class: #{announce_class}" unless announce_class.is_a?(Class)
+        self.subscriptions[announce_class] ||= []
+        self.subscriptions[announce_class] << lambda(&block)
+      end
+    end
+    alias_method :when_announcing, :subscribe
+
+    # Stop announcing for a given announcement class (or array of classes)
+    def unsubscribe *announce_classes
+      Array(announce_classes).each do |announce_class|
+        self.subscriptions.delete announce_class
+      end
+    end
+
+    # If queue_announcements? true, puts announcement in a Queue.
+    # Otherwise, calls announce_now!
+    # Queued announcements are announced in a background thread in batches 
+    # (see the #initialize method doc for details).
+    def announce announcement
+      if self.queue_announcements?
+        self.announcements_queue << announcement
+      else
+        self.announce_now! announcement
+      end
+    end
+
+    #
+    # First, an announcement is made by calling 'as_announcement' on an_announcement_or_announcement_factory,
+    # and subscribers to the announcement's class are then notified
+    #
+    # subscribers to this announcer will be filtered to those that match to the announcement's class,
+    # and those subscriptions will be 'fired'. Subscribers should use the 'subscribe' method (also
+    # called 'when_announcing') to configure actions to take when a given announcement is made.
+    #
+    # Typically, an announcement is passed in for an_announcement_factory, in
+    # which case as_announcement does nothing but return the announcement. But any class can override
+    # as_announcement to adapt into an anouncement as they see fit.
+    #
+    # (see Cossell::Announcer for full explanation)
+    #
+    def announce_now! an_announcement_or_announcement_factory
+      announcement = an_announcement_or_announcement_factory.as_announcement
+
+      self.subscriptions.each do |subscription_type, subscriptions_for_type |
+        if announcement.is_a?(subscription_type)
+          subscriptions_for_type.each{|subscription| subscription.call(announcement) }
+        end
+      end
+
+      return announcement 
+    end
+
+    #
+    #
+    #           DEBUG
+    #
+    #
+
+    # 
+    # Log a message every time this announcer makes an announcement
+    #
+    # Options:
+    #    :on => Which class of announcements to spy on. Default is Object (ie. all announcements)
+    #    :logger => The log to log to. Default is a logger on STDOUT
+    #    :level => The log level to log with. Default is :info
+    #    :preface => A message to prepend to all log messages. Default is "Announcement Spy: "
+    def spy!(opts = {})
+      on = opts[:on] || Object
+      logger = opts[:logger] || Logger.new(STDOUT)
+      level = opts[:level] || :info
+      preface = opts[:preface_with] || "Announcement Spy: "
+      self.subscribe(on){|ann| logger.send(level, "#{preface} #{ann.as_announcement_trace}")}
+    end
+
+    # lazy initialization of cosell.
+    # Optional -- calling this will get rid of any subsequent warnings about uninitialized ivs
+    # In most cases not necessary, and should never have an effect except to get rid of some warnings.
+    def initialize_cosell_if_needed
+      self.initialize_cosell! if @__subscriptions.nil? 
+    end
+
+    # Will blow away any queue, and reset all state.
+    # Should not be necessary to call this, but left public for testing.
+    def initialize_cosell!
+      # Using pseudo-scoped var names. 
+      # Unfortunately cant lazily init these w/out ruby warnings going berzerk in verbose mode,
+      # So explicitly declaring them here.
+      @__queue_announcements ||= false
+      @__announcements_queue ||= nil
+      @__kill_announcement_queue ||= false
+      @__announcements_thread ||= nil
+      @__subscriptions ||= {}
+      @__queue_logger ||= {}
+    end
+
+    # Kill the announcments queue.
+    # This is called automatically if you call queue_announcements!, before starting the next
+    # announcments thread, so it's optional. A way of stopping announcments.
+    def kill_queue!
+      @__kill_announcement_queue = true
+    end
+
+    # return whether annoucements are queued or sent out immediately when the #announce method is called.
+    def queue_announcements?
+      return @__queue_announcements.eql?(true)
+    end
+
+    protected
+      
+      #:stopdoc: 
+    
+      def log(msg, level = :info)
+        self.queue_logger.send(level, msg) if self.queue_logger
+      end
+
+      # return whether the queue was killed by kill_queue!
+      def queue_killed? 
+        @__kill_announcement_queue.eql?(true)
+      end
+
+      def queue_logger; @__queue_logger; end
+      def queue_logger= x; @__queue_logger = x; end
+      def announcements_queue; @__announcements_queue; end
+      def announcements_queue= x; @__announcements_queue = x; end
+      def announcements_thread; @__announcements_thread; end
+      def announcements_thread= x; @__announcements_thread = x; end
+      def kill_announcement_queue= x; @__kill_announcement_queue = x; end
+      def should_queue_announcements= x; @__queue_announcements = x; end
+      def subscriptions= x; @__subscriptions = x; end
+      def subscriptions; @__subscriptions; end
+
+      #:startdoc: 
+    public
+
+
+end
+
+

data/lib/cosell/monkey.rb

@@ -0,0 +1,32 @@
+#
+# Cosell is intended to be way for objects to 
+# communicate throughout the Object graph. It is _supposed_ to be
+# pervasive. As such, it has a few top-level methods that all objects inherit.
+#
+class Object
+
+  # When an object (or class) is announced, :as_announcement is called, the result of which
+  # becomes the announcement. By default just returns self, but can be overridden if appropriate.
+  # By default, simply return self.
+  def as_announcement
+    return self
+  end
+
+  # When cosell is configured to "spy!", the result of announement.as_announcement_trace is what
+  # is sent to the spy log. By default just calls 'to_s'.
+  def as_announcement_trace
+    self.to_s
+  end
+
+  # When a class is used as an announcment, an empty new instance is created using #allocate.
+  # Will raise an exception for those rare classes that cannot #allocate a new instance.
+  def self.as_announcement
+    new_inst = self.allocate rescue nil
+    raise "Cannot create an announcement out of #{self}. Please implement 'as_announcement' as a class method of #{self}." if new_inst.nil?
+    new_inst
+  end
+
+end
+
+
+

data/spec/cosell_spec.rb

@@ -0,0 +1,179 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+#
+# A few announcments
+#
+class AWordFromOurSponsor
+  attr_accessor :word
+end
+class KnockOut; end
+class TKO < KnockOut; end
+
+#
+# A class whose objects can act as announcers
+#
+class AnyOldClass; include Cosell; end
+
+#
+# The tests
+#
+describe Cosell do
+
+  before(:each) do
+    @announcer = AnyOldClass.new
+  end
+
+  it "should instantiate announcement instance from class if needed" do
+    @announcer.announce(AWordFromOurSponsor).class.should be_eql(AWordFromOurSponsor)
+    @announcer.announce(AWordFromOurSponsor.new).class.should be_eql(AWordFromOurSponsor)
+  end
+
+  it "should execute block specified by subscription" do
+    
+    #@announcer.spy!
+
+    # After subscribing to KnockOut, make sure it fires whenever
+    # KnockOut or it's subclass TKO are announced.
+    
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+
+    what_was_announced = nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql KnockOut
+   
+    what_was_announced = nil
+    @announcer.announce TKO
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql TKO
+
+    
+    # Do the same thing as above, but announce instances (test above used the class as the announcement)
+    # make sure if an announcement instance is announced, that the exact instance is what is announced
+   
+    what_was_announced = nil
+    announcement = AWordFromOurSponsor.new
+    announcement.word = 'the'
+    @announcer.announce announcement
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql AWordFromOurSponsor
+    what_was_announced.word.should be_eql('the')
+   
+    what_was_announced = nil
+    @announcer.announce TKO.new
+    what_was_announced.should_not be_nil
+    what_was_announced.class.should be_eql TKO
+
+  end
+
+  it "should take actions only on announcements of events for which there is a subscription" do
+    # Make sure the subscription block fires when an AWordFromOurSponsor is 
+    # announced, setting what_was_announced to the announcement)
+    what_was_announced = nil
+    @announcer.when_announcing(KnockOut) { |ann| what_was_announced = ann }
+
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should be_nil
+
+    @announcer.announce AWordFromOurSponsor.new # also test announcement instances
+    what_was_announced.should be_nil
+
+    @announcer.announce TKO # subclass of Knockout, should be announced
+    what_was_announced.should_not be_nil
+  end
+
+  it "should be able to subscribe to set of announcements types" do
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+
+    what_was_announced = nil
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should_not be_nil
+
+    what_was_announced = nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+  end
+
+  it "should not take actions after unsubscribing" do
+    what_was_announced = nil
+    @announcer.when_announcing(AWordFromOurSponsor, KnockOut) { |ann| what_was_announced = ann }
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should_not be_nil
+
+    @announcer.unsubscribe(AWordFromOurSponsor)
+    what_was_announced = nil
+    @announcer.announce AWordFromOurSponsor
+    what_was_announced.should be_nil
+    @announcer.announce KnockOut
+    what_was_announced.should_not be_nil
+  end
+
+  it "should be able to queue announcements" do
+    what_was_announced = nil
+    count = 0
+    sleep_time = 0.1
+    how_many_each_cycle = 77
+    @announcer.queue_announcements!(:sleep_time => sleep_time, 
+                                    :logger => Logger.new(STDOUT),
+                                    :announcements_per_cycle => how_many_each_cycle)
+    @announcer.when_announcing(AWordFromOurSponsor) { |ann| count += 1 }
+
+    little_bench("time to queue 10_000 announcements"){10_000.times {@announcer.announce AWordFromOurSponsor}}
+
+    # @announcer.spy! #dbg
+
+    # Allow announcer thread to do a few batches of announcements, checking the 
+    # count after each batch. Since we may get to this part of the thread after
+    # the announcer has already made a few announcements, use the count at
+    # this moment as the starting_count
+    start_count = count
+    #puts "-------start count: #{count}" # dbg
+
+    sleep sleep_time + 0.01
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 1*how_many_each_cycle)
+
+    sleep sleep_time
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 2*how_many_each_cycle)
+
+    sleep sleep_time
+    #puts "-------count: #{count}" # dbg
+    count.should be_eql(start_count + 3*how_many_each_cycle)
+
+    # See if killing the queue stops announcments that where queued
+    @announcer.kill_queue!
+    count_after_queue_stopped = count
+    #puts "-------count after stopping: #{count}" # dbg
+    sleep sleep_time * 2
+    count.should be_eql(count_after_queue_stopped)
+
+  end
+
+#  it "should suppress announcements during suppress_announcements block" do
+#    # TODO: support for this idiom:
+#    notifier.suppress_announcements_during {
+#    }
+#       and
+#    notifier.suppress_announcements(EventType,
+#                                    :during => lambda { "some operation" },
+#                                    :send_unique_events_when_done => true)
+#       and
+#    notifier.suppress_announcements(EventType,
+#                                    :during => lambda { "some operation" },
+#                                    :send_all_events_when_done => true)
+#  end
+
+  protected
+
+    def little_bench(msg, &block)
+      start = Time.now
+      result = block.call
+      puts "#{msg}: #{Time.now - start} sec"
+      return result
+    end
+end
+
+# EOF

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require File.join(File.dirname(__FILE__), '../lib/cosell')
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+# EOF

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: swerling-cosell
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Steven Swerling
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-18 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bones
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.4.0
+    version: 
+description: Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk 7.4 as a replacement for 'triggerEvent' style of event notification.  Instead of triggering events identified by symbols, the events are first class objects.  For rationale, please see the original blog posting by Vassili Bykov (refs below).  *Lineage*  This implementation is loosely based on Lukas Renggli's tweak of Colin Putney's Squeak implementation of Vassili Bykov's Announcements framework for VisualWorks Smalltalk.  (Specifically Announcements-lr.13.mcz was used as a reference.)  Liberties where taken during the port. In particular, the Announcer class in the Smalltalk version is implemented here as a ruby module which can be mixed into any object. Also, in this implementation any object (or class) can serve as an announcement, so no Announcement class is implemented.   The ability to queue announcements in the background is built into cosell.  <b>The Name 'Cosell'</b>  I chose the name 'Cosell' because   a. Howard Cosell is an iconic event announcer b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced scads of results about ruby meetups, conferences, and the like. So I went with something a bit cryptic but hopefully a little more searchable.   *See*  * {Original blog posting describing Announcments by Vassili Bykov}[http://www.cincomsmalltalk.com/userblogs/vbykov/blogView?entry=3310034894] * {More info on the Announcements Framework}[http://wiki.squeak.org/squeak/5734]
+email: sswerling@yahoo.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.rdoc
+- README.txt
+files: 
+- .gitignore
+- History.txt
+- README.rdoc
+- README.txt
+- Rakefile
+- cosell.gemspec
+- example/basic_example.rb
+- example/cat_whisperer.rb
+- lib/cosell.rb
+- lib/cosell/announcer.rb
+- lib/cosell/monkey.rb
+- spec/cosell_spec.rb
+- spec/spec_helper.rb
+has_rdoc: false
+homepage: http://github.com/swerling/TODO
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: cosell
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk 7
+test_files: []
+