rcapture 1.0.4

data/rcapture/capture_19x.rb

@@ -0,0 +1,65 @@
+
+module RCapture
+
+  module Internal
+  
+    # Pre-capture single method.
+    # This version is used on Ruby 1.9.x where define_method
+    # allows for block arguments
+    def Internal.capture_single_pre(klass, method, additional_args, &callback)
+      prev = klass.instance_method(method)
+      # http://eigenclass.org/hiki/Changes+in+Ruby+1.9#l32
+      is_private = klass.private_instance_methods.include?(method)
+      
+      klass.class_eval do
+        # http://eigenclass.org/hiki/Changes+in+Ruby+1.9#l11
+        define_method "#{method}" do |*args, &b|
+          status = CaptureStatus.current
+          call_prev = true; alt_ret = nil
+          if status.on?
+            status.use(false) do
+              ci = CapturedInfo.current
+              ci.fill(args, self, method, b)
+              callback.call(ci)
+              alt_ret = ci.return
+              call_prev = ci.predicate
+            end
+          end
+          if call_prev
+            prev.bind(self).call(*args, &b)
+          else
+            alt_ret
+          end
+        end
+        private "#{method}" if is_private
+      end
+    end
+    
+    # Post-capture single method.
+    # This version is used on Ruby 1.9.x where define_method
+    # allows for block arguments
+    def Internal.capture_single_post(klass, method, additional_args, &callback)
+      prev = klass.instance_method(method)
+      # http://eigenclass.org/hiki/Changes+in+Ruby+1.9#l32
+      is_private = klass.private_instance_methods.include?(method)
+      
+      klass.class_eval do
+        define_method "#{method}" do |*args, &b|
+          ret = prev.bind(self).call(*args, &b)
+          status = CaptureStatus.current
+          if status.on?
+            status.use(false) do
+              ci = CapturedInfo.current
+              ci.fill(args, self, method, b, ret)
+              callback.call(ci)
+              ret = ci.return
+            end
+          end
+          ret
+        end
+        private "#{method}" if is_private
+      end   
+    end
+  end
+end
+

data/rcapture/capture_status.rb

@@ -0,0 +1,53 @@
+require 'thread'
+
+module RCapture
+
+  # Stack-based boolean enabled/disabled status.
+  # CaptureStatus is used to disable capturing from
+  # within callbacks which could otherwise lead to
+  # infinite recursion or undesired results.
+  class CaptureStatus
+    
+    def initialize(value = true)
+      @status = value
+      @stack = []
+    end
+    
+    # Access thread-local capture status variable
+    def CaptureStatus.current
+      Thread.current[:capture_status] ||= CaptureStatus.new(true)
+    end
+    
+    # Status is set to +value+ while operating on the block.
+    def use(value)
+      begin
+        self.set(value)
+        yield
+      ensure
+        self.restore
+      end
+    end
+    
+    # Set/push new status
+    def set(value)
+      @stack.unshift @status
+      @status = value
+    end
+    
+    # Query status
+    def on?
+      @status
+    end
+    
+    # Query status
+    def off?
+      !@status
+    end
+    
+    # Pop status from stack
+    def restore
+      @status = @stack.shift if @stack.size > 0
+    end
+  end
+  
+end

data/rcapture/captured_info.rb

@@ -0,0 +1,62 @@
+require 'thread'
+
+module RCapture
+
+  # Holds captured method information and acts as a communicator
+  # between callback and RCapture.
+  #
+  # === Post Capture
+  # When called from a method previously captured by +capture_post+,
+  # the following meaning holds true:
+  # args:: Array of input arguments passed to the method.
+  # sender:: Instance the method was called on.
+  # method:: Symbol of method called.
+  # return:: Value returned by method. When modified, the modified value is
+  #          returned from the method.
+  # block:: Block passed to method or nil.
+  # predicate:: Unused.
+  #
+  # === Pre Capture
+  # When called from a method that was previously captured by +capture_pre+,
+  # the following meaning holds true:
+  # args:: Array of input arguments passed to the method. Modifyable.
+  # sender:: Instance the method was called on.
+  # method:: Symbol of method called.
+  # block:: Block passed to method or nil.
+  # predicate:: Initially true. If set to false the captured method will not be invoked.
+  # return:: Initially nil. If +predicate+ is false, then the value of +return+ is returned
+  #          from the method.
+  #
+  class CapturedInfo
+    attr_accessor :args
+    attr_accessor :sender
+    attr_accessor :method
+    attr_accessor :return
+    attr_accessor :predicate
+    attr_accessor :block
+    
+    # Access thread-local CapturedInfo variable
+    def CapturedInfo.current
+      Thread.current[:captured_info] ||= CapturedInfo.new
+    end
+    
+    # Fill with values
+    def fill(args, sender, method, block = nil, ret = nil)
+      @args = args
+      @sender = sender
+      @method = method
+      @return = ret
+      @block = block
+      @predicate = true
+    end
+    
+    alias_method :a, :args
+    alias_method :s, :sender
+    alias_method :m, :method
+    alias_method :r, :return
+    alias_method :r=, :return=
+    alias_method :b, :block
+    alias_method :p, :predicate
+    alias_method :p=, :predicate=
+  end  
+end

