observational 0.2.5

data/.gitignore

@@ -0,0 +1,7 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+doc
+.yardoc

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 James Golick
+
+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.rdoc

@@ -0,0 +1,54 @@
+= Observational
+
+How many times have you seen this in a rails app?
+
+  class User
+    after_create :deliver_welcome_message
+
+    protected
+    def deliver_welcome_message
+      Notifier.deliver_welcome_message(self)
+    end
+  end
+
+Why is the user concerned with the delivery of his own welcome message? It seems like the Notifier should be responsible for that.
+
+Observational makes it possible to make it the Notifier's responsibility, using the observer pattern.
+
+The equivalent of the above example is:
+
+  class Notifier < ActionMailer::Base
+    observes :user, :invokes => :deliver_welcome_message, :after => :create
+
+    def welcome_message(user)
+      # do mailer stuff here
+    end
+  end
+
+After a user is created, Notifier.deliver_welcome_message(that_user) will be invoked.
+
+It's also possible to specify that the observer method gets called with a specific attribute from the observed object.
+
+  class Creditor
+    observes :message, :invokes => :use_credit, :with => :creator, :after => :create
+
+    def use_credit(user)
+      # do something
+    end
+  end
+
+After a message is created, Creditor.use_credit(message.creator) will be called.
+
+Observational supports all of ActiveRecord's callbacks.
+
+== YARDOC
+
+Observational uses YARD, because it's a million times better than RDoc. You can find the docs at {docs.github.com/giraffesoft/observational}[http://docs.github.com/giraffesoft/observational]
+
+== General Purpose Observers
+
+Observational can also be used to add observers to ruby classes that aren't related to active_record. But, that's not documented yet :-).
+  
+== Copyright
+
+Copyright (c) 2009 James Golick. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "observational"
+    gem.summary = %Q{TODO}
+    gem.email = "james@giraffesoft.ca"
+    gem.homepage = "http://github.com/giraffesoft/observational"
+    gem.authors = ["James Golick"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.5

data/lib/observational.rb

@@ -0,0 +1,32 @@
+require 'observational/observer'
+require 'observational/observable'
+
+module Observational
+  ##
+  # Declares an observer
+  #
+  # @param [Symbol] the name of the model to observe
+  # @param [Hash] opts observer options
+  # @option opts [Symbol] :invokes The method to invoke on the subscriber.
+  # @option opts [Symbol] :with The parameters to pass to the method that gets invoked.
+  # @option opts [Symbol] :on The action to observe. e.g. :after_create for an active_record object
+  # @option opts [Symbol] :after A shortcut for AR objects. :after => :create is the equivalent of :on => :after_create
+  # @option opts [Symbol] :before Same as :after
+  #
+  def observes(model_name, opts = {})
+    opts.assert_valid_keys :with, :invokes, :on, :before, :after
+
+    opts[:on]   = :"before_#{opts[:before]}" unless opts[:before].nil?
+    opts[:on]   = :"after_#{opts[:after]}" unless opts[:after].nil?
+    model_klass = model_name.to_s.classify.constantize
+    model_klass.send(:include, Observable) unless model_klass.include?(Observable)
+    observer    = Observational::Observer.new :method     => opts[:invokes],
+                                              :parameters => opts[:with].nil? ? nil : [*opts[:with]],
+                                              :subscriber => self,
+                                              :actions    => opts[:on]
+    model_klass.add_observer(observer)
+  end
+end
+
+Class.send(:include, Observational) unless Class.include?(Observational)
+

data/lib/observational/active_record_observers.rb

@@ -0,0 +1,8 @@
+module Observational
+  module ActiveRecordObservers
+    def run_callbacks(kind, options = {}, &block)
+      self.send(:notify_observers, kind)
+      super
+    end
+  end
+end

data/lib/observational/observable.rb

@@ -0,0 +1,35 @@
+module Observational
+  module Observable
+    def self.included(klass)
+      klass.send(:extend, ClassMethods)
+    end
+
+    module ClassMethods
+      def observers
+        @observers ||= []
+      end
+
+      def add_observer(observer)
+        observers << observer
+      end
+
+      def observed_by?(observer)
+        observers.include?(observer)
+      end
+
+      def observers_for(action)
+        observers.select { |o| o.observes_action?(action) }
+      end
+
+      def delete_observers
+        @observers = []
+      end
+    end
+
+    protected
+      def notify_observers(action)
+        self.class.observers_for(action).each { |o| o.invoke(self) }
+      end
+  end
+end
+

data/lib/observational/observer.rb

@@ -0,0 +1,26 @@
+module Observational
+  class Observer
+    attr_reader :subscriber, :method, :parameters, :actions
+
+    def initialize(options)
+      @subscriber = options[:subscriber]
+      @method     = options[:method]
+      @parameters = options[:parameters]
+      @actions    = [*options[:actions]]
+    end
+
+    def invoke(observable)
+      @subscriber.send(method, *arguments(observable))
+    end
+
+    def observes_action?(action)
+      actions.include?(action.to_sym)
+    end
+
+    protected
+      def arguments(observable)
+        parameters.nil? ? observable : parameters.map { |p| observable.send(p) }
+      end
+  end
+end
+

data/observational.gemspec

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{observational}
+  s.version = "0.2.5"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["James Golick"]
+  s.date = %q{2009-08-05}
+  s.email = %q{james@giraffesoft.ca}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/observational.rb",
+     "lib/observational/active_record_observers.rb",
+     "lib/observational/observable.rb",
+     "lib/observational/observer.rb",
+     "observational.gemspec",
+     "rails/init.rb",
+     "spec/active_record_observers_spec.rb",
+     "spec/observable_spec.rb",
+     "spec/observational_spec.rb",
+     "spec/observer_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/giraffesoft/observational}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = "Use the observer pattern to better divide your objects' responsibilities."
+  s.test_files = [
+    "spec/active_record_observers_spec.rb",
+     "spec/observable_spec.rb",
+     "spec/observational_spec.rb",
+     "spec/observer_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+ActiveRecord::Base.send(:include, Observational::ActiveRecordObservers)
+ActiveRecord::Base.send(:include, Observational::Observable)

data/spec/active_record_observers_spec.rb

@@ -0,0 +1,31 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Observational::ActiveRecord" do
+  include Observational
+
+  before do
+    @user = User.new
+  end
+
+  ActiveRecord::Callbacks::CALLBACKS.each do |callback|
+    describe "observing #{callback}" do
+      it "should fire the observer during that callback" do
+        self.expects(:subscription).with(@user)
+        observes :user, :invokes => :subscription, :on => callback.to_sym
+        @user.send :callback, callback
+      end
+    end
+  end
+
+  describe "adding custom callbacks" do
+    before do
+      User.send :define_callbacks, :after_something_else
+      self.expects(:subscription).with(@user)
+      observes :user, :invokes => :subscription, :after => :something_else
+    end
+
+    it "should make it possible to observe those using observational" do
+      @user.send :callback, :after_something_else
+    end
+  end
+end

data/spec/observable_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Observable" do
+  before do
+    @klass = Class.new do
+      include Observational::Observable
+
+      def save
+        fire_observers :after_create
+      end
+    end
+    @observer = Observational::Observer.new :method     => :do_stuff,
+                                            :subscriber => stub(:do_stuff => ""),
+                                            :actions    => :some_action
+  end
+
+  it "should accept new observers" do
+    @klass.add_observer @observer
+    @klass.should be_observed_by(@observer)
+  end
+
+  it { @klass.should_not be_observed_by(:non_observer) }
+
+  describe "notifying observers" do
+    before do
+      @observable = @klass.new
+      @klass.add_observer @observer
+      @different_action = Observational::Observer.new :method     => :do_stuff,
+                                                      :subscriber => stub(:do_stuff => ""),
+                                                      :actions    => :something_else
+      @klass.add_observer @different_action
+    end
+
+    it "should notify the observers who are interested" do
+      @observer.expects(:invoke).with(@observable)
+      @different_action.expects(:invoke).never
+      @observable.send :notify_observers, :some_action
+    end
+  end
+
+  describe "removing the observers" do
+    before do
+      @klass.observers << @different_action
+      @klass.delete_observers
+    end
+
+    it "should clear out all the observers" do
+      @klass.observers.should be_empty
+    end
+  end
+end

data/spec/observational_spec.rb

@@ -0,0 +1,64 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class Observed; end
+
+describe "Observational" do
+  after { Observed.delete_observers }
+
+  describe "declaring an observer" do
+    before do
+      @observing_klass = Class.new do
+        observes :observed, :on      => :some_action,
+                            :invokes => :do_stuff
+      end
+
+      @observer = Observed.observers.first
+    end
+
+    it "should set the observing class as the subscriber" do
+      @observer.subscriber.should == @observing_klass
+    end
+
+    it "should set the action to the value of the :on parameter" do
+      @observer.actions.should == [:some_action]
+    end
+
+    it "should set the method to the value of the :invokes parameter" do
+      @observer.method.should == :do_stuff
+    end
+
+    it "should raise ArgumentError if passed any unfamiliar keys" do
+      lambda { Class.new.observes :user, :asdf => "whatever" }.should raise_error(ArgumentError)
+    end
+  end
+
+  describe "using the activerecord shortcut :before => :whatever" do
+    before do
+      @observing_klass = Class.new do
+        observes :observed, :before  => :create,
+                            :invokes => :do_stuff
+      end
+
+      @observer = Observed.observers.first
+    end
+
+    it "should create an observer with :action => :before_create" do
+      @observer.actions.should == [:before_create]
+    end
+  end
+
+  describe "using the activerecord shortcut :after => :whatever" do
+    before do
+      @observing_klass = Class.new do
+        observes :observed, :after   => :create,
+                            :invokes => :do_stuff
+      end
+
+      @observer = Observed.observers.first
+    end
+
+    it "should create an observer with :action => :after_create" do
+      @observer.actions.should == [:after_create]
+    end
+  end
+end

data/spec/observer_spec.rb

@@ -0,0 +1,46 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Observer" do
+  before do
+    @klass    = Class.new
+  end
+
+  describe "without paraemeters specified" do
+    before do
+      @observer = Observational::Observer.new :subscriber => @klass, 
+                                              :method     => :do_stuff
+    end
+
+    it "should invoke the :method with the object" do
+      @klass.expects(:do_stuff).with(:the_object)
+      @observer.invoke(:the_object)
+    end
+  end
+
+  describe "with particular parameters" do
+    before do
+      @observer = Observational::Observer.new :subscriber => @klass,
+                                              :method     => :do_stuff,
+                                              :parameters => [:foo, :bar]
+    end
+    
+    it "should invoke the method with the parameters as specified" do
+      @klass.expects(:do_stuff).with("bar", "foo")
+      @observer.invoke(stub(:foo => "bar", :bar => "foo"))
+    end
+  end
+
+  describe "observing :after_create" do
+    before do
+      @observer = Observational::Observer.new :subscriber => @klass,
+                                              :method     => :do_stuff,
+                                              :parameters => [:foo, :bar],
+                                              :actions    => :after_create
+    end
+    subject { @observer }
+
+    it { should be_observes_action(:after_create) }
+    it { should_not be_observes_action(:other_stuff) }
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'observational'
+require 'activerecord'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end
+
+ActiveRecord::Base.configurations = {'sqlite3' => {:adapter => 'sqlite3', :database => ':memory:'}}
+ActiveRecord::Base.establish_connection('sqlite3')
+
+ActiveRecord::Base.logger = Logger.new(STDERR)
+ActiveRecord::Base.logger.level = Logger::WARN
+
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :users do |t|
+    t.string  :email,    :default => ''
+  end
+
+  create_table :messages do |t|
+    t.integer :creator_id
+    t.string  :email,    :default => ''
+  end
+end
+
+class User < ActiveRecord::Base
+end
+
+class Message < ActiveRecord::Base
+  belongs_to :creator, :class_name => "User"
+end
+
+class Notifier
+  observes :user, :invokes => :deliver_new_user, :on => :after_create
+
+  def self.deliver_new_user(user)
+  end
+end
+
+class Creditor
+  observes :message, :invokes => :use_credits, :with => :creator, :on => :create
+
+  def self.use_credits(user)
+  end
+end
+
+require 'observational/active_record_observers'
+User.send(:include, Observational::ActiveRecordObservers)
+

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: observational
+version: !ruby/object:Gem::Version 
+  version: 0.2.5
+platform: ruby
+authors: 
+- James Golick
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-05 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: james@giraffesoft.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/observational.rb
+- lib/observational/active_record_observers.rb
+- lib/observational/observable.rb
+- lib/observational/observer.rb
+- observational.gemspec
+- rails/init.rb
+- spec/active_record_observers_spec.rb
+- spec/observable_spec.rb
+- spec/observational_spec.rb
+- spec/observer_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/giraffesoft/observational
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: 
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 2
+summary: Use the observer pattern to better divide your objects' responsibilities.
+test_files: 
+- spec/active_record_observers_spec.rb
+- spec/observable_spec.rb
+- spec/observational_spec.rb
+- spec/observer_spec.rb
+- spec/spec_helper.rb