introspection 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.md

@@ -0,0 +1,7 @@
+Dynamic inspection of the hierarchy of method definitions on a Ruby object.
+
+Motivations :-
+
+* Extract code that may be generally useful from Mocha.
+* Learn more about the Ruby's Object, Class & Module and the method receiver chain.
+* Detect undesirable changes to classes made by other libraries.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler"
+Bundler::GemHelper.install_tasks
+
+require "rake/testtask"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task :default => :test

data/introspection.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib/', __FILE__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require "introspection/version"
+
+Gem::Specification.new do |s|
+  s.name        = "introspection"
+  s.version     = Introspection::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["James Mead"]
+  s.email       = ["james@floehopper.org"]
+  s.homepage    = "http://jamesmead.org"
+  s.summary     = %q{Dynamic inspection of the hierarchy of method definitions on a Ruby object.}
+  s.description = %q{}
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.rubyforge_project = "introspection"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "metaid", "~> 1.0"
+
+  s.add_development_dependency "rake"
+end

data/lib/introspection.rb

@@ -0,0 +1,4 @@
+require "introspection/receivers"
+require "introspection/method"
+require "introspection/snapshot"
+require "introspection/assertions"

data/lib/introspection/assertions.rb

@@ -0,0 +1,17 @@
+module Introspection
+  module Assertions
+    def assert_snapshot_changed(object)
+      before = Snapshot.new(object)
+      yield
+      after = Snapshot.new(object)
+      assert before.changed?(after), "Snapshot has not changed."
+    end
+
+    def assert_snapshot_unchanged(object)
+      before = Snapshot.new(object)
+      yield
+      after = Snapshot.new(object)
+      assert !before.changed?(after), "Snapshot has changed: #{before.diff(after).inspect}"
+    end
+  end
+end

data/lib/introspection/method.rb

@@ -0,0 +1,37 @@
+require "forwardable"
+
+module Introspection
+
+  class Method
+
+    extend Forwardable
+    def_delegators :@method, :owner
+
+    attr_reader :method, :visibility
+
+    def initialize(method, visibility = :public)
+      @method, @visibility = method, visibility
+    end
+
+    def ==(other)
+      (owner == other.owner) && (name == other.name) && (visibility == other.visibility)
+    end
+
+    def eql?(other)
+      (self.class === other) && (self == other)
+    end
+
+    def hash
+      [owner, name, visibility].hash
+    end
+
+    def name
+      @method.name.to_sym
+    end
+
+    def inspect
+      "#{owner}##{name} (#{visibility})"
+    end
+  end
+
+end

data/lib/introspection/receivers.rb

@@ -0,0 +1,40 @@
+require "metaid"
+
+module Introspection
+
+  module Receivers
+
+    class NullMetaclass
+      def ancestors
+        Array.new
+      end
+    end
+
+    class NullReceiver
+      def metaclass
+        NullMetaclass.new
+      end
+
+      def receivers
+        Array.new
+      end
+    end
+
+    def superklass
+      respond_to?(:superclass) ? superclass : NullReceiver.new
+    end
+
+    def local_receivers
+      [metaclass] + metaclass.ancestors - superklass.metaclass.ancestors
+    end
+
+    def receivers
+      local_receivers + superklass.receivers
+    end
+
+  end
+end
+
+class Object
+  include Introspection::Receivers
+end

data/lib/introspection/snapshot.rb

@@ -0,0 +1,35 @@
+require "introspection/receivers"
+require "metaid"
+
+module Introspection
+
+  class Snapshot
+    attr_reader :methods
+
+    def initialize(object)
+      @methods = object.receivers.map do |receiver|
+        [:public, :protected, :private].map do |visibility|
+          query_method = "#{visibility}_instance_methods"
+          receiver.send(query_method, false).map do |method|
+            unbound_method = receiver.instance_method(method)
+            if unbound_method.owner.equal?(receiver)
+              Method.new(unbound_method, visibility)
+            end
+          end.compact
+        end
+      end.flatten
+    end
+
+    def diff(other)
+      {
+        :added => other.methods - methods,
+        :removed => methods - other.methods
+      }
+    end
+
+    def changed?(other)
+      diff(other).values.flatten.any?
+    end
+
+  end
+end

data/lib/introspection/version.rb

