surrogate 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1,7 @@
+rvm use ruby-1.9.3-p125
+
+root_dir="$(pwd)"
+
+alias ac="rspec '$root_dir/spec/acceptance_spec.rb'"
+alias sp="rspec $(find "$root_dir/spec" -name *_spec.rb | ruby -ne 'print unless /acceptance_spec/' | tr '\n' ' ')"
+

data/Gemfile

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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/Readme.md

@@ -0,0 +1,54 @@
+TODO
+----
+
+* substitutability
+* add methods for substitutability
+
+
+Features for future vuersions
+-----------------------------
+
+* change queue notation from will_x_qeue(1,2,3) to will_x(1,2,3)
+* arity option
+* support for raising errors
+* need some way to talk about and record blocks being passed
+* support all rspec matchers (RSpec::Mocks::ArgumentMatchers)
+* assertions for order of invocations & methods
+
+
+
+Future subset substitutability
+
+    # =====  Substitutability  =====
+
+    # real user is not a suitable substitute if missing methods that mock user has
+    user_class.should_not substitute_for Class.new
+
+    # real user must have all of mock user's methods to be substitutable
+    substitutable_real_user_class = Class.new do
+      def self.find() end
+      def initialize(id) end
+      def id() end
+      def name() end
+      def address() end
+      def phone_numbers() end
+      def add_phone_number(area_code, number) end
+    end
+    user_class.should substitute_for substitutable_real_user_class
+    user_class.should be_subset_of substitutable_real_user_class
+
+    # real user class is not a suitable substitutable if has extra methods, but is suitable subset
+    real_user_class = substitutable_real_user_class.clone
+    def real_user_class.some_class_meth() end
+    user_class.should_not substitute_for real_user_class
+    user_class.should be_subset_of real_user_class
+
+    real_user_class = substitutable_real_user_class.clone
+    real_user_class.send(:define_method, :some_instance_method) {}
+    user_class.should_not substitute_for real_user_class
+    user_class.should be_subset_of real_user_class
+
+    # subset substitutability does not work for superset
+    real_user_class = substitutable_real_user_class.clone
+    real_user_class.undef_method :address
+    user_class.should_not be_subset_of real_user_class

data/lib/surrogate/api_comparer.rb

@@ -0,0 +1,126 @@
+require 'set'
+
+class Surrogate
+
+  # compares a surrogate to an object
+  class ApiComparer
+    attr_accessor :surrogate, :actual
+
+    def initialize(surrogate, actual)
+      self.surrogate, self.actual = surrogate, actual
+    end
+
+    def surrogate_methods
+      @surrogate_methods ||= SurrogateMethods.new(surrogate).methods
+    end
+
+    def actual_methods
+      @actual_methods ||= ActualMethods.new(actual).methods
+    end
+
+    def compare
+      @compare ||= {
+        instance: {
+          not_on_surrogate: instance_not_on_surrogate,
+          not_on_actual:    instance_not_on_actual,
+        },
+        class: {
+          not_on_surrogate: class_not_on_surrogate,
+          not_on_actual:    class_not_on_actual,
+        },
+      }
+    end
+
+    def instance_not_on_surrogate
+      (actual_methods[:instance][:inherited] + actual_methods[:instance][:other]) -
+        (surrogate_methods[:instance][:inherited] + surrogate_methods[:instance][:api])
+    end
+
+    def instance_not_on_actual
+      surrogate_methods[:instance][:api] - actual_methods[:instance][:inherited] - actual_methods[:instance][:other]
+    end
+
+    def class_not_on_surrogate
+      (actual_methods[:class][:inherited] + actual_methods[:class][:other]) -
+        (surrogate_methods[:class][:inherited] + surrogate_methods[:class][:api])
+    end
+
+    def class_not_on_actual
+      surrogate_methods[:class][:api] - actual_methods[:class][:inherited] - actual_methods[:class][:other]
+    end
+
+    # methods from the actual class (as opposed to "these are actually methods"
+    class ActualMethods < Struct.new(:actual)
+      def methods
+        { instance: {
+            inherited: instance_inherited_methods,
+            other:     instance_other_methods,
+          },
+          class: {
+            inherited: class_inherited_methods,
+            other:     class_other_methods,
+          },
+        }
+      end
+
+      def instance_inherited_methods
+        Set.new actual.instance_methods - actual.instance_methods(false)
+      end
+
+      def instance_other_methods
+        Set.new(actual.instance_methods) - instance_inherited_methods
+      end
+
+      def class_inherited_methods
+        Set.new actual.singleton_class.instance_methods - actual.singleton_class.instance_methods(false)
+      end
+
+      def class_other_methods
+        Set.new(actual.singleton_class.instance_methods) - class_inherited_methods
+      end
+    end
+
+
+    class SurrogateMethods < Struct.new(:surrogate)
+      def methods
+        { instance: {
+            api:       instance_api_methods,
+            inherited: instance_inherited_methods,
+            other:     instance_other_methods,
+          },
+          class: {
+            api:       class_api_methods,
+            inherited: class_inherited_methods,
+            other:     class_other_methods,
+          },
+        }
+      end
+
+      def instance_api_methods
+        Set.new surrogate.api_method_names
+      end
+
+      def instance_inherited_methods
+        Set.new surrogate.instance_methods - surrogate.instance_methods(false)
+      end
+
+      def instance_other_methods
+        Set.new(surrogate.instance_methods false) - instance_api_methods
+      end
+
+      def class_api_methods
+        Set.new surrogate.singleton_class.api_method_names
+      end
+
+      # should have new
+      def class_inherited_methods
+        Set.new surrogate.singleton_class.instance_methods - surrogate.singleton_class.instance_methods(false) + [:new]
+      end
+
+      # should not have new
+      def class_other_methods
+        Set.new(surrogate.singleton_class.instance_methods false) - class_api_methods - class_inherited_methods
+      end
+    end
+  end
+end