data/rcapture/interceptable.rb

@@ -0,0 +1,93 @@
+
+module RCapture
+
+  # = Introduction
+  # Interceptable is a module mixin to enrich the receiver with capturing capatibilities.
+  #
+  # It can be used at a class scope:
+  #
+  #  class Array
+  #    include RCapture::Interceptable
+  #  end
+  #
+  # This will provide the methods +capture+, +capture_pre+, and +capture_post+.
+  # at class and instance level:
+  #
+  #  Array.capture :methods => :push do
+  #    puts 'pushed'
+  #  end
+  #
+  # will affect all instances of Array. On the other hand
+  #
+  #  a = []
+  #  a.capture :methods => :push do
+  #    puts 'pushed'
+  #  end
+  #
+  # will affect only the instance +a+.
+  #
+  # Instances can be extended by Interceptable to provide capturing capatibilities
+  # for the selected instance only:
+  #
+  #  a = []
+  #  a.extend(RCapture::Interceptable)
+  #  a.capture :methods => :push do
+  #    puts 'pushed'
+  #  end
+  module Interceptable
+  
+    module ClassMethods # :nodoc:
+      def capture(args, &callback)
+        RCapture::Internal.capture_post(self, args, &callback)
+      end
+      alias_method :capture_post, :capture
+      
+      def capture_pre(args, &callback)
+        RCapture::Internal.capture_pre(self, args, &callback)
+      end
+    end
+    
+    def self.included(klass) # :nodoc:
+      klass.extend(Interceptable::ClassMethods)
+    end
+    
+    # Perform a post-capture on the given class/instance.
+    #
+    # === Arguments
+    # args:: A hash of options. The following are recognized
+    #        [:methods] Instance methods to capture. Either a single method name/symbol or
+    #                   and array of names/symbols.
+    #        [:class_methods] Class methods to capture. Either a single method name/symbol or
+    #                         and array of names/symbols.
+    # callback:: The block to be invoked after captured method was invoked. The callback will be given
+    #            an instance of CapturedInfo.
+    def capture_post(args, &callback)
+      RCapture::Internal.capture_post(
+        RCapture::Internal.singleton_class(self), 
+        args, 
+        &callback
+      )
+    end
+    alias_method :capture, :capture_post
+    
+    # Perform a pre-capture on the given class/instance.
+    #
+    # === Arguments
+    # args:: A hash of options. The following are recognized
+    #        [:methods] Instance methods to capture. Either a single method name/symbol or
+    #                   and array of names/symbols.
+    #        [:class_methods] Class methods to capture. Either a single method name/symbol or
+    #                         and array of names/symbols.
+    # callback:: The block to be invoked before the captured method is invoked. The callback will be given
+    #            an instance of CapturedInfo.
+    def capture_pre(args, &callback)
+      RCapture::Internal.capture_pre(
+        RCapture::Internal.singleton_class(self), 
+        args, 
+        &callback
+      )
+    end
+    
+  end
+end
+

data/rcapture/module_doc.rb