@@ -0,0 +1,3 @@
+module Introspection
+  VERSION = "0.0.1"
+end

data/samples/class.rb

@@ -0,0 +1,122 @@
+module Kernel
+  def foo
+    puts "Kernel#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Object
+  def foo
+    puts "Object#foo"
+    super
+  rescue NoMethodError
+  end
+  def self.foo
+    puts "Object.foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Module
+  def foo
+    puts "Module#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Class
+  def foo
+    puts "Class#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module GreatUncle
+  def foo
+    puts "GreatUncle#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module GreatAunt
+  def foo
+    puts "GreatAunt#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Grandaddy
+  def self.foo
+    puts "Grandaddy.foo"
+    super
+  rescue NoMethodError
+  end
+  extend GreatUncle, GreatAunt
+end
+
+module Uncle
+  def foo
+    puts "Uncle#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module Aunt
+  def foo
+    puts "Aunt#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Daddy < Grandaddy
+  def self.foo
+    puts "Daddy.foo"
+    super
+  rescue NoMethodError
+  end
+  extend Uncle, Aunt
+end
+
+module Brother
+  def foo
+    puts "Brother#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module HalfSister
+  def foo
+    puts "HalfSister#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module Sister
+  def foo
+    puts "Sister#foo"
+    super
+  rescue NoMethodError
+  end
+  include HalfSister
+end
+
+class Sonny < Daddy
+  def self.foo
+    puts "Sonny.foo"
+    super
+  rescue NoMethodError
+  end
+  extend Brother, Sister
+end
+
+Sonny.foo

data/samples/instance.rb

@@ -0,0 +1,110 @@
+module Kernel
+  def foo
+    puts "Kernel#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Object
+  def foo
+    puts "Object#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module GreatUncle
+  def foo
+    puts "GreatUncle#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module GreatAunt
+  def foo
+    puts "GreatAunt#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Grandaddy
+  def foo
+    puts "Grandaddy#foo"
+    super
+  rescue NoMethodError
+  end
+  include GreatUncle, GreatAunt
+end
+
+module Uncle
+  def foo
+    puts "Uncle#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module Aunt
+  def foo
+    puts "Aunt#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+class Daddy < Grandaddy
+  def foo
+    puts "Daddy#foo"
+    super
+  rescue NoMethodError
+  end
+  include Uncle, Aunt
+end
+
+module Brother
+  def foo
+    puts "Brother#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module HalfSister
+  def foo
+    puts "HalfSister#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module Sister
+  def foo
+    puts "Sister#foo"
+    super
+  rescue NoMethodError
+  end
+  include HalfSister
+end
+
+class Sonny < Daddy
+  def foo
+    puts "Sonny#foo"
+    super
+  rescue NoMethodError
+  end
+  include Brother, Sister
+end
+
+sonny = Sonny.new
+class << sonny
+  def foo
+    puts "sonny#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+sonny.foo

data/samples/module.rb

@@ -0,0 +1,27 @@
+module Grandaddy
+  def foo
+    puts "Grandaddy#foo"
+    super
+  rescue NoMethodError
+  end
+end
+
+module Daddy
+  def foo
+    puts "Daddy#foo"
+    super
+  rescue NoMethodError
+  end
+  include Grandaddy
+end
+
+module Sonny
+  def self.foo
+    puts "Sonny.foo"
+    super
+  rescue NoMethodError
+  end
+  extend Daddy
+end
+
+Sonny.foo

data/test/class_snapshot_test.rb

