swerling-cosell 0.0.1 → 0.0.2

data/.gitignore

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

data/README.rdoc

@@ -1,11 +1,14 @@
 cosell
-    by Steven Swerling
-    http://tab-a.slot-z.net
+ 
+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 7.4 as a
+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
@@ -40,7 +43,7 @@ b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced
 == FEATURE
 
 * Announcements-style event observer framework
-* Easy way to queue events in background
+* Synchronous announcements and asynchronous announcements (using a background thread with a queue)
 
 == PROBLEMS
 

data/Rakefile

@@ -24,18 +24,42 @@ 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"]
+PROJ.rdoc.opts = ["--inline-source", "-o rdoc", "--format=html", "-T hanna"]
 
-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
+
+
+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

@@ -2,13 +2,13 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cosell}
-  s.version = "0.0.1"
+  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-07-18}
+  s.date = %q{2009-08-09}
   s.description = %q{Cosell is a minimal implementation of the 'Announcements' observer
-framework, originally introduced in VisualWorks Smalltalk 7.4 as a
+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
@@ -40,25 +40,26 @@ b. Googling for 'Ruby Announcements', 'Ruby Event Announcements', etc., produced
 * {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.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", "--main", "README.txt"]
+  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.3}
-  s.summary = %q{Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk 7}
+  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.4.0"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
     else
-      s.add_dependency(%q<bones>, [">= 2.4.0"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
     end
   else
-    s.add_dependency(%q<bones>, [">= 2.4.0"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
   end
 end

data/lib/cosell.rb

@@ -1,7 +1,7 @@
 module Cosell 
 
   # :stopdoc:
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
 

data/lib/cosell/announcer.rb

@@ -15,12 +15,18 @@ module Cosell
 
     # Place all announcments in a queue, and make announcements in a background thread.
     #
-    # Options:
+    # Arguments:
+    #    :logger => a logger. Where to log exceptions and warnings.
+    #               This argument is mandatory -- it is too hard to debug exceptions in announcement 
+    #               handler code without a logger. If you _really_ want your code to fail silently, 
+    #               you will have to create a logger on /dev/null.
     #    :sleep_time => how long to sleep (in seconds) after making a batch of announchements 
-    #                   default: 0.01
+    #                   optional arg, 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.
+    #                   optional arg, default: 25
+    #
+    # WARNING: If you do not pass in a logger, announcement code will fail silently (the queue
+    # is in a background thread).
     #
     # Note: at the moment, this method may only be called once, and cannot be undone. There is
     # no way to interrupt the thread.
@@ -29,6 +35,13 @@ module Cosell
 
       self.initialize_cosell_if_needed
 
+      # The logger in mandatory
+      if opts[:logger]
+        self.queue_logger = opts[:logger]
+      else
+        raise "Cosell error: You have to provide a logger, otherwise failures in announcement handler code are to hard to debug"
+      end
+
       # kill off the last queue first
       if self.announcements_thread
         kill_queue!
@@ -41,18 +54,17 @@ module Cosell
 
       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
+        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
+            begin
               self.announce_now! self.announcements_queue.pop
               count += 1
               if (count%how_many_per_cycle).eql?(0)
@@ -60,10 +72,10 @@ module Cosell
                 count = 0
                 sleep cycle_duration
               end
+            rescue Exception => x
+              log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error
             end
           end
-        rescue Exception => x
-          log "Exception: #{x}, trace: \n\t#{x.backtrace.join("\n\t")}", :error
         end
       end
 
@@ -148,7 +160,7 @@ module Cosell
     #    :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: "
+    #    :preface_with => 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)
@@ -190,6 +202,9 @@ module Cosell
       return @__queue_announcements.eql?(true)
     end
 
+    def subscriptions= x; @__subscriptions = x; end
+    def subscriptions; @__subscriptions ||= []; end
+
     protected
       
       #:stopdoc: 
@@ -211,8 +226,6 @@ module Cosell
       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

data/lib/cosell/monkey.rb

@@ -15,7 +15,7 @@ class Object
   # 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
+    self.to_s rescue "(Warning: could not create announcement trace)"
   end
 
   # When a class is used as an announcment, an empty new instance is created using #allocate.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: swerling-cosell
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Steven Swerling
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-18 00:00:00 -07:00
+date: 2009-08-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,9 +20,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.4.0
+        version: 2.5.1
     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]
+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]
 email: sswerling@yahoo.com
 executables: []
 
@@ -31,12 +31,10 @@ 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
@@ -46,13 +44,17 @@ files:
 - lib/cosell/monkey.rb
 - spec/cosell_spec.rb
 - spec/spec_helper.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/swerling/TODO
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --inline-source
+- -o rdoc
+- --format=html
+- -T hanna
 - --main
-- README.txt
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -70,9 +72,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: cosell
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk 7
+summary: Cosell is a minimal implementation of the 'Announcements' observer framework, originally introduced in VisualWorks Smalltalk as a replacement for 'triggerEvent' style of event notification
 test_files: []
 

data/README.txt

@@ -1,187 +0,0 @@
-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.