method_proxy 0.2.1

data/README.markdown

@@ -0,0 +1,178 @@
+### WHAT'S THIS? 
+
+'method_proxy' gem allows to 'tap' into instance method or class method calls 
+on objects of specific class or on specific classes. 
+
+
+### API 
+
+* `MethodProxy.proxy_instance_method(SomeClass, :some_instance_method, &block)`
+
+Replaces original instance method SomeClass#some_instance_method with method 
+generated from supplied block. Supplied block should expect following 
+arguments:
+  1) object on which the call is made;
+  2) original method bound to the object on which call is made;
+  *args - arguments of original method call;
+  &block - block passed to the original method call. 
+
+An important thing to remember, is the &block should not use 'return <result>' 
+and should use 'next <result>' construct instead - as 'return' will result in 
+exception:
+
+LocalJumpError: unexpected return
+
+
+* `MethodProxy.unproxy_instance_method(SomeClass, :some_instance_method)`
+
+Restore original instance method SomeClass#some_instance_method.
+
+
+* `MethodProxy.proxy_class_method(SomeClass, :some_class_method, &block)`
+
+Replaces original class method with method generated from supplied block. 
+Supplied block should expect following arguments:
+  1) class on which the call is made;
+  2) original method bound to that class;
+  *args - arguments of original method call;
+  &block - block passed to the original method call.
+  
+Just like in case of proxy_instance_method, &block should use 'next <result>' 
+construct instead of 'return <result>' or LocalJumpError will be raised.
+
+
+* `MethodProxy.unproxy_class_method(SomeClass, :some_class_method)`
+Restore original class method SomeClass.some_class_method.
+
+
+* `MethodProxy.classes_with_proxied_instance_methods`
+
+Returns Array of classes that have at least one instance method tapped into by 
+MethodProxy.
+
+
+* `MethodProxy.proxied_instance_methods_for(klass)`
+
+Returns Array of instance method names for class klass that have been altered by 
+MethodProxy.
+
+
+* `MethodProxy.classes_with_proxied_class_methods`
+
+Returns Array of classes that have at least one class method tapped into by 
+MethodProxy.
+
+
+* `MethodProxy.proxied_class_methods_for(klass)`
+
+Returns Array of class method names for class klass that have been altered by 
+MethodProxy.
+
+
+### EXAMPLES
+
+**Example 1.** Non-intrusive debugging. Here's a way to dynamically "inject" call 
+to debugger before an instance method of interest UsersController#create, with 
+the help of MethodProxy:
+
+	require 'method_proxy'
+	require 'ruby-debug'
+	MethodProxy.proxy_instance_method(UsersController, :create) do |users_controller_obj, orig_create_meth, *args|
+	  debugger
+	  res = orig_create_meth.call *args
+	  next res
+	end
+
+
+**Example 1b.** Debug on exception:
+
+    require 'method_proxy'
+    require 'ruby-debug'
+    MethodProxy.proxy_instance_method(UsersController, :create) do |users_controller_obj, orig_create_meth, *args|
+      begin
+        res = orig_create_meth.call *args
+      rescue Exception => e
+        debugger
+      end
+      next res
+    end
+
+
+**Example 2.** Automatic recording of system actions during QA process. With the help of MethodProxy one can
+arrange interception of actions of interest (say, those that change database state), and storing of the
+actions' parameters:
+
+	tbd = {
+	  UsersController => [:create, :update, :delete],
+	  PostsController => [:create, :update, :delete]
+	}
+
+	tbd.each_pair do |cntrlr, actns|
+	  actns.each do |actn|
+	    MethodProxy.proxy_instance_method(cntrlr, actn) do |controller, meth, *args| 
+	      record_hash = Hash.new
+	      record_hash[:controller] = controller.class.name.to_sym
+	      record_hash[:action] = actn
+	      record_hash[:http_meth] = controller.request.method
+	      record_hash[:params] = controller.request.params
+      
+	      store_action_record(record_hash)    # store the information - implement according to your needs!
+      
+	      meth.call *args
+	    end
+	  end
+	end
+
+
+Later, the resulting "records" can be "replayed" in automated tests.
+
+
+### CAVEATS
+
+There is a number of known issues:
+
+- have to remember to use "next <result>" instead of "return <result>" syntax;
+- if one needs to tap into methods that are dynamically created, e.g. 
+'find_user_by_id' created on-the-fly with the help of 'method_missing' in 
+Rails, the code should make sure that method has been defined before attempting 
+to tap.
+
+
+### RELATION TO AOP 
+
+"Tapping" into method calls the way 'method_proxy' does is similar to creating 
+joint points in Aspect-Oriented Programming, and the same task can be 
+accomplished with AOP frameworks like Aquarium. 'method_proxy' however is 
+intended as a simple tool focused on its task - with no attempt to align it 
+with AOP concepts and terminology.
+
+
+### LICENSE 
+
+Usage, distribution or modification, for both commercial or non-profit purposes, 
+are not limited whatsoever.
+
+
+### DISCLAIMER 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+### CREDITS
+Special thanks for their invaluable feedback, advice, suggestions and fixes to:
+wtaysom, adehvadeh, shaokun and rainchen.
+
+
+### PROJECT ON THE WEB 
+
+The project is hosted on GitHub:
+https://github.com/kudelabs/method_proxy/

