zimbatm-monkeypatch 0.1.0

data/README.rdoc

@@ -0,0 +1,34 @@
+= MonkeyPatch
+
+  <INSERT NICE INTRO HERE>
+
+  Do you monkeys, patch ? If so, use this library, you won't regret it.
+
+  Why use a library when you could do all this by hand ? For two reasons:
+
+  1. We provide the mechanism to protect from patch collision
+  2. By including this gem as dependency, you declare your project is
+     monkeypatching.
+
+  </INSERT NICE INTRO HERE>
+
+== Usage
+
+Example usage:
+
+  :include:example/patch_usage.rb
+
+== Related projects
+
+* http://github.com/coderrr/monkey_shield/ : provides sorts of namespaces to avoid patch collision
+
+== Ideas
+
+* method re-definition or module/class extension could be detected, especially when using Gems. The load-path is not the same between the original definition and the new-one.
+* load-path as namespace
+
+== TODO
+
+* Add programmable patching conditions
+* Add reason string
+* Add 'monkeywarn' that warns when a monkeypatch is applied

data/Rakefile

@@ -0,0 +1,9 @@
+$:.push('lib')
+require 'monkeypatch'
+
+Dir['task/*.rake'].each do |lib|
+  load lib
+end
+
+desc "Same as `rake test`"
+task :default => :test

data/example/patch_usage.rb

@@ -0,0 +1,24 @@
+require 'monkeypatch'
+
+# Define a new extension that adds the #to_blob method
+date_patch = MonkeyPatch.add_method(:to_blob) do
+  def to_blob; "<blob>" end
+end
+
+x = "something"
+date_patch.patch_instance(x)
+x.to_blob #=> "<blob>"
+
+# Define a patch, that replaces the #to_date method
+each_patch = MonkeyPatch.replace_method(:to_s) do
+  def to_s; "..." end
+end
+
+class ExampleClass
+  def to_s; "hello" end
+end
+
+(date_patch & each_patch).patch_class(ExampleClass)
+
+ExampleClass.new.to_s #=> "..."
+ExampleClass.new.to_blob #=> "<blob>"

data/lib/monkeypatch.rb

