sentinel 0.4.0 → 0.5.0

data/README.textile

@@ -2,6 +2,8 @@ h1. Sentinel
 
 Transparent (unobtrusive) Observers for your Rubies.
 
+Does Sentinel helps your daily work with Ruby? So, "please recommend me in Work With Rails":http://workingwithrails.com/recommendation/new/person/9370-lucas-h-ngaro and thanks for your kindness! :)
+
 h2. Why?
 
 Developed for an specific need we had at "Busk":http://www.busk.com, Sentinel is a very small library that provides a way to add what we call "Transparent Observers" to your Ruby code. This means that you do not need to modify the observed methods (following the most common implementation of Observers), just use a mixin and declare your observers.
@@ -49,16 +51,20 @@ class MyClass
 end
 </pre>
 
-And... that's it! Every time the subject (in this case, MyClass) method is called, the specified observer method will be called *before* it, then it will run normally. The parameters passed to the subject method are passed to the observer method via the *args array. The options hash contains the key :subject, which contains the actual subject object in case you want to use it, like below:
+And... that's it! Every time the subject (in this case, MyClass) method is called, the specified observer method will be called too. By default, the observer method is called *before* the subject method, but you can call it *after* the execution (will see it in the next example).
+
+The parameters passed to the subject method are passed to the observer method via the *args array. The options hash contains the key :subject, which contains the actual subject object and the key :result, which contains the return of the observed method in case you intercepted the call after its execution.
+
+Below is a more "advanced" use of the observers:
 
 <pre>
 class MyObserver
   include Sentinel
 
-  observe MyClass, :instance_method
+  observe MyClass, :instance_method, :intercept => :after
 
   def self.notify(options, *args)
-    puts "Called from #{options[:subject]} with arguments #{args.inspect}"
+    puts "Called from #{options[:subject]} with arguments #{args.inspect} and returned #{options[:result]}"
   end
 end
 </pre>

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

data/lib/sentinel.rb

@@ -10,14 +10,28 @@ module Sentinel
       sentinel = self
 
       options = {
-        :method_to_notify => :notify
+        :method_to_notify => :notify,
+        :intercept => :before
       }.merge(options)
 
+      if options[:intercept] == :before
+        calls = <<-CODE
+          sentinel.send("#{options[:method_to_notify]}", observer_opt, *args)
+          self.send("#{method_name}_without_observer", *args)
+        CODE
+      else
+        calls = <<-CODE
+          result = self.send("#{method_name}_without_observer", *args)
+          observer_opt[:result] = result
+          sentinel.send("#{options[:method_to_notify]}", observer_opt, *args)
+          result
+        CODE
+      end
+
       body = <<-CODE
         define_method "#{method_name}_with_observer" do |*args|
           observer_opt = {:subject => self}
-          sentinel.send("#{options[:method_to_notify]}", observer_opt, *args)
-          self.send("#{method_name}_without_observer", *args)
+          #{calls}
         end
 
         alias_method "#{method_name}_without_observer", method_name

data/spec/fixtures/sentinel_subject.rb

@@ -1,14 +1,10 @@
 class SentinelSubject
   def instance_method
-    "hi from instance method!"
-  end
-
-  def new_method
-    "hi from new method!"
+    42
   end
 
   def self.class_method
-    "hi from class method!"
+    42
   end
 
   def instance_method_with_params(*params)
@@ -18,12 +14,4 @@ class SentinelSubject
   def self.class_method_with_params(*params)
     "hi from class method with params!"
   end
-
-  def instance_returning_something
-    42
-  end
-
-  def self.class_returning_something
-    42
-  end
 end

data/spec/sentinel_spec.rb

@@ -2,74 +2,103 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 require File.expand_path(File.dirname(__FILE__) + '/fixtures/my_observer')
 require File.expand_path(File.dirname(__FILE__) + '/fixtures/sentinel_subject')
 
-describe Sentinel, "defining an observer for a method" do
-  before(:all) do
+describe Sentinel do
+  before(:each) do
     MyObserver.send(:include, Sentinel)
   end
+  
+  after(:each) do
+    # reload the file to undefine the observer methods (would cause 'stack level too deep' errors otherwise)
+    load File.expand_path(File.dirname(__FILE__) + '/fixtures/sentinel_subject.rb')    
+  end
 
-  context "with the minimum required options" do
-    it "should notify the specified Observer when calling a class method" do
+  context "basic premises" do
+    it "should not modify the subject method output when called before it" do
+      MyObserver.send(:observe, SentinelSubject, :class_method, :class_method => true)
       MyObserver.send(:observe, SentinelSubject, :instance_method)
-      MyObserver.expects(:notify)
-
-      SentinelSubject.new.instance_method
-    end
 
-    it "should notify the specified Observer when calling an instance method" do
-      MyObserver.send(:observe, SentinelSubject, :class_method, :class_method => true)
-      MyObserver.expects(:notify)
+      MyObserver.expects(:notify).twice
 
-      SentinelSubject.class_method
+      SentinelSubject.class_method.should == 42
+      SentinelSubject.new.instance_method.should == 42
     end
