module_shims 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4fb050764d4610e725df30049551b313d93e388a
+  data.tar.gz: 0b71eb057f042f1c79a702c95f08a24d2941de38
+SHA512:
+  metadata.gz: 60d80f64dd2bb5c112440276dbadd2cfdef577e502df779246c938f6da12a4406606dbc68aa4527980240d4d618a1b96322791fd120a342deb2d5e3ccfa0b4eb
+  data.tar.gz: ec99f0364d5d2de60459a3d11137cb4445234ac394e5bd9b4112ab267bf9fb15b4ff925dc04203a05f81a75f44aef016cf080f5b08cbca87adfbb2018539a459

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.4
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in module_shims.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 ypxing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# Module::Shims
+
+The gem is one tool used for debugging/developing Ruby projects and as one helper for reading/trying source code of Ruby projects (like source code of Ruby on Rails).
+It should NOT be used for production.
+
+In one inheritance chain like [A, B, C, D], it can add shim module to anyone of them so that you can "replace" one method's implementation of one specific module/class with your own implementation without impacting other modules/classes.
+
+Different from monkey patch, you can freely enable/disable your implementation. You can maitain many of your implementation and enable them whenever you want to debug/develop your projects.
+
+It makes use of Module#prepend of Ruby (>= 2.0)
+
+See example in Usage section.
+
+## Installation
+
+Add this line to your application's Gemfile (for development/test groups):
+
+```ruby
+gem 'module_shims'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install module_shims
+
+## Usage
+
+For below inheritance chain [BClass, AModule]
+```ruby
+  module AModule
+    def target
+      'a_module'
+    end
+  end
+
+  class BClass
+    include AModule
+
+    def target
+      'b_class'
+    end
+
+    def irrelevant
+    end
+  end
+```
+
+Let's hook method "target"
+```ruby
+
+  # give BClass one outer namespace.
+  module Mine
+    module BClass
+      extend ModuleShims::Switch
+
+      def target
+        "mine with #{super}"
+      end
+    end
+  end
+
+  Mine::BClass.enable_shim
+  # your target will be used from this line
+
+  BClass.new.target # "mine with a_module"
+
+  Mine::BClass.disable_shim
+  # original target will be used from this line
+
+  BClass.new.target # "b_class"
+
+```
+
+You can keep BClass's method implementation in the inheritance chain like
+
+```ruby
+  Mine::BClass.enable_shim(false)
+  BClass.new.target # "mine with b_class"
+
+```
+
+## Note for adding shim to one module
+
+For existing module M, below code cannot impact existing classes which have already included M.
+```ruby
+Fake::M.enable_shim
+```
+To cover this case, you can put simliar code at the beginning of the boot of your project.
+
+It just makes use of TracePoint and inserts the shim when M is defined.
+You can put all your "fake" modules in below code.
+
+```ruby
+trace = TracePoint.new(:class) do |tp|
+  src_mod =
+    %w(
+      Fake::M
+    ).find { |src| tp.self.name == src.gsub(/\A[^:]+::/, '') }
+
+  src_mod.constantize.insert_shim if src_mod
+end
+
+trace.enable
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ypxing/module_shims.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "module_shims"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/module_shims.rb

@@ -0,0 +1,6 @@
+require "module_shims/version"
+require "module_shims/module_ext"
+require "module_shims/switch"
+
+module ModuleShims
+end

data/lib/module_shims/module_ext.rb