@@ -0,0 +1,212 @@
+=begin rdoc
+
+This is the public API to produce new patches.
+
+Once you have a patch, look at Patch and it's children to see how to use it.
+
+=end
+module MonkeyPatch
+  # MonkeyPatch's version as a string
+  VERSION = '0.1.0'
+  # May be raised on check_conflicts
+  class ConflictError < StandardError; end
+  
+  # A collection of patches. Used to collect one or more patches with the #& operator
+  # 
+  # NOTE: didn't use the Set class, to not force a dependency
+  class PatchSet
+    def initialize(patches) #:nodoc:
+      @patches = patches.to_a.uniq
+    end
+    
+    # Aggregates Patch (es) and PatchSet (s)
+    def &(other)
+      PatchSet.new(@patches + other.to_a)
+    end
+    def to_a; @patches.dup end
+    
+    # Delegates to patches
+    # TODO: determine what happens if a patch fails
+    def patch_class(klass)
+      @patches.each do |patch|
+        patch.patch_class(klass)
+      end
+    end
+    
+    # Delegates to patches
+    def patch_instance(obj)
+      for patch in @patches
+        patch.patch_instance(obj)
+      end
+    end
+  end
+  
+  # Abstract definition of a patch.
+  # 
+  # You cannot create Patch instance yourself, they are spawned from 
+  # MonkeyPatch class-methods.
+  class Patch
+    class << self
+      # Hide new to force api usage
+      private :new
+    end
+    # The callstack it was defined in
+    attr_reader :from
+    
+    def initialize(&patch_def) #:nodoc:
+      raise ArgumentError, "patch_def not given" unless block_given?
+      @patch_def = patch_def
+    end
+    
+    # Combine patches together. Produces a PatchSet instance.
+    def &(other)
+      PatchSet.new([self]) & other
+    end
+    
+    # Returns [self], used by #&
+    def to_a; [self] end
+  
+    # Patches a class or module instance methods
+    def patch_class(klass)
+      raise ArgumentError, "klass is not a Class" unless klass.kind_of?(Class)
+      
+      return false if !check_conditions(klass)
+      
+      check_conflicts!(klass)
+        
+      # Apply
+      apply_patch(klass)
+        
+      return true
+    end
+
+    # Patches the instance's metaclass
+    def patch_instance(obj)
+      meta = (class << obj; self end)
+      patch_class(meta)
+    end
+    
+  protected
+  
+    # Condition are checks that raise nothing
+    # 
+    # If a condition isn't met, the patch is not applied
+    #
+    # Returns true if all conditions are matched
+    def check_conditions(klass) #:nodoc:
+      if klass.respond_to?(:applied_patches) && klass.applied_patches.include?(self)
+        log "WARN: Patch already applied"
+        return false
+      end
+      true
+    end
+  
+    # Re-implement in childs. Make sure super is called
+    # 
+    # raises a ConflictError if an error is found 
+    def check_conflicts!(klass) #:nodoc:
+    end
+    
+    def apply_patch(klass) #:nodoc:
+      klass.extend IsPatched
+      klass.class_eval(&@patch_def)
+      klass.applied_patches.push self
+    end
+    
+    def log(msg) #:nodoc:
+      MonkeyPatch.logger.log(msg)
+    end
+  end
+  
+  class MethodPatch < Patch
+    # The name of the method to be patched
+    attr_reader :method_name
+    def initialize(method_name, &patch_def) #:nodoc:
+      super(&patch_def)
+      @method_name = method_name.to_s
+      unless Module.new(&patch_def).instance_methods(true) == [@method_name]
+        raise ArgumentError, "&patch_def does not define the specified method"
+      end 
+    end
+    
+  protected
+    def check_conflicts!(klass) #:nodoc:
+      super
+      if klass.respond_to? :applied_patches
+        others = klass.applied_patches.select{|p| p.respond_to?(:method_name) && p.method_name == method_name }
+        if others.any?
+          raise ConflictError, "Conflicting patches: #{([self] + others).inspect}"
+        end
+      end
+    end
+  end
+  
+  # Spawned by MonkeyPatch.add_method
+  class AddMethodPatch < MethodPatch
+  protected
+    def check_conflicts!(klass) #:nodoc:
+      super
+      if klass.method_defined?(method_name)
+        raise ConflictError, "Add already existing method #{method_name} in #{klass}"
+      end
+    end
+  end
+  
+  # Spawned by MonkeyPatch.replace_method
+  class ReplaceMethodPatch < MethodPatch
+  protected
+    def check_conflicts!(klass) #:nodoc:
+      super
+      unless klass.method_defined?(method_name)
+        raise ConflictError, "Replacing method #{method_name} does not exist in #{klass}"
+      end
+    end
+  end
+  
+  # Default MonkeyPatch::logger . Use the same interface
+  # if you want to replace it.
+  class STDERRLogger
+    def log(msg); STDERR.puts msg end
+  end
+  
+  # This module extends patched objects to keep track of the applied patches
+  module IsPatched
+    def applied_patches; @__applied_patches__ ||= [] end
+  end
+  
+  @logger = STDERRLogger.new
+  @loaded_patches = []
+  class << self
+    # Here goes the messages, this object should respond_to? :log
+    # Default is STDERRLogger
+    attr_accessor :logger
+    
+    # All defined patches are stored here
+    attr_reader :loaded_patches
+    
+    # Creates a new patch that adds a method to a class or a module
+    # 
+    # Returns a Patch (AddMethodPatch)
+    def add_method(method_name, &definition)
+      new_patch AddMethodPatch.send(:new, method_name, &definition)
+    end
+    
+    # Creates a new patch that replaces a method of a class or a module
+    #
+    # Returns a Patch (ReplaceMethodPatch)
+    def replace_method(method_name, &definition)
+      new_patch ReplaceMethodPatch.send(:new, method_name, &definition)
+    end
+  
+  protected
+    
+    def new_patch(patch, &definition) #:nodoc:
+      #patch.validate
+      patch.instance_variable_set(:@from, caller[1])
+      @loaded_patches.push(patch)
+      patch
+    end
+  
+  end
+end
+

data/task/gem.rake

@@ -0,0 +1,37 @@
+require 'rake/gempackagetask'
+require 'monkeypatch'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'monkeypatch'
+  s.version = MonkeyPatch::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Monkey patching made safe(er)"
+  s.homepage = "http://github.com/zimbatm/ruby-monkeypatch"
+  s.description = "Provides a mechanism to avoid patch collision. It's also useful to tell if your project is using monkeypatching or not."
+  s.authors = ["zimbatm"]
+  s.email = "zimbatm@oree.ch"
+  s.has_rdoc = true
+  s.files = FileList['README.rdoc', 'Rakefile', 'lib/*', 'test/*', 'task/*', 'example/*']
+  s.test_files = FileList['test/test*.rb']
+end
+
+file "ruby-monkeypatch.gemspec" do |t|
+  File.open(t.name, 'w') do |f|
+    f.write(spec.to_ruby)
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+#  pkg.need_zip = true
+#  pkg.need_tar = true
+end
+
+namespace :gem do
+  desc "Updates the ruby-monkeypatch.gemspec file"
+  task :spec do
+    File.open("ruby-monkeypatch.gemspec", 'w') do |f|
+      f.write(spec.to_ruby)
+    end
+  end
+end
+

data/task/rcov.rake

@@ -0,0 +1,14 @@
+begin
+  require 'rcov/rcovtask'
+  
+  Rcov::RcovTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/test*.rb']
+    t.verbose = true
+  end
+  
+rescue LoadError
+  if !Rake.application.options.silent
+    STDERR.puts "*** Install the RCov for code coverage" 
+  end
+end

data/task/rdoc.rake