@@ -0,0 +1,87 @@
+require "test_helper"
+
+class ClassSnapshotTest < Test::Unit::TestCase
+
+  def test_detect_class_method_on_class
+    for_all_method_visibilities do |visibility|
+      klass = Class.new
+      klass.metaclass.send(:define_method, :foo) {}
+      klass.metaclass.send(visibility, :foo)
+      assert_method_exists(klass, klass.metaclass, :foo, visibility)
+    end
+  end
+
+  def test_detect_class_method_on_superclass
+    for_all_method_visibilities do |visibility|
+      superklass = Class.new
+      superklass.metaclass.send(:define_method, :foo) {}
+      superklass.metaclass.send(visibility, :foo)
+      klass = Class.new(superklass)
+      assert_method_exists(klass, superklass.metaclass, :foo, visibility)
+    end
+  end
+
+  def test_detect_class_method_on_superclass_of_superclass
+    for_all_method_visibilities do |visibility|
+      superduperklass = Class.new
+      superduperklass.metaclass.send(:define_method, :foo) {}
+      superduperklass.metaclass.send(visibility, :foo)
+      klass = Class.new(Class.new(superduperklass))
+      assert_method_exists(klass, superduperklass.metaclass, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_as_class_method_into_class
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      klass = Class.new do
+        extend mod
+      end
+      assert_method_exists(klass, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_as_class_method_into_superclass
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      superklass = Class.new do
+        extend mod
+      end
+      klass = Class.new(superklass)
+      assert_method_exists(klass, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_as_class_method_into_superclass_of_superclass
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      superduperklass = Class.new do
+        extend mod
+      end
+      klass = Class.new(Class.new(superduperklass))
+      assert_method_exists(klass, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_into_module_included_as_class_method_into_class
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      supermod = Module.new do
+        include mod
+      end
+      klass = Class.new do
+        extend supermod
+      end
+      assert_method_exists(klass, mod, :foo, visibility)
+    end
+  end
+
+end

data/test/instance_snapshot_test.rb

@@ -0,0 +1,122 @@
+require "test_helper"
+
+class InstanceSnapshotTest < Test::Unit::TestCase
+
+  def test_detect_instance_method_on_singleton_class
+    for_all_method_visibilities do |visibility|
+      instance = Class.new.new
+      instance.metaclass.send(:define_method, :foo) {}
+      instance.metaclass.send(visibility, :foo)
+      assert_method_exists(instance, instance.metaclass, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_into_singleton_class
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      instance = Class.new.new
+      instance.extend(mod)
+      assert_method_exists(instance, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_module_included_into_singleton_class
+    for_all_method_visibilities do |visibility|
+      supermod = Module.new
+      supermod.send(:define_method, :foo) {}
+      supermod.send(visibility, :foo)
+      mod = Module.new
+      mod.send(:include, supermod)
+      instance = Class.new.new
+      instance.extend(mod)
+      assert_method_exists(instance, supermod, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_class
+    for_all_method_visibilities do |visibility|
+      klass = Class.new
+      klass.send(:define_method, :foo) {}
+      klass.send(visibility, :foo)
+      instance = klass.new
+      assert_method_exists(instance, klass, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_superclass
+    for_all_method_visibilities do |visibility|
+      superklass = Class.new
+      superklass.send(:define_method, :foo) {}
+      superklass.send(visibility, :foo)
+      instance = Class.new(superklass).new
+      assert_method_exists(instance, superklass, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_superclass_of_superclass
+    for_all_method_visibilities do |visibility|
+      superduperklass = Class.new
+      superduperklass.send(:define_method, :foo) {}
+      superduperklass.send(visibility, :foo)
+      instance = Class.new(Class.new(superduperklass)).new
+      assert_method_exists(instance, superduperklass, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_into_class
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      instance = Class.new do
+        include mod
+      end.new
+      assert_method_exists(instance, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_into_superclass
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      superklass = Class.new do
+        include mod
+      end
+      instance = Class.new(superklass).new
+      assert_method_exists(instance, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_into_superclass_of_superclass
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      superduperklass = Class.new do
+        include mod
+      end
+      instance = Class.new(Class.new(superduperklass)).new
+      assert_method_exists(instance, mod, :foo, visibility)
+    end
+  end
+
+  def test_detect_instance_method_on_module_included_into_module_included_into_class
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.send(:define_method, :foo) {}
+      mod.send(visibility, :foo)
+      supermod = Module.new do
+        include mod
+      end
+      klass = Class.new do
+        include supermod
+      end
+      instance = klass.new
+      assert_method_exists(instance, mod, :foo, visibility)
+    end
+  end
+
+end

data/test/module_snapshot_test.rb

@@ -0,0 +1,40 @@
+require "test_helper"
+
+class ModuleSnapshotTest < Test::Unit::TestCase
+
+  def test_detect_module_method_on_module
+    for_all_method_visibilities do |visibility|
+      mod = Module.new
+      mod.metaclass.send(:define_method, :foo) {}
+      mod.metaclass.send(visibility, :foo)
+      assert_method_exists(mod, mod.metaclass, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_as_module_method_on_module
+    for_all_method_visibilities do |visibility|
+      supermod = Module.new
+      supermod.send(:define_method, :foo) {}
+      supermod.send(visibility, :foo)
+      mod = Module.new do
+        extend supermod
+      end
+      assert_method_exists(mod, supermod, :foo, visibility)
+    end
+  end
+
+  def test_detect_method_on_module_included_into_module_included_as_module_method_on_module
+    for_all_method_visibilities do |visibility|
+      superdupermod = Module.new
+      superdupermod.send(:define_method, :foo) {}
+      superdupermod.send(visibility, :foo)
+      supermod = Module.new do
+        include superdupermod
+      end
+      mod = Module.new do
+        extend supermod
+      end
+      assert_method_exists(mod, superdupermod, :foo, visibility)
+    end
+  end
+end

data/test/snapshot_test.rb

@@ -0,0 +1,50 @@
+require "test_helper"
+
+class SnapshotTest < Test::Unit::TestCase
+
+  include Introspection
+
+  def test_should_report_methods_added
+    instance = Class.new.new
+    before = Snapshot.new(instance)
+    instance.metaclass.send(:define_method, :foo) {}
+    after = Snapshot.new(instance)
+    diff = before.diff(after)
+    assert_equal 1, diff[:added].length
+    assert_equal instance.metaclass, diff[:added][0].owner
+    assert_equal :foo, diff[:added][0].name
+  end
+
+  def test_should_report_methods_removed
+    instance = Class.new.new
+    instance.metaclass.send(:define_method, :foo) {}
+    before = Snapshot.new(instance)
+    instance.metaclass.send(:remove_method, :foo)
+    after = Snapshot.new(instance)
+    diff = before.diff(after)
+    assert_equal 1, diff[:removed].length
+    assert_equal instance.metaclass, diff[:removed][0].owner
+    assert_equal :foo, diff[:removed][0].name
+  end
+
+  def test_should_indicate_snapshot_has_changed_when_method_is_added
+    instance = Class.new.new
+    assert_snapshot_changed(instance) do
+      instance.metaclass.send(:define_method, :foo) {}
+    end
+  end
+
+  def test_should_indicate_snapshot_has_changed_when_method_is_removed
+    instance = Class.new.new
+    instance.metaclass.send(:define_method, :foo) {}
+    assert_snapshot_changed(instance) do
+      instance.metaclass.send(:remove_method, :foo)
+    end
+  end
+
+  def test_should_indicate_snapshot_has_not_changed_when_method_no_methods_are_added_or_removed
+    instance = Class.new.new
+    assert_snapshot_unchanged(instance) {}
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require "rubygems"
+require "bundler/setup"
+
+require "introspection"
+require "test/unit"
+
+module Introspection
+  module TestHelper
+    def for_all_method_visibilities(&block)
+      [:public, :protected, :private].each do |visibility|
+        block.call(visibility)
+      end
+    end
+  end
+  module LocalAssertions
+    def assert_method_exists(object, owner, method_name, visibility)
+      snapshot = Snapshot.new(object)
+      method = owner.instance_method(method_name)
+      expected_method = Method.new(method, visibility)
+      methods_for_name = snapshot.methods.select { |m| m.name == method_name }
+      assert_equal [expected_method], methods_for_name
+    end
+  end
+end
+
+class Test::Unit::TestCase
+  include Introspection::TestHelper
+  include Introspection::LocalAssertions
+  include Introspection::Assertions
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: introspection
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- James Mead
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-13 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: metaid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: ""
+email: 
+- james@floehopper.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- introspection.gemspec
+- lib/introspection.rb
+- lib/introspection/assertions.rb
+- lib/introspection/method.rb
+- lib/introspection/receivers.rb
+- lib/introspection/snapshot.rb
+- lib/introspection/version.rb
+- samples/class.rb
+- samples/instance.rb
+- samples/module.rb
+- test/class_snapshot_test.rb
+- test/instance_snapshot_test.rb
+- test/module_snapshot_test.rb
+- test/snapshot_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://jamesmead.org
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: introspection
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Dynamic inspection of the hierarchy of method definitions on a Ruby object.
+test_files: 
+- test/class_snapshot_test.rb
+- test/instance_snapshot_test.rb
+- test/module_snapshot_test.rb
+- test/snapshot_test.rb
+- test/test_helper.rb