data/lib/surrogate/endower.rb

@@ -0,0 +1,108 @@
+class Surrogate
+
+  # adds surrogate behaviour to your class / singleton class / instances
+  class Endower
+    def self.endow(klass, &playlist)
+      new(klass, &playlist).endow
+    end
+
+    attr_accessor :klass, :playlist
+
+    def initialize(klass, &playlist)
+      self.klass, self.playlist = klass, playlist
+    end
+
+    def endow
+      endow_klass
+      endow_singleton_class
+    end
+
+  private
+
+    def endow_klass
+      a_hatchery_for                         klass
+      enable_defining_methods                klass
+      record_initialization_for_instances_of klass
+      remember_invocations_for_instances_of  klass
+      remember_invocations_for_instances_of  klass.singleton_class
+      hijack_instantiation_of                klass
+      can_get_a_new                          klass
+    end
+
+    def endow_singleton_class
+      hatchery = a_hatchery_for singleton
+      enable_defining_methods singleton
+      singleton.module_eval &playlist if playlist
+      klass.instance_variable_set :@surrogate, Hatchling.new(klass, hatchery)
+      klass
+    end
+
+    # yeesh :( try to find a better way to do this
+    def record_initialization_for_instances_of(klass)
+      def klass.method_added(meth)
+        return unless meth == :initialize && !@hijacking_initialize
+        @hijacking_initialize = true
+        current_initialize = instance_method :initialize
+        define :initialize do |*args, &block|
+          current_initialize.bind(self).call(*args, &block)
+        end
+      ensure
+        @hijacking_initialize = false
+      end
+      initialize = klass.instance_method :initialize
+      klass.send :define_method, :initialize do |*args, &block|
+        initialize.bind(self).call(*args, &block)
+      end
+    end
+
+    def singleton
+      klass.singleton_class
+    end
+
+    def can_get_a_new(klass)
+      klass.define_singleton_method :reprise do
+        new_klass = Class.new self
+        surrogate = @surrogate
+        Surrogate.endow new_klass do
+          surrogate.api_methods.each do |method_name, options|
+            define method_name, options.to_hash, &options.default_proc
+          end
+        end
+        @hatchery.api_methods.each do |method_name, options|
+          new_klass.define method_name, options.to_hash, &options.default_proc
+        end
+        new_klass
+      end
+    end
+
+    def remember_invocations_for_instances_of(klass)
+      klass.send :define_method, :invocations do |method_name|
+        @surrogate.invocations method_name
+      end
+    end
+
+    def a_hatchery_for(klass)
+      klass.instance_variable_set :@hatchery, Surrogate::Hatchery.new(klass)
+    end
+
+    def hijack_instantiation_of(klass)
+      def klass.new(*args)
+        instance = allocate
+        hatchery = @hatchery
+        instance.instance_eval { @surrogate = Hatchling.new instance, hatchery }
+        instance.send :initialize, *args
+        instance
+      end
+    end
+
+    def enable_defining_methods(klass)
+      def klass.define(method_name, options={}, &block)
+        @hatchery.define method_name, options, block
+      end
+
+      def klass.api_method_names
+        @hatchery.api_method_names
+      end
+    end
+  end
+end