data/lib/method_proxy.rb

@@ -0,0 +1,218 @@
+require 'thread' if RUBY_VERSION <"1.9"
+
+class MethodProxyException < Exception
+
+end
+
+class MethodProxy
+  ##################################### CLASS VARIABLES #############################################
+  
+  @@mx = Mutex.new
+  @@proxied_instance_methods = {}
+  @@proxied_class_methods = {}
+  @@tmp_binding = nil
+  
+  #################################### SOME HELPER METHODS ##########################################
+  def self.classes_with_proxied_instance_methods
+    @@mx.synchronize do
+      return @@proxied_instance_methods.keys.collect{|k| Class.const_get(k)}
+    end
+  end
+  
+  def self.proxied_instance_methods_for(klass)
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    @@mx.synchronize do
+      meth_hash_for_klass = @@proxied_instance_methods[klass.name.to_sym]
+      return [] if !meth_hash_for_klass || meth_hash_for_klass.empty?
+      return meth_hash_for_klass.keys
+    end
+  end
+  
+  
+  def self.classes_with_proxied_class_methods
+    @@mx.synchronize do
+      return @@proxied_class_methods.keys.collect{|k| Class.const_get(k)}
+    end
+  end
+  
+  def self.proxied_class_methods_for(klass)
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    @@mx.synchronize do
+      meth_hash_for_klass = @@proxied_class_methods[klass.name.to_sym]
+      return [] if !meth_hash_for_klass || meth_hash_for_klass.empty?
+      return meth_hash_for_klass.keys
+    end
+  end
+  
+  
+  #### WARNING: NON-THREAD-SAFE methods for internal use; generally, they should not be called by ####
+  ####                                 any external code                                          ####
+  def self.register_original_instance_method(klass, meth_name, meth_obj)
+    @@proxied_instance_methods[klass.name.to_sym][meth_name] = meth_obj
+  end
+  
+  def self.original_instance_method(klass, meth_name)
+    @@proxied_instance_methods[klass.name.to_sym][meth_name]
+  end
+  
+  def self.tmp_binding
+    @@tmp_binding
+  end
+  
+  protected
+  def self.capture_tmp_binding!(bndg)
+    @@tmp_binding = bndg
+  end
+  
+  def self.reset_tmp_binding!
+    @@tmp_binding = nil
+  end
+  
+  ####################################### MAIN STUFF #################################################
+  public
+  
+  # "Tap" into instance method calls - subvert original method with the supplied block; preserve
+  # reference to the original method so that it can still be called or restored later on.
+  #
+  # Common idiom:
+  # MethodProxy.proxy_instance_method(SomeClass, :some_instance_method) do |obj, original_instance_meth, *args, &block|
+  #
+  #   # do stuff before calling original method
+  #     ... ... ...
+  #
+  #   # call the original method (already bound to object obj), with supplied arguments
+  #   result = original_instance_meth.call(*args, &block)
+  #
+  #   # do stuff after calling original method
+  #     ... ... ...
+  #
+  #   # return the actual return value
+  #   result
+  # end
+  def self.proxy_instance_method(klass, meth, &block)
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    raise "method argument must be a Symbol" unless meth.is_a?(Symbol)
+    raise "must supply block argument" unless block_given?
+    
+    proc = Proc.new(&block)
+    
+    @@mx.synchronize do
+      @@proxied_instance_methods[klass.name.to_sym] ||= {}
+      if @@proxied_instance_methods[klass.name.to_sym][meth]
+        raise ::MethodProxyException, "The method has already been proxied"
+      end
+    
+      klass.class_eval do
+      
+        MethodProxy.register_original_instance_method(klass, meth, instance_method(meth))
+      
+        undef_method(meth)
+    
+        define_method meth do |*args, &blk|
+          ret = proc.call(self, MethodProxy.original_instance_method(klass, meth).bind(self), *args, &blk)
+          return ret
+        end
+      end
+    end
+  end
+  
+  # Restore the original instance method for objects of class klass
+  def self.unproxy_instance_method(klass, meth)
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    raise "method argument must be a Symbol" unless meth.is_a?(Symbol)
+    
+    @@mx.synchronize do
+      return unless @@proxied_instance_methods[klass.name.to_sym][meth].is_a?(UnboundMethod)    # pass-through rather than raise
+      proc = @@proxied_instance_methods[klass.name.to_sym][meth]
+    
+      klass.class_eval{ define_method(meth, proc) }
+      
+      # clean up storage
+      @@proxied_instance_methods[klass.name.to_sym].delete(meth)
+      remaining_proxied_instance_methods = @@proxied_instance_methods[klass.name.to_sym]
+      @@proxied_instance_methods.delete(klass.name.to_sym) if remaining_proxied_instance_methods.empty?
+    end
+  end
+  
+  # "Tap" into class method calls - subvert original method with the supplied block; preserve
+  # reference to the original method so that it can still be called or restored later on.
+  #
+  # Common idiom:
+  # MethodProxy.proxy_class_method(SomeClass, :some_class_method) do |klass, original_class_meth, *args, &block|
+  #
+  #   # do stuff before calling original method
+  #     ... ... ...
+  #
+  #   # call original method (already bound to SomeClass), with supplied arguments
+  #   result = original_class_meth.call(*args, &block)
+  #
+  #   # do stuff after calling original method
+  #     ... ... ...
+  #
+  #   # return the actual return value
+  #   result
+  # end
+  def self.proxy_class_method klass, meth, &block
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    raise "method argument must be a Symbol" unless meth.is_a?(Symbol)
+    raise "must supply block argument" unless block_given?
+    
+    @@mx.synchronize do
+      proc = Proc.new(&block)
+      
+      capture_tmp_binding! binding
+      
+      @@proxied_class_methods[klass.name.to_sym] ||= {}
+    
+      class << klass
+        
+        klass, meth, proc = eval "[klass, meth, proc]", MethodProxy.tmp_binding
+        
+        self.instance_eval do
+          if @@proxied_class_methods[klass.name.to_sym][meth]
+            raise ::MethodProxyException, "The method has already been proxied"
+          end
+          @@proxied_class_methods[klass.name.to_sym][meth] = instance_method meth
+        end
+      
+        remove_method meth
+      
+        self.instance_eval do
+          define_method(meth) do |*args, &blk|
+            ret = proc.call(self, @@proxied_class_methods[klass.name.to_sym][meth].bind(self), *args, &blk)
+            return ret
+          end
+        end
+      end
+      
+      reset_tmp_binding!
+    end
+  end
+  
+  # Restore the original class method for klass
+  def self.unproxy_class_method klass, meth
+    raise "klass argument must be a Class" unless klass.is_a?(Class) || klass.is_a?(Module)
+    raise "method argument must be a Symbol" unless meth.is_a?(Symbol)
+    
+    @@mx.synchronize do
+      return unless (class_entries = @@proxied_class_methods[klass.name.to_sym])
+      return unless (orig_unbound_meth = class_entries[meth])
+    
+      capture_tmp_binding! binding
+    
+      class << klass
+        meth, orig_unbound_meth = eval "[meth, orig_unbound_meth]", MethodProxy.tmp_binding
+        self.instance_eval do
+          define_method meth, orig_unbound_meth
+        end
+      end
+      
+      reset_tmp_binding!
+      
+      # clean up storage
+      @@proxied_class_methods[klass.name.to_sym].delete(meth)
+      remaining_proxied_class_methods = @@proxied_class_methods[klass.name.to_sym]
+      @@proxied_class_methods.delete(klass.name.to_sym) if remaining_proxied_class_methods.empty?
+    end
+  end
+end