@@ -0,0 +1,61 @@
+
+# = Introduction
+# The module RCapture is your single entry point when it comes to
+# method capturing/hooking.
+#
+# To hook/capture methods you need to
+# - enrich target(s) with capturing capatibilities. This is provided by the module mixin Interceptable.
+# - capture the methods by invoking methods from Interceptable.
+#
+# = Examples
+# Here is a set of examples that should help you getting started. Those examples are part of
+# the RCapture distribution
+#
+# == Hello World
+# The following example illustrates basic class and instance level hooking and
+# makes use of the passed CapturedInfo instance to query details.
+# :include:example/hello_world.rb
+#
+# == Class Methods
+# In this example quickly shows how to hook class methods.
+# :include:example/class_methods.rb
+#
+# == Modifying Arguments and Return Values
+# The following example illustrates capturing methods in order to modify input and return arguments.
+# Further, it illustrates how capture methods of a single instance only.
+# :include:example/modify_arguments.rb
+#
+# == Filtering Method Calls
+# Additionally to modifying arguments you can prevent captured method from being called using a Interceptable#capture_pre hook.
+# :include:example/filter_method_calls.rb
+#
+# == Callbacks Are Capture-Free
+# During processing of a callback, capturing is disabled. Otherwise, this could lead to infinite recursion as the following
+# examples demonstrates.
+# :include:example/no_endless_recursion.rb
+#
+# == Inheritance
+# Captured methods propagate through derivates as long as they are not overridden by a class.
+# :include:example/inheritance.rb
+#
+# == Multithreading
+# RCapture is a lock-free implementation that supports multithreading. There is no restriction on the number of threads
+# that call a shared callback. Captures, however, should be called only from a single thread or guaranteed to be synchronized
+# by the user. Since callbacks can be invoked from multiple threads in parallel, shared resources from within the callbacks
+# need to be synchronized by the user. The passed CapturedInfo is a thread-local variable and needs not to be synchronized.
+# The following example illustrates this.
+# :include:example/multithreaded.rb
+#
+# == New with Block
+# Here is one final example that stimulate your imagination of what can be done with RCapture: given any class, it is often
+# desireable to work with newly created instance by passing a block to new. If that class does not support this you can use
+# RCapture to enable this behaviour.
+# :include:example/new_with_block.rb
+#
+# = Benchmark
+# RCapture works on Ruby 1.8.x and 1.9.x. Due to API changes between 1.8 and 1.9, RCapture selects an appropriate
+# implementation of its core methods. Here is a benchmark that illustrates the overhead on 1.8 and 1.9 when
+# a captured method is called.
+# :include:test/benchmark/benchmark_capture.rb
+module RCapture
+end

data/rcapture/singleton_class.rb

@@ -0,0 +1,12 @@
+
+module RCapture
+  module Internal
+    # Access singleton class of given object
+    def Internal.singleton_class(t)
+      class << t
+        self
+      end
+    end
+  end  
+end
+

data/rcapture/symbol.rb

@@ -0,0 +1,7 @@
+
+# Extend Symbol to override default to_a behaviour which is deprecated.
+class Symbol
+  def to_a
+    return [self]
+  end
+end

data/test/acceptance/acc_array.rb

@@ -0,0 +1,36 @@
+#
+# (c) Christoph Heindl, 2010
+# http://cheind.wordpress.com
+#
+
+require 'test/unit'
+
+require 'rcapture'
+
+class Array
+  include RCapture::Interceptable
+end
+
+class TestAcceptanceArrray < Test::Unit::TestCase
+    
+  def test_array
+    op_count = 0
+    a = Array.new  
+    
+    a.capture :methods => [:push, :<<] do |ci|
+      puts "intercepted"
+    end
+    
+    Array.capture_pre :class_methods => :new  do |ci|
+      p "new called"
+    end
+    
+    r = Array.new(3)
+    
+    a << 1 << 2
+    [] << 1
+    p a
+    
+    
+  end
+end

data/test/acceptance/acc_inheritance.rb

@@ -0,0 +1,61 @@
+#
+# (c) Christoph Heindl, 2010
+# http://cheind.wordpress.com
+#
+
+require 'test/unit'
+
+require 'rcapture'
+include RCapture
+
+# Closed polygon dummy
+class Polygon
+  include Interceptable
+  def vertices
+    self.edges
+  end
+end
+
+class Triangle < Polygon
+  def edges
+    3
+  end
+end
+
+ # Degenerate Polygon
+class Digon < Polygon
+  def edges
+    1
+  end
+  
+  def vertices
+    2
+  end
+end
+
+class Quadliteral < Polygon
+  def edges
+    4
+  end
+  
+  def vertices
+    super
+  end
+end
+
+class AcceptanceInheritance < Test::Unit::TestCase 
+  def test_inheritance
+    called = 0
+    Polygon.capture :methods => :vertices do |ci|
+      called += 1
+    end
+    
+    assert_equal(3, Triangle.new.vertices)
+    assert_equal(1, called)
+    
+    assert_equal(2, Digon.new.vertices)
+    assert_equal(1, called)
+    assert_equal(4, Quadliteral.new.vertices)
+    assert_equal(2, called)
+  end
+end