-
-    it "should not modify the observed methods output" do
-      MyObserver.send(:observe, SentinelSubject, :class_returning_something, :class_method => true)
-      MyObserver.send(:observe, SentinelSubject, :instance_returning_something)
+    
+    it "should not modify the subject method output when called after it" do
+      MyObserver.send(:observe, SentinelSubject, :class_method, :class_method => true, :intercept => :after)
+      MyObserver.send(:observe, SentinelSubject, :instance_method, :intercept => :after)
 
       MyObserver.expects(:notify).twice
 
-      SentinelSubject.class_returning_something.should == 42
-      SentinelSubject.new.instance_returning_something.should == 42
+      SentinelSubject.class_method.should == 42
+      SentinelSubject.new.instance_method.should == 42
     end
+    
+    it "should pass all parameters of the observed methods to the observer" do
+      MyObserver.send(:observe, SentinelSubject, :class_method_with_params, :class_method => true)
+      MyObserver.send(:observe, SentinelSubject, :instance_method_with_params)
 
-    context "observing methods with parameters" do
-      it "should pass all parameters of the observed methods to the Observer" do
-        MyObserver.send(:observe, SentinelSubject, :class_method_with_params, :class_method => true)
-        MyObserver.send(:observe, SentinelSubject, :instance_method_with_params)
+      subject = SentinelSubject.new
 
-        subject = SentinelSubject.new
+      MyObserver.expects(:notify).once.with({:subject => SentinelSubject}, "texto", 1)
+      MyObserver.expects(:notify).once.with({:subject => subject}, "texto", 1)
 
-        MyObserver.expects(:notify).once.with({:subject => SentinelSubject}, "texto", 1)
-        MyObserver.expects(:notify).once.with({:subject => subject}, "texto", 1)
-
-        SentinelSubject.class_method_with_params("texto", 1)
-        subject.instance_method_with_params("texto", 1)
-      end
+      SentinelSubject.class_method_with_params("texto", 1)
+      subject.instance_method_with_params("texto", 1)
     end
+  end
 
-    context "observing methods using a different Observer method" do
-      it "should call the specified method in the observe call" do
-        MyObserver.send(:observe, SentinelSubject, :new_method, :method_to_notify => :another_method)
-        MyObserver.expects(:another_method)
+  context "with the default options" do
+    it "should notify the specified observer when calling an instance method" do
+      MyObserver.send(:observe, SentinelSubject, :instance_method)
+      MyObserver.expects(:notify)
 
-        SentinelSubject.new.new_method
-      end
+      SentinelSubject.new.instance_method
     end
-  end
 
-  context "without the minimum required options" do
-    it "should raise ArgumentError when the observer of an instance method is not defined" do
-      MyObserver.expects(:notify).never
-      SentinelSubject.expects(:observe).raises(ArgumentError)
+    it "should notify the specified observer when calling a class method" do
+      MyObserver.send(:observe, SentinelSubject, :class_method, :class_method => true)
+      MyObserver.expects(:notify)
 
-      SentinelSubject.send(:observe, :instance_method) rescue nil
+      SentinelSubject.class_method
     end
+    
+    it "should be called before the method execution" do
+      MyObserver.send(:observe, SentinelSubject, :instance_method)
+      subject = SentinelSubject.new
+      
+      MyObserver.expects(:notify).once.with({:subject => subject})
 
-    it "should raise ArgumentError when the observer of a class method is not defined" do
-      MyObserver.expects(:notify).never
-      SentinelSubject.expects(:observe).raises(ArgumentError)
+      subject.instance_method
+    end
+  end
+  
+  context "with user-specified options" do
+    context "when observing methods using a different observer method" do
+      it "should call the specified observer method when the subject method is called" do
+        MyObserver.send(:observe, SentinelSubject, :instance_method, :method_to_notify => :another_method)
+        MyObserver.send(:observe, SentinelSubject, :class_method, :method_to_notify => :another_method, :class_method => true)
+        
+        MyObserver.expects(:another_method).twice
+
+        SentinelSubject.new.instance_method
+        SentinelSubject.class_method
+      end 
+    end
+    
+    context "when intercepting the call after the method execution" do
+      it "should pass the result of the execution to the observer" do
+        MyObserver.send(:observe, SentinelSubject, :instance_method, :intercept => :after)
+        MyObserver.send(:observe, SentinelSubject, :class_method, :intercept => :after, :class_method => true)
+        
+        subject = SentinelSubject.new
+        
+        MyObserver.expects(:notify).once.with({:subject => subject, :result => 42})
+        MyObserver.expects(:notify).once.with({:subject => SentinelSubject, :result => 42})
 
-      SentinelSubject.send(:observe, :class_method, :class_method => true) rescue nil
+        subject.instance_method
+        SentinelSubject.class_method
+      end
     end
   end
+
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 4
+  - 5
   - 0
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors: 
 - "Lucas H\xC3\xBAngaro"
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-19 00:00:00 -03:00
+date: 2010-04-26 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency