giraffesoft-observational 0.1.1 → 0.2.3

data/.gitignore

@@ -3,3 +3,5 @@
 coverage
 rdoc
 pkg
+doc
+.yardoc

data/README.rdoc

@@ -11,14 +11,14 @@ How many times have you seen this in a rails app?
     end
   end
 
-Why is the user concerned with the delivery of his own welcome message? It seems like that responsibility would be better suited to the Notifier.
+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, :on => :create
+    observes :user, :invokes => :deliver_welcome_message, :after => :create
 
     def welcome_message(user)
       # do mailer stuff here
@@ -30,7 +30,7 @@ After a user is created, Notifier.deliver_welcome_message(that_user) will be inv
 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, :on => :create
+    observes :message, :invokes => :use_credit, :with => :creator, :after => :create
 
     def use_credit(user)
       # do something
@@ -38,6 +38,16 @@ It's also possible to specify that the observer method gets called with a specif
   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
 

data/Rakefile

@@ -31,18 +31,8 @@ end
 
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "observational #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
 end
 

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.3

data/lib/observational.rb

@@ -1,13 +1,30 @@
+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
-
-    model_klass    = model_name.to_s.classify.constantize
-    observer_klass = self
-    model_klass.send(:"after_#{opts[:on]}") do |object|
-      argument = opts.has_key?(:with) ? object.send(opts[:with]) : object
-      observer_klass.send(opts[:invokes], argument)
-    end
+    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
 

data/lib/observational/active_record_observers.rb

@@ -0,0 +1,25 @@
+module Observational
+  module ActiveRecordObservers
+    def self.included(klass)
+      ActiveRecord::Callbacks::CALLBACKS.each do |callback|
+        klass.send(callback) { |obj| obj.send :notify_observers, callback }
+      end
+      klass.class_eval do
+        extend ClassMethods
+        class << self
+          alias_method_chain :define_callbacks, :observational
+        end
+      end
+    end
+
+    module ClassMethods
+      def define_callbacks_with_observational(*callbacks)
+        define_callbacks_without_observational *callbacks
+        callbacks.each do |c|
+          send(c) { |obj| obj.send :notify_observers, c }
+        end
+      end
+    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)
+    end
+
+    protected
+      def arguments(observable)
+        parameters.nil? ? observable : parameters.map { |p| observable.send(p) }
+      end
+  end
+end
+

data/observational.gemspec

@@ -2,26 +2,32 @@
 
 Gem::Specification.new do |s|
   s.name = %q{observational}
-  s.version = "0.1.1"
+  s.version = "0.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["James Golick"]
-  s.date = %q{2009-07-16}
+  s.date = %q{2009-08-05}
   s.email = %q{james@giraffesoft.ca}
   s.extra_rdoc_files = [
     "LICENSE",
      "README.rdoc"
   ]
   s.files = [
-    ".document",
-     ".gitignore",
+    ".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
@@ -31,7 +37,10 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.1}
   s.summary = %q{TODO}
   s.test_files = [
-    "spec/observational_spec.rb",
+    "spec/active_record_observers_spec.rb",
+     "spec/observable_spec.rb",
+     "spec/observational_spec.rb",
+     "spec/observer_spec.rb",
      "spec/spec_helper.rb"
   ]
 

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
+        @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

@@ -1,27 +1,64 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
+class Observed; end
+
 describe "Observational" do
-  before do
-    @user = User.new
-  end
+  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
 
-  describe "creating an observer on create" do
-    it "should invoke that method on create of the observed object" do
-      Notifier.expects(:deliver_new_user).with(@user)
-      @user.save
+    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 "an observer that returns specific data from the observed object" do
-    it "should pass that specific data to the observer method" do
-      @user.save
-      @message = Message.new :creator => @user
-      Creditor.expects(:use_credits).with(@user)
-      @message.save
+  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
 
-  it "should raise ArgumentError if passed any unfamiliar keys" do
-    lambda { Class.new.observes :user, :asdf => "whatever" }.should raise_error(ArgumentError)
+  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

@@ -35,7 +35,7 @@ class Message < ActiveRecord::Base
 end
 
 class Notifier
-  observes :user, :invokes => :deliver_new_user, :on => :create
+  observes :user, :invokes => :deliver_new_user, :on => :after_create
 
   def self.deliver_new_user(user)
   end
@@ -48,3 +48,6 @@ class Creditor
   end
 end
 
+require 'observational/active_record'
+ActiveRecord::Base.send(:include, Observational::ActiveRecordObservers)
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: giraffesoft-observational
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.3
 platform: ruby
 authors: 
 - James Golick
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-16 00:00:00 -07:00
+date: 2009-08-05 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -23,18 +23,25 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
-- .document
 - .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
@@ -55,10 +62,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 2
 summary: TODO
 test_files: 
+- spec/active_record_observers_spec.rb
+- spec/observable_spec.rb
 - spec/observational_spec.rb
+- spec/observer_spec.rb
 - spec/spec_helper.rb

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE