rcapture 1.0.4

data/License

@@ -0,0 +1,26 @@
+
+# = License
+#
+# Copyright (c) 2010, Christoph Heindl
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification, 
+# are permitted provided that the following conditions are met:
+# - Redistributions of source code must retain the above copyright notice, this list 
+#   of conditions and the following disclaimer.
+# - Redistributions in binary form must reproduce the above copyright notice, this list 
+#   of conditions and the following disclaimer in the documentation and/or other materials 
+#   provided with the distribution.
+# - Neither the name of the Christoph Heindl nor the names of its contributors may be 
+#   used to endorse or promote products derived from this software without specific prior 
+#   written permission.
+#
+# 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.

data/README

@@ -0,0 +1,46 @@
+
+= RCapture
+This package contains the module RCapture, a collection of intuitive methods to capture method invocations.
+
+RCapture has the following features
+- Capturing of instance and class methods of individual objects or entire population of objects.
+- Capturing pre or post method invocation.
+- Multiple capturings per method.
+- Modify method arguments and return values.
+- Filter method calls.
+- Developed with multithreaded environments in mind.
+and many more.
+
+= Simple Example
+The example below will capture insertion methods of arrays and output statistics upon 
+invocation. For more examples see RCapture module documentation.
+
+ require 'rcapture'
+ 
+ class Array
+  include RCapture::Interceptable
+ end
+ 
+ Array.capture_post :methods => [:<<, :push] do |cs|
+  puts "#{cs.args.first} was inserted to array #{cs.sender}"
+ end
+ 
+ [] << 1 << 2
+ [].push 3
+ 
+ #=> 1 was inserted to array [1]
+ #=> 2 was inserted to array [1, 2]
+ #=> 3 was inserted to array [3]
+ 
+= Requirements
+Non except Ruby. This distribution was tested on Ruby 1.8.6 and Ruby 1.9.1.
+ 
+= License
+RCapture is Copyright (c) 2010 Christoph Heindl. It is free software, and may be redistributed under the terms 
+specified in the {License}[link:files/License.html] file.
+
+= Support
+The RCapture homepage is http://code.google.com/p/cheind-blog-files. There you will find links report 
+{issues}[http://code.google.com/p/cheind-blog-files/issues/list] (use tag component-rcapture) and latest source code.
+You might find additional help on the author's homepage http://cheind.wordpress.com. For general questions contact the 
+author via email at {christoph.heindl@gmail.com}[mailto:christoph.heindl@gmail.com]

data/Rakefile

@@ -0,0 +1,38 @@
+#
+# (c) Christoph Heindl, 2010
+# http://cheind.wordpress.com
+#
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+task :default => [:test_units]
+
+desc "Run unit tests"
+Rake::TestTask.new("test") { |t|
+  t.pattern = FileList['test/unit/test_*.rb']
+  t.verbose = true
+  t.warning = false
+}
+
+desc "Run acceptance tests"
+Rake::TestTask.new("acceptance") { |t|
+  t.pattern = FileList['test/acceptance/acc_*.rb']
+  t.verbose = false
+  t.warning = false
+}
+
+desc "Run benchmarks"
+Rake::TestTask.new("benchmark") { |t|
+  t.pattern = FileList['test/benchmark/benchmark_*.rb']
+  t.verbose = false
+  t.warning = false
+}
+
+desc "Generate rdoc documentation"
+Rake::RDocTask.new do |rd|
+  rd.main = 'README'
+  rd.rdoc_dir = "doc"
+  rd.rdoc_files.include('README', 'License', 'rcapture/**/*.rb')
+end

data/example/class_methods.rb

@@ -0,0 +1,14 @@
+  require 'rcapture'
+
+  # Enrich Math module
+  module Math
+    include RCapture::Interceptable
+  end
+  
+  Math.capture_pre :class_methods => [:cos, :acos, :sin, :asin] do
+    puts "Hello Trigonometry!"
+  end
+
+  Math.cos(0)
+  
+  #=> Hello Trigonometry!

data/example/filter_method_calls.rb

@@ -0,0 +1,24 @@
+  require 'rcapture'
+
+  # This array will only accept even numbers
+  x = []
+  x.extend(RCapture::Interceptable)
+  
+  even_filter = Proc.new do |ci|
+    # Define the predicate that must evaluate to true
+    # in order to call the captured method
+    ci.predicate = (ci.args.first % 2 == 0)
+    
+    # In case the predicate evaluates to false you
+    # can use the return property to control
+    # what is returned from the captured method instead
+    # Insertion to array returns the array itself:
+    ci.return = ci.sender
+  end
+  
+  x.capture_pre :methods => [:<<, :push], &even_filter
+    
+  x << 2 << 3 << 4 << 5 << 6
+  x.push(7).push(8)
+  p x
+  #=> [2,4,6,8]

data/example/hello_world.rb

@@ -0,0 +1,35 @@
+  require 'rcapture'
+
+  # Enrich Array class.
+  class Array
+    include RCapture::Interceptable
+  end
+
+  # Install a hook at insertion methods of Array.
+  # Calling capture methods at class level will capture
+  # insertions from all instances of Array.
+  Array.capture_pre :methods => [:<<, :push] do |cs|
+    puts "'#{cs.method}' will be called with #{cs.args.first}"
+  end
+
+  [] << 1 << 2
+  [].push :hello
+
+  # Installing a hook on instance level will
+  # affect only that single instance
+  a = []
+  a.capture_post :methods => :length do |cs|
+    puts "Length of 'a' is #{cs.return}"
+  end
+
+  a << 1
+  a.length
+
+  # Any other array will not be affected
+  [].length
+
+  #=> '<<' was called with 1!
+  #=> '<<' was called with 2!
+  #=> 'push' was called with hello!
+  #=> '<<' was called with 1!
+  #=> Length of 'a' is 1

data/example/inheritance.rb

@@ -0,0 +1,36 @@
+  require 'rcapture'
+  include RCapture
+
+  # Closed polygon
+  class Polygon
+    include Interceptable
+    def vertices; self.edges; end
+  end
+
+  # Triangle
+  class Triangle < Polygon
+    def edges; 3; end
+  end
+
+  # Degenerate polygon
+  class Digon < Polygon
+    def edges; 1; end
+    def vertices; 2; end
+  end
+
+  # Four sided polygon
+  class Quadliteral < Polygon
+    def edges; 4; end
+    def vertices; super; end
+  end
+  
+  called = 0
+  Polygon.capture :methods => :vertices do
+    called += 1
+  end
+  
+  Triangle.new.vertices # +1
+  Digon.new.vertices # -
+  Quadliteral.new.vertices # +1
+  
+  p called #=> 2

data/example/modify_arguments.rb

@@ -0,0 +1,39 @@
+  require 'rcapture'
+
+  # Enrich single instance
+  x = []
+  x.extend(RCapture::Interceptable)
+  
+  # Define procs that will modify the input arguments
+  inc = Proc.new { |ci| ci.args[0] += 1 }
+  dec = Proc.new { |ci| ci.args[0] -= 1 }
+  mul = Proc.new { |ci| ci.args[0] *= 2 }
+
+  # Capture ':<<' multiple times.
+  x.capture_pre :methods => :<<, &inc
+  x.capture_pre :methods => :<<, &mul
+  x.capture_pre :methods => :<<, &inc
+  x.capture_pre :methods => :<<, &dec
+  x.capture_pre :methods => :<<, &dec
+  
+  x << 2 << 4
+  p x
+  #=> [3,7]
+  
+  # Similarily, you can modify return values
+  y = []
+  y.extend(RCapture::Interceptable)
+  
+  inc = Proc.new { |ci| ci.return += 1 }
+  dec = Proc.new { |ci| ci.return -= 1 }
+  mul = Proc.new { |ci| ci.return *= 2 }
+  
+  y.capture_post :methods => :[], &inc
+  y.capture_post :methods => :[], &mul
+  y.capture_post :methods => :[], &inc
+  y.capture_post :methods => :[], &dec
+  y.capture_post :methods => :[], &dec
+  
+  y << 1 << 4
+  p y[0] #=> 3
+  p y[1] #=> 9

data/example/multithreaded.rb

@@ -0,0 +1,32 @@
+  require 'rcapture'
+  require 'thread'
+  
+  # Will keep track of Enumberable#inject results
+  inject_results = []
+  m = Mutex.new
+  
+  module Enumerable
+    include RCapture::Interceptable
+  end
+  
+  Enumerable.capture :methods => :inject do |cs|
+    # Callbacks can be invoked from multiple threads.
+    # So we need to synchronize access to shared resources.
+    m.synchronize do
+      inject_results << cs.return
+    end
+  end
+  
+  array = []
+  10000.times {array << rand(100)}
+  
+  threads = []
+  5.times do
+    t = Thread.new do
+      sum = array.inject(0) {|memo, e| memo + e}
+    end
+    threads << t
+  end
+  threads.each {|t| t.join }
+  
+  p inject_results #=> [493311, 493311, 493311, 493311, 493311] or similar

data/example/new_with_block.rb

@@ -0,0 +1,30 @@
+  require 'rcapture'
+  include RCapture
+
+  class X
+    include Interceptable
+    def initialize(name); @name = name; end
+    def say_hello; puts "Hello, #{@name}!"; end
+  end
+
+  class Y < X
+    def initialize; super("Y"); end
+  end
+
+  X.capture :class_methods => :new do |ci|
+    ci.block.call(ci.return) if ci.block
+  end
+
+  # Now you can use X and Y as if it supports
+  # blocks
+  x = X.new("Christoph") do |x|
+    x.say_hello #=> "Hello, Christoph!"
+  end
+
+  y = Y.new do |y|
+    y.say_hello #=> "Hello, Y!"
+  end
+
+  # Or leaf the block argument away
+  x = X.new("Christoph")
+  y = Y.new

data/example/no_endless_recursion.rb

@@ -0,0 +1,16 @@
+  require 'rcapture'
+  
+  class Fixnum
+    include RCapture::Interceptable
+  end
+  
+  op_count = 0
+  Fixnum.capture :methods => :+ do |cs|
+    # Here we use Fixnum#+ inside the callback.
+    # RCapture takes special care that anything that
+    # happens inside a callback remains capture-free.
+    op_count = op_count + 1
+  end
+  
+  x = 1 + 1 + 2 + 3
+  p op_count #=> 3

data/rcapture.rb

@@ -0,0 +1,19 @@
+#
+# (c) Christoph Heindl, 2010
+# http://cheind.wordpress.com
+#
+
+require 'rcapture/symbol'
+require 'rcapture/capture_status'
+require 'rcapture/captured_info'
+require 'rcapture/singleton_class'
+require 'rcapture/interceptable'
+require 'rcapture/capture'
+if RUBY_VERSION >= "1.9" # will fail when ruby reaches 1.10
+  require 'rcapture/capture_19x'
+else
+  require 'rcapture/capture_18x'
+end
+
+
+

data/rcapture/capture.rb

@@ -0,0 +1,60 @@
+
+module RCapture
+  
+  # RCapture internal methods
+  module Internal # :nodoc:
+  
+    # Perform a pre-capture on the given class.
+    def Internal.capture_pre(klass, args, &callback)
+      CaptureStatus.current.use(false) do
+        RCapture::Internal.capture(klass, { :type => :pre }.merge(args), &callback)
+      end
+    end
+    
+    # Perform a post-capture on the given class.
+    def Internal.capture_post(klass, args, &callback)
+      CaptureStatus.current.use(false) do
+        RCapture::Internal.capture(klass, { :type => :post }.merge(args), &callback)
+      end
+    end
+
+    # Dispatches to internal methods by arguments provided.
+    def Internal.capture(klass, args, &callback)
+      args = { :methods => [], :class_methods => [] }.merge(args)
+      
+      RCapture::Internal.capture_methods(
+        klass,
+        args[:methods].to_a,
+        args,
+        &callback
+      )
+    
+      RCapture::Internal.capture_methods(
+        RCapture::Internal.singleton_class(klass),
+        args[:class_methods].to_a,
+        args,
+        &callback
+      )
+    end
+
+    # Iterate over each method and install capturing code
+    def Internal.capture_methods(klass, methods, additional_args, &callback)
+      type = additional_args[:type]
+      methods.each do |m|
+        RCapture::Internal.capture_single_method(klass, m.to_sym, type, additional_args, &callback)
+      end
+    end
+    
+    # Install capturing code at single method.
+    # Dispatches based on the type of capturing (pre/post)
+    def Internal.capture_single_method(klass, method, type, additional_args, &callback)
+      case type
+        when :post
+          RCapture::Internal.capture_single_post(klass, method, additional_args, &callback)
+        when :pre
+          RCapture::Internal.capture_single_pre(klass, method, additional_args, &callback)
+      end
+    end
+    
+  end
+end

data/rcapture/capture_18x.rb

@@ -0,0 +1,78 @@
+
+module RCapture
+
+  module Internal
+  
+    # Pre-capture single method.
+    # This version is used on Ruby 1.8.x where define_method
+    # does not allow for block arguments. See http://tinyurl.com/yczowjx
+    def Internal.capture_single_pre(klass, method, additional_args, &callback)
+      prev = klass.instance_method(method)
+      id = prev.object_id
+      is_private = klass.private_instance_methods.include?(method.to_s)
+      
+      klass.class_eval do
+        define_method "#{method}_#{id}_" do |b, *args|
+          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}_#{id}_"
+      end
+      
+      klass.class_eval <<-EOF 
+        def #{method} *args, &block
+          self.send "#{method}_#{id}_", block, *args
+        end
+        private "#{method}" if #{is_private}
+      EOF
+    end
+    
+    # Post-capture single method.
+    # This version is used on Ruby 1.8.x where define_method
+    # does not allow for block arguments. See http://tinyurl.com/yczowjx
+    def Internal.capture_single_post(klass, method, additional_args, &callback)
+      prev = klass.instance_method(method)
+      id = prev.object_id
+      is_private = klass.private_instance_methods.include?(method.to_s)
+      
+      klass.class_eval do
+        define_method "#{method}_#{id}_" do |b, *args|
+          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}_#{id}_"
+      end
+   
+      klass.class_eval <<-EOF 
+        def #{method} *args, &block
+          self.send "#{method}_#{id}_", block, *args
+        end
+        private "#{method}" if #{is_private}
+      EOF
+    end
+  end
+end
+