cosell 0.0.2

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/
+doc/
+rdoc/
+*.swp

data/History.txt

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

data/README.rdoc

@@ -0,0 +1,190 @@
+cosell
+ 
+by {Steven Swerling}[http://tab-a.slot-z.net]
+
+{rdoc}[http://tab-a.slot-z.net] | {github}[http://www.github.com/swerling/cosell]
+
+
+== DESCRIPTION:
+
+Cosell is a minimal implementation of the 'Announcements' observer
+framework, originally introduced in VisualWorks Smalltalk 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
+* Synchronous announcements and asynchronous announcements (using a background thread with a queue)
+
+== 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,65 @@
+# 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.readme_file = 'README.rdoc'
+
+PROJ.spec.opts << '--color'
+
+PROJ.rdoc.opts = ["--inline-source", "-o rdoc", "--format=html", "-T hanna"]
+
+
+
+require 'fileutils'
+def this_dir; File.join(File.dirname(__FILE__)); end
+def doc_dir; File.join(this_dir, 'rdoc'); end
+def tab_a_doc_dir; File.join(this_dir, '../tab-a/public/cosell/rdoc'); end
+task :myclobber => [:clobber] do
+  mydir = File.join(File.dirname(__FILE__))
+  sh "rm -rf #{File.join(mydir, 'pkg')}"
+  sh "rm -rf #{File.join(mydir, 'doc')}"
+  sh "rm -rf #{File.join(mydir, 'rdoc')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.log')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.o')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.so')}"
+  sh "rm -rf #{File.join(mydir, 'ext/Makefile')}"
+  sh "rm -rf #{File.join(mydir, 'ext/Makefile')}"
+end
+task :mypackage => [:myclobber] do
+  Rake::Task['gem:package'].invoke
+end
+task :mydoc => [:myclobber] do
+  FileUtils.rm_f doc_dir()
+  sh "cd #{this_dir()} && rdoc -o rdoc --inline-source --format=html -T hanna README.rdoc lib/**/*.rb" 
+end
+task :taba => [:mydoc] do
+  this_dir = File.join(File.dirname(__FILE__))
+  FileUtils.rm_rf tab_a_doc_dir
+  FileUtils.cp_r doc_dir, tab_a_doc_dir
+end
+
+task :mygemspec => [:myclobber] do
+  Rake::Task['gem:spec'].invoke
+end

data/cosell.gemspec

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{cosell}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Steven Swerling"]
+  s.date = %q{2009-08-09}
+  s.description = %q{Cosell is a minimal implementation of the 'Announcements' observer
+framework, originally introduced in VisualWorks Smalltalk 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"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "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.has_rdoc = true
+  s.homepage = %q{http://github.com/swerling/TODO}
+  s.rdoc_options = ["--inline-source", "-o rdoc", "--format=html", "-T hanna", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{cosell}
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk as a replacement for 'triggerEvent' style of event notification}
+
+  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.5.1"])
+    else
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
+    end
+  else
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
+  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)
+ # =>