data/lib/surrogate/hatchery.rb

@@ -0,0 +1,48 @@
+class Surrogate
+  class Hatchery
+    attr_accessor :klass
+
+    def initialize(klass)
+      self.klass = klass
+      defines_methods
+    end
+
+    def defines_methods
+      klass.singleton_class.send :define_method, :define, &method(:define)
+    end
+
+    def define(method_name, options={}, block)
+      add_api_methods_for method_name
+      api_methods[method_name] = Options.new options, block
+    end
+
+    def api_methods
+      @api_methods ||= {}
+    end
+
+    def api_method_names
+      api_methods.keys - [:initialize]
+    end
+
+    # here we need to find better domain terminology
+    def add_api_methods_for(method_name)
+      klass.send :define_method, method_name do |*args, &block|
+        @surrogate.invoke_method method_name, args, &block
+      end
+
+      # verbs
+      klass.send :define_method, "will_#{method_name}" do |*args, &block|
+        if args.size == 1
+          @surrogate.prepare_method method_name, args, &block
+        else
+          @surrogate.prepare_method_queue method_name, args, &block
+        end
+        self
+      end
+
+      # nouns
+      klass.send :alias_method, "will_have_#{method_name}", "will_#{method_name}"
+    end
+  end
+end
+

data/lib/surrogate/hatchling.rb

@@ -0,0 +1,78 @@
+class Surrogate
+  UnknownMethod = Class.new StandardError
+  class Hatchling
+    attr_accessor :instance, :hatchery
+
+    def initialize(instance, hatchery)
+      self.instance, self.hatchery = instance, hatchery
+    end
+
+    def api_methods
+      hatchery.api_methods
+    end
+
+    def invoke_method(method_name, args, &block)
+      invoked_methods[method_name] << args
+      return get_default method_name, args unless has_ivar? method_name
+      ivar = get_ivar method_name
+      return ivar unless ivar.kind_of? MethodQueue
+      play_from_queue ivar, method_name
+    end
+
+    def prepare_method(method_name, args, &block)
+      set_ivar method_name, *args
+    end
+
+    def prepare_method_queue(method_name, args, &block)
+      set_ivar method_name, MethodQueue.new(args)
+    end
+
+    def invocations(method_name)
+      invoked_methods[method_name]
+    end
+
+  private
+
+    def invoked_methods
+      @invoked_methods ||= Hash.new do |hash, method_name|
+        must_know method_name
+        hash[method_name] = []
+      end
+    end
+
+    def get_default(method_name, args)
+      api_methods[method_name].default instance, args do
+        raise UnpreparedMethodError, "#{method_name} has been invoked without being told how to behave"
+      end
+    end
+
+    def play_from_queue(queue, method_name)
+      result = queue.dequeue
+      unset_ivar method_name if queue.empty?
+      result
+    end
+
+    def must_know(method_name)
+      return if api_methods.has_key? method_name
+      known_methods = api_methods.keys.map(&:to_s).map(&:inspect).join ', '
+      raise UnknownMethod, "doesn't know \"#{method_name}\", only knows #{known_methods}"
+    end
+
+    def has_ivar?(method_name)
+      instance.instance_variable_defined? "@#{method_name}"
+    end
+
+    def set_ivar(method_name, value)
+      instance.instance_variable_set "@#{method_name}", value
+    end
+
+    def get_ivar(method_name)
+      instance.instance_variable_get "@#{method_name}"
+    end
+
+    def unset_ivar(method_name)
+      instance.send :remove_instance_variable, "@#{method_name}"
+    end
+  end
+end
+

data/lib/surrogate/method_queue.rb

@@ -0,0 +1,14 @@
+class Surrogate
+  class MethodQueue < Struct.new(:queue)
+    QueueEmpty = Class.new StandardError
+
+    def dequeue
+      raise QueueEmpty if empty?
+      queue.shift
+    end
+
+    def empty?
+      queue.empty?
+    end
+  end
+end

data/lib/surrogate/options.rb

@@ -0,0 +1,28 @@
+class Surrogate
+  class Options
+    attr_accessor :options, :default_proc
+
+    def initialize(options, default_proc)
+      self.options, self.default_proc = options, default_proc
+    end
+
+    def has?(name)
+      options.has_key? name
+    end
+
+    def [](key)
+      options[key]
+    end
+
+    def to_hash
+      options
+    end
+
+    def default(instance, args, &no_default)
+      return options[:default] if options.has_key? :default
+      return instance.instance_exec(*args, &default_proc) if default_proc
+      no_default.call
+    end
+  end
+end
+