@@ -0,0 +1,65 @@
+class Module
+  def instance_method_inheritance_list(instance_method, location = true)
+    ancestors.find_all do |ancestor|
+      (ancestor.public_instance_methods(false) +
+        ancestor.protected_instance_methods(false) +
+        ancestor.private_instance_methods(false)).include?(instance_method)
+    end
+    .map do |x|
+      m = x.instance_method(instance_method)
+      m.respond_to?(:super_method) && m.super_method ? m.super_method : m
+    end
+    .map { |m| location ? m.source_location : m }.uniq
+  end
+
+  # def supermodule(target = self)
+  #   ancestors[ancestors.index(target) + 1]
+  # end
+
+  def remove_existing_instance_methods(mod)
+    methods = Module === mod ?
+      (mod.public_instance_methods(false) + mod.private_instance_methods(false) + mod.protected_instance_methods(false)) : Array(mod)
+
+    methods.each do |m|
+      remove_method(m) rescue nil
+    end
+  end
+
+  def copy_existing_instance_methods(mod, template = mod)
+    ['public', 'private', 'protected'].each do |perm|
+      perm_s = "#{perm}_"
+      template.send("#{perm_s}instance_methods", false).each do |m|
+        define_method(m, mod.instance_method(m))
+        send("#{perm}", m)
+      end
+    end
+  end
+
+  def prefix_existing_instance_methods(prefix, template = self, remove_prefix = false)
+    ['public', 'private', 'protected'].each do |perm|
+      perm_s = "#{perm}_"
+
+      template.send("#{perm_s}instance_methods", false).each do |m|
+        new_name, old_name =
+          if remove_prefix
+            template == self ? [m[prefix.size..-1], m] : [m, "#{prefix}#{m}"]
+          else
+            ["#{prefix}#{m}", m]
+          end
+
+        next unless send("#{perm_s}instance_methods", false).include?(old_name.to_sym)
+
+        define_method(new_name, instance_method(old_name))
+        send("#{perm}", new_name)
+        remove_method(old_name)
+      end
+    end
+  end
+
+  def remove_instance_methods_from_ancestors(anc_name)
+    ancestors.each do |anc|
+      # just reset all SHIM module
+      anc.remove_existing_instance_methods(anc) if anc.name == anc_name
+    end
+  end
+end

data/lib/module_shims/switch.rb

@@ -0,0 +1,39 @@
+module ModuleShims
+  module Switch
+    def enable_shim(shadow_target = true)
+      insert_shim unless @inserted
+      target_const.prefix_existing_instance_methods('__module_switch', self) if shadow_target
+      shim_const.copy_existing_instance_methods(self)
+    end
+
+    def disable_shim
+      target_const.prefix_existing_instance_methods('__module_switch', self, true)
+      target_const.remove_instance_methods_from_ancestors("#{name}::SHIM")
+    end
+
+    def insert_shim
+      @inserted ||=
+        begin
+          target_const.send(:prepend, shim_const)
+          true
+        end
+    end
+
+    def shim_const
+      @shim ||= const_defined?('SHIM') ? const_get('SHIM') :
+        const_set('SHIM', Module.new{ def self.prepended(mod); mod.remove_instance_methods_from_ancestors(name); super; end })
+    end
+
+    def target_const
+      @target ||= default_target
+    end
+
+    def target_const=(target = default_target)
+      @target = target
+    end
+
+    def default_target
+      const_get(name.gsub(/\A[^:]*/, ''))
+    end
+  end
+end

data/lib/module_shims/version.rb

@@ -0,0 +1,3 @@
+module ModuleShims
+  VERSION = "0.1.0"
+end

data/module_shims.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'module_shims/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "module_shims"
+  spec.version       = ModuleShims::VERSION
+  spec.authors       = ["Yunpeng Xing (Rick)"]
+  spec.email         = ["ypxing@gmail.com"]
+
+  spec.summary       = %q{Insert shims among inheritance chain for debugging/development and reading source code purpose.}
+  spec.description   = %q{It helps you prepend modules in the inheritance chain so that you can easily implement your own methods to override existing ones in specific modules/classes without impacting others.}
+  spec.homepage      = "https://github.com/ypxing/module_shims"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.4"
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: module_shims
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yunpeng Xing (Rick)
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: It helps you prepend modules in the inheritance chain so that you can
+  easily implement your own methods to override existing ones in specific modules/classes
+  without impacting others.
+email:
+- ypxing@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/module_shims.rb
+- lib/module_shims/module_ext.rb
+- lib/module_shims/switch.rb
+- lib/module_shims/version.rb
+- module_shims.gemspec
+homepage: https://github.com/ypxing/module_shims
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Insert shims among inheritance chain for debugging/development and reading
+  source code purpose.
+test_files: []