= announcements

http://www.bofh.org.uk/articles/tag/announcementsproject

== DESCRIPTION:

A port of Vassily Bykov's Smalltalk Announcements framework. Think of it as
Observer/Observable on steroids.

== FEATURES/PROBLEMS:

=== Problems first

This is very much a first cut. Testing is sparse because this is mostly a direct port
from a Smalltalk package that's pretty much test free. The API also a pretty
much straight port of the Smalltalk and isn't what could be called idiomatic
Ruby just yet.

=== Features

* Announcements are objects and can carry all the information a subscriber will need.
* Small, uniform interface for subscription

== SYNOPSIS:

  class ObservableValue
    include Announcements
    class ChangeAnnouncement < Announcements::Anouncement
      attr_accessor :from, :to

      def initialize(from, to)
        @from, @to = from, to
      end

      def inspect
        self.class.to_s.gsub(/([a-z])(A-Z)/) { $1 + ' ' + $2}.downcase << 
          " from #{@from.inspect} to #{@to.inspect}"
      end
    end

    class ValueWillChange <  ChangeAnnouncement
      def veto!
        @vetoed = true
      end

      def vetoed?
        @vetoed
      end
    end

    class ValueChanging < ChangeAnnouncement; end
    class ValueChanged < ChangeAnnouncement; end

    def self.announcer
      @@announcer ||= Announcements::Announcer.new
    end

    def announce(*args)
      self.class.announcer.announce(*args)
    end

    def value=(new_value) 
      unless announce(ValueWillChange.new(@value, new_value)).vetoed?
        announce(ValueChanging.new(@value, new_value)
        change_complete = ValueChanged.new(@value, new_value)
        @value = new_value
        announce(change_complete)
    end
  end

  # Spy on all the changes

  ObservableValue.watch(ObservableValue::ChangeAnnouncement) do |notice, sender|
    puts "#{announcer.inspect} #{announcement.inspect}"
  end

  # Remember changes for undoing

  ObservableValue.watch(ObservableValue::ValueChanged) do |notice, sender|
    command_history << UndoableCommand.new(sender, notice.from, notice.to)
  end

== REQUIREMENTS:

* Rspec, but only if you want to run the tests
* Er...
* That's it

== INSTALL:

  sudo gem install announcements

== COPYRIGHT:

Copyright (c) 2008 Piers Cawley

This library is free software; you can redistribute it and/or modify it under
the same terms as Ruby itself.

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.