@@ -0,0 +1,17 @@
+begin
+  require 'rdoc/task'
+  RDocTask = RDoc::Task
+rescue LoadError
+  if !Rake.application.options.silent
+    STDERR.puts "*** Install the RDoc 2.X gem for nicer docs" 
+  end
+  
+  require 'rake/rdoctask'
+  RDocTask = Rake::RDocTask
+end
+
+RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end
+

data/task/test.rake

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+  t.ruby_opts = ["-Ilib"]
+end

data/test/test_monkeypatch.rb

@@ -0,0 +1,139 @@
+require 'test/unit'
+
+require 'monkeypatch'
+
+class TestMonkeypatch < Test::Unit::TestCase
+  include MonkeyPatch
+  
+  class FakeLogger
+    attr_reader :logs
+    def initialize
+      @logs = []
+    end
+    def log(msg)
+      @logs.push msg
+    end
+  end
+  
+  def setup
+    @logger = MonkeyPatch.logger = FakeLogger.new
+    @logs = @logger.logs
+    @c = Class.new do
+      def existing_method; "original" end
+    end
+    @p_add = MonkeyPatch.add_method(:new_method) do
+      def new_method; "exists" end
+    end
+    @p_repl = MonkeyPatch.replace_method(:existing_method) do
+      def existing_method; "replaced" end
+    end
+  end
+  
+  def test_invalid_patches
+    assert_raise(ArgumentError) do
+      MonkeyPatch.add_method(:new_method)
+    end
+    assert_raise(ArgumentError) do
+      MonkeyPatch.replace_method(:new_method)
+    end
+    assert_raise(ArgumentError) do
+      MonkeyPatch.add_method(:new_method) do
+        def new_method_typo; end
+      end
+    end
+  end
+
+  def test_do_not_apply_twice
+    @p_add.patch_class(@c)
+    @p_add.patch_class(@c)
+    assert_equal 1, @logs.size, "Should be the notice about the twice application"
+    assert_equal [@p_add], @c.applied_patches
+  end
+  
+  def test_add_method
+    @p_add.patch_class(@c)
+    
+    assert_equal("exists", @c.new.new_method )
+  end
+
+  def test_check_conflict
+    p1 = MonkeyPatch.add_method(:some) do
+      def some; "one" end
+    end
+    p2 = MonkeyPatch.add_method(:some) do
+      def some; "thing" end
+    end
+    c = Class.new
+    assert_nothing_raised do
+      p1.patch_class(c)
+    end
+    assert_raise(ConflictError) do
+      p2.patch_class(c)
+    end
+  end
+  
+  def test_replace_method
+    @p_repl.patch_class(@c)
+    
+    assert @c.respond_to?(:applied_patches)
+    
+    assert_equal("replaced", @c.new.existing_method )
+  end
+  
+  def test_patch_class_application
+    assert !@c.new.respond_to?(:applied_patches)
+    @p_add.patch_class(@c)
+    assert_respond_to @c, :applied_patches
+    
+    assert_equal [@p_add], @c.applied_patches
+    
+    @p_repl.patch_class(@c)
+    assert_equal [@p_add, @p_repl], @c.applied_patches
+  end
+  
+  def test_patch_instance_application
+    p = MonkeyPatch.replace_method(:to_s) do
+      def to_s; "right" end
+    end
+    i = "left"
+    p.patch_instance(i)
+    assert_equal("right", i.to_s)
+  end
+  
+  def test_replace_conflict
+    c = Class.new
+    assert_raise(ConflictError) do
+      @p_repl.patch_class(c)
+    end
+    assert !c.new.respond_to?(:existing_method)
+  end
+  
+  def test_add_method_conflict
+    c = Class.new do
+      def new_method; "not replaced" end
+    end
+    assert_raise(ConflictError) do
+      @p_add.patch_class(c)
+    end
+    assert_equal "not replaced", c.new.new_method
+  end
+  
+  def test_patch_from
+    assert_equal(File.basename(__FILE__), File.basename(@p_add.from).gsub(/:.*/,''))
+  end
+  
+  def test_patch_set
+    both = (@p_add & @p_repl)
+    assert_equal(PatchSet, both.class)
+    
+    inst = @c.new
+    both.patch_instance(inst)
+    assert_equal("exists", inst.new_method )
+    assert_equal("replaced", inst.existing_method )
+    
+    both.patch_class(@c)
+    assert_equal("exists", @c.new.new_method )
+    assert_equal("replaced", @c.new.existing_method )
+  end
+  
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: zimbatm-monkeypatch
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- zimbatm
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-26 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Provides a mechanism to avoid patch collision. It's also useful to tell if your project is using monkeypatching or not.
+email: zimbatm@oree.ch
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- Rakefile
+- lib/monkeypatch.rb
+- test/test_monkeypatch.rb
+- task/gem.rake
+- task/rcov.rake
+- task/rdoc.rake
+- task/test.rake
+- example/patch_usage.rb
+has_rdoc: true
+homepage: http://github.com/zimbatm/ruby-monkeypatch
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Monkey patching made safe(er)
+test_files: 
+- test/test_monkeypatch.rb