data/test/method_proxy_test.rb

@@ -0,0 +1,126 @@
+class GuineaPig
+  def gp_instance_method a, b
+    return "#{a}-#{b}"
+  end
+  
+  def gp_instance_method_w_block a, b, &block
+    interm = "*#{a}*#{b}*"
+    res = yield interm
+    res
+  end
+  
+  def self.gp_class_method c, d
+    return "#{c}$#{d}"
+  end
+  
+  def self.gp_class_method_w_block c, d, &block
+    interm = "-=#{c}O#{d}=-"
+    res = yield interm
+    res
+  end
+end
+
+require File.join(File.expand_path(File.dirname(__FILE__)), "../lib/method_proxy")
+require "test/unit"
+
+class MethodProxyTest < Test::Unit::TestCase
+  def test_proxy_unproxy_instance_method
+    gpig = GuineaPig.new
+    assert_equal "2-3", gpig.gp_instance_method(2, 3)
+    assert [].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [], MethodProxy.proxied_instance_methods_for(GuineaPig)
+    
+    MethodProxy.proxy_instance_method(GuineaPig, :gp_instance_method) do |obj, meth, a, b|
+      res = meth.call a, b
+      next "<#{res}>"   # within Proc's should be 'next' instead of 'return' -- in order to avoid returning from the caller method
+    end
+    assert_equal "<2-3>", gpig.gp_instance_method(2, 3)
+    assert [GuineaPig].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [:gp_instance_method], MethodProxy.proxied_instance_methods_for(GuineaPig)
+    
+    MethodProxy.unproxy_instance_method(GuineaPig, :gp_instance_method)
+    assert_equal "2-3", gpig.gp_instance_method(2, 3)
+    assert [].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [], MethodProxy.proxied_instance_methods_for(GuineaPig)
+  end
+  
+  def test_proxy_unproxy_instance_method_w_block
+    gpig = GuineaPig.new
+    before_res = gpig.gp_instance_method_w_block(6, 7) do |interm|
+      "#{interm}<-->#{interm}"
+    end
+    assert [].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [], MethodProxy.proxied_instance_methods_for(GuineaPig)
+    assert_equal "*6*7*<-->*6*7*", before_res
+    
+    MethodProxy.proxy_instance_method(GuineaPig, :gp_instance_method_w_block) do |obj, meth, a, b, &block|
+      res = meth.call a, b, &block
+      next "!!!__#{res}__!!!"   # within Proc's should be 'next' instead of 'return' -- in order to avoid returning from the caller method
+    end
+    
+    after_res = gpig.gp_instance_method_w_block(6, 7) do |interm|
+      "#{interm}<-->#{interm}"
+    end
+    
+    assert_equal "!!!__*6*7*<-->*6*7*__!!!", after_res
+    assert [GuineaPig].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [:gp_instance_method_w_block], MethodProxy.proxied_instance_methods_for(GuineaPig)
+    
+    MethodProxy.unproxy_instance_method(GuineaPig, :gp_instance_method_w_block)
+    after_un_res = gpig.gp_instance_method_w_block(6, 7) do |interm|
+      "#{interm}<-->#{interm}"
+    end
+    assert_equal before_res, after_un_res
+    assert [].eql?(MethodProxy.classes_with_proxied_instance_methods)
+    assert_equal [], MethodProxy.proxied_instance_methods_for(GuineaPig)
+  end
+  
+  def test_proxy_unproxy_class_method
+    assert_equal "4$5", GuineaPig.gp_class_method(4, 5)
+    assert [].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [], MethodProxy.proxied_class_methods_for(GuineaPig)
+
+    MethodProxy.proxy_class_method(GuineaPig, :gp_class_method) do |obj, meth, c, d|
+      res = meth.call c, d
+      next "[#{res}]"   # within Proc's should be 'next' instead of 'return' -- in order to avoid returning from the caller method
+    end
+    assert_equal "[4$5]", GuineaPig.gp_class_method(4, 5)
+    assert [GuineaPig].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [:gp_class_method], MethodProxy.proxied_class_methods_for(GuineaPig)
+    
+    MethodProxy.unproxy_class_method(GuineaPig, :gp_class_method)
+    assert_equal "4$5", GuineaPig.gp_class_method(4, 5)
+    assert [].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [], MethodProxy.proxied_class_methods_for(GuineaPig)
+  end
+  
+  def test_proxy_unproxy_class_method_w_block
+    before_res = GuineaPig.gp_class_method_w_block(8, 9) do |interm|
+      "#{interm}>--<#{interm}"
+    end
+    assert_equal "-=8O9=->--<-=8O9=-", before_res
+    assert [].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [], MethodProxy.proxied_class_methods_for(GuineaPig)
+    
+    MethodProxy.proxy_class_method(GuineaPig, :gp_class_method_w_block) do |obj, meth, a, b, &block|
+      res = meth.call a, b, &block
+      next "???__#{res}__???"   # within Proc's should be 'next' instead of 'return' -- in order to avoid returning from the caller method
+    end
+    
+    after_res = GuineaPig.gp_class_method_w_block(8, 9) do |interm|
+      "#{interm}>--<#{interm}"
+    end
+    
+    assert_equal "???__-=8O9=->--<-=8O9=-__???", after_res
+    assert [GuineaPig].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [:gp_class_method_w_block], MethodProxy.proxied_class_methods_for(GuineaPig)
+    
+    MethodProxy.unproxy_class_method(GuineaPig, :gp_class_method_w_block)
+    after_un_res = GuineaPig.gp_class_method_w_block(8, 9) do |interm|
+      "#{interm}>--<#{interm}"
+    end
+    assert_equal before_res, after_un_res
+    assert [].eql?(MethodProxy.classes_with_proxied_class_methods)
+    assert_equal [], MethodProxy.proxied_class_methods_for(GuineaPig)
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: method_proxy
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 1
+  version: 0.2.1
+platform: ruby
+authors: 
+- Jevgenij Solovjov
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-01 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: |-
+  Provides convenient means of "taping" into instance or class method calls. The intercepting
+  code is provided with reference to the object, reference to the original method and list of arguments.
+email: jevgenij@kudelabs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/method_proxy.rb
+- test/method_proxy_test.rb
+- README.markdown
+has_rdoc: true
+homepage: https://github.com/kudelabs/method_proxy
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby method call interception tool.
+test_files: []
+