meta_instance 1.0.2 → 1.1.0

data/docs/module.md

@@ -0,0 +1,34 @@
+# Instance for Modules/Classes
+
+Modules and Classes have additional features not shared by other 
+types of objects.
+
+## Instance#method_definition
+
+    um = String.instance.method_definition(:to_s)
+    um.class.assert == UnboundMethod
+
+## Instance#definition
+
+The `#definition` method is just an alias for `#method_definition`.
+
+    um = String.instance.definition(:to_s)
+    um.class.assert == UnboundMethod
+
+## Instance#method_definitions
+
+    list = String.instance.method_definitions
+
+Method definitions can be selected use support symbol selectors.
+
+    list = String.instance.method_definitions(:public)
+    list = String.instance.method_definitions(:protected)
+    list = String.instance.method_definitions(:private)
+    list = String.instance.method_definitions(:private, :protected)
+
+## Instance#definitions
+
+The `#definitions` method is likewise an alias for `#method_definitions`.
+
+    list = String.instance.definitions
+

data/lib/meta_instance.rb

@@ -1,60 +1,39 @@
-# This is based on a few things from
-# http://reference.jumpingmonkey.org/programming_languages/ruby/ruby-metaprogramming.html
+# Instance class is a delgator for any object which provides an elegant
+# and protected interface to an object's state, i.e. its *instance*.
+# Elgence is achieved by providing a single interface, the `instance`
+# method. Protection is made possible by caching all the built-in
+# Ruby methods used to interface with an object's internal state.
+# This way they can not be overriden by some errant code or third
+# party library.
+#
+# Examples
+#
+#   class Friend
+#     attr_accessor :name, :age, :phone
+#     def initialize(name, age, phone)
+#       @name, @age, @phone = name, age, phone
+#     end
+#   end
+#
+#   f1 = Friend.new("John", 30, "555-1212")
+#   f1.instance.get(:name)  #=> "John"
+#   f1.instance.update(:name=>'Jerry')
+#   f1.instance.get(:name)  #=> "Jerry"
 #
-# allows the adding of methods to instances,
-# but not the entire set of instances for a
-# particular class
-module MetaInstance
-
-  # when a method is stubbed with snapshot data, we stare the
-  # original method prixefixed with this:
-  METHOD_BACKUP_KEY = "_mata_instance_backup_current_"
-
-  # backs up and overrides a method.
-  # but don't override if we already have overridden this method
-  def instance_override(name, &block)
-    unless respond_to?("#{METHOD_BACKUP_KEY}#{name}")
-      backup_instance_method(name)
-    end
-    instance_define(name, &block)
-  end
-
-  # Adds methods to a singletonclass
-  # define_singleton_method(name, &block) is the same as doing
-  #
-  # meta_eval {
-  #   define_method(name, &block)
-  # }
-  def instance_define(name, &block)
-    define_singleton_method(name, &block)
-  end
 
-  # backs up a method in case we want to restore it later
-  def backup_instance_method(name)
-    meta_eval {
-      alias_method "#{METHOD_BACKUP_KEY}#{name}", name
-    }
-  end
+require 'active_support'
 
-  # the original method becomes reaccessible
-  def restore_instance_method(name)
-    if respond_to?("#{METHOD_BACKUP_KEY}#{name}")
-      meta_eval {
-        alias_method name, "#{METHOD_BACKUP_KEY}#{name}"
-        remove_method "#{METHOD_BACKUP_KEY}#{name}"
-      }
-    end
-  end
+require 'meta_instance/version'
+require 'meta_instance/freeze_method'
+require 'meta_instance/module_extensions'
+require 'meta_instance/instance_method_define'
+require 'meta_instance/proxy'
 
-  private
 
-  # evals a block inside of a singleton class, aka
-  #
-  # class << self
-  #   self
-  # end
-  def meta_eval(&block)
-    singleton_class.instance_eval(&block)
+class BasicObject
+  # Returns an instance of Instance for `self`, which allows convenient
+  # access to an object's internals.
+  def instance
+    ::MetaInstance::Proxy.instance(self)
   end
-
 end

data/lib/meta_instance/freeze_method.rb

@@ -0,0 +1,13 @@
+module MetaInstance::FreezeMethod
+  extend ActiveSupport::Concern
+
+  # Store Object methods so they cannot be overriden by the delegate class.
+  METHODS = {}
+
+  module ClassMethods
+    def freeze_method(name)
+      METHODS[name.to_sym] = Module.instance_method(name)
+    end
+  end
+
+end

data/lib/meta_instance/instance_method_define.rb

@@ -0,0 +1,61 @@
+# This is based on a few things from
+# http://reference.jumpingmonkey.org/programming_languages/ruby/ruby-metaprogramming.html
+#
+# allows the adding of methods to instances,
+# but not the entire set of instances for a
+# particular class
+module MetaInstance::InstanceMethodDefine
+  extend ActiveSupport::Concern
+
+  # when a method is stubbed with snapshot data, we stare the
+  # original method prixefixed with this:
+  METHOD_BACKUP_KEY = "_mata_instance_backup_current_"
+
+  # backs up and overrides a method.
+  # but don't override if we already have overridden this method
+  def instance_override(name, &block)
+    unless respond_to?("#{METHOD_BACKUP_KEY}#{name}")
+      backup_method(name)
+    end
+    define_method(name, &block)
+  end
+
+  # Adds methods to a singletonclass
+  # define_singleton_method(name, &block) is the same as doing
+  #
+  # meta_eval {
+  #   define_method(name, &block)
+  # }
+  def define_method(name, &block)
+    define_singleton_method(name, &block)
+  end
+
+  # backs up a method in case we want to restore it later
+  def backup_method(name)
+    meta_eval {
+      alias_method "#{METHOD_BACKUP_KEY}#{name}", name
+    }
+  end
+
+  # the original method becomes reaccessible
+  def restore_method(name)
+    if respond_to?("#{METHOD_BACKUP_KEY}#{name}")
+      meta_eval {
+        alias_method name, "#{METHOD_BACKUP_KEY}#{name}"
+        remove_method "#{METHOD_BACKUP_KEY}#{name}"
+      }
+    end
+  end
+
+  private
+
+  # evals a block inside of a singleton class, aka
+  #
+  # class << self
+  #   self
+  # end
+  def meta_eval(&block)
+    singleton_class.instance_eval(&block)
+  end
+
+end

data/lib/meta_instance/module_extensions.rb

@@ -0,0 +1,61 @@
+require_relative "freeze_method"
+
+##
+# ModuleExtensions provides some additional methods for Module and Class
+# objects.
+#
+# TODO: Are there any other module/class methods that need to be provided?
+#
+module MetaInstance::ModuleExtensions
+  extend ActiveSupport::Concern
+
+  include MetaInstance::FreezeMethod
+  # Store Object methods so they cannot be overriden by the delegate class.
+
+  included do
+    freeze_method :instance_method
+    freeze_method :instance_methods
+    freeze_method :public_instance_methods
+    freeze_method :protected_instance_methods
+    freeze_method :private_instance_methods
+  end
+
+  # List of method definitions in a module or class.
+  #
+  # selection - Any of `:public`, `:protected` or `:private` which
+  #             is used to select specific subsets of methods.
+  #
+  # Returns [Array<Symbol>]
+  def method_definitions(*selection)
+    list = []
+
+    if selection.empty?
+      list.concat bind_call(:instance_methods)
+    end
+
+    selection.each do |s|
+      case s
+      when :public, :all
+        list.concat bind_call(:public_instance_methods)
+      when :protected, :all
+        list.concat bind_call(:protected_instance_methods)
+      when :private, :all
+        list.concat bind_call(:private_instance_methods)
+      end
+    end
+
+    return list
+  end
+
+  # Shorter alias for #method_definitions.
+  alias :definitions :method_definitions
+
+  # Get a first-class method definition object.
+  #
+  # Returns an unbound method object. [UnboundMethod]
+  def method_definition(name)
+    bind_call(:instance_method, name)
+  end
+
+  alias :definition :method_definition
+end

data/lib/meta_instance/proxy.rb

@@ -0,0 +1,270 @@
+# require 'forwardable'
+require 'active_support/core_ext'
+
+module MetaInstance
+  class Proxy
+    # extend Forwardable
+    include Enumerable
+    include FreezeMethod
+    include ModuleExtensions
+    include InstanceMethodDefine
+
+    freeze_method :object_id
+    freeze_method :class
+    freeze_method :instance_of?
+    freeze_method :method
+    freeze_method :methods
+    freeze_method :public_methods
+    freeze_method :protected_methods
+    freeze_method :private_methods
+    freeze_method :instance_eval
+    freeze_method :instance_exec
+    freeze_method :instance_variables
+    freeze_method :instance_variable_get
+    freeze_method :instance_variable_set
+    freeze_method :instance_variable_defined?
+    freeze_method :remove_instance_variable
+    freeze_method :send
+    freeze_method :is_a?
+    freeze_method :kind_of?
+
+    delegate :send, :class, :kind_of, :is_a?, :instance_variables, to: :@delegate
+
+
+
+    # Instance cache acts as a global cache for instances of Instance.
+    @cache = {}
+
+    # Instance is multiton. Use this method instead of #new to get a
+    # cached instance.
+    def self.instance(delegate)
+      @cache[delegate] ||= MetaInstance::Proxy.new(delegate)
+    end
+
+    # Initialize new Instance instance. If the delegate is a type of
+    # Module or Class then the instance will be extended with the
+    # {ModuleExtensions} mixin.
+    #
+    def initialize(delegate)
+      @delegate = delegate
+      extend ModuleExtensions if Module === delegate
+    end
+
+    # The delegated object.
+    def delegate
+      @delegate
+    end
+
+    # Iterate over instance variables.
+    def each
+      variables.each do |name|
+        yield(name[1..-1].to_sym, get(name))
+      end
+    end
+
+    # Number of instance variables.
+    def size
+      variables.size
+    end
+
+    # Get instance variables with values as a hash.
+    #
+    # Examples
+    #
+    #   class X
+    #     def initialize(a,b)
+    #       @a, @b = a, b
+    #     end
+    #   end
+    #
+    #   x = X.new(1,2)
+    #
+    #   x.instance.to_h  #=> { :a=>1, :b=>2 }
+    #
+    # Returns [Hash].
+    def to_h(at=false)
+      h = {}
+      if at
+        variables.each do |name|
+          h[name] = get(name)
+        end
+      else
+        each do |key, value|
+          h[key] = value
+        end
+      end
+      h
+    end
+
+    # Get instance variable's value. Will return `nil` if the
+    # variable does not exist.
+    #
+    # Returns the value of the instance variable.
+    def get(name)
+      name = atize(name)
+      delegate.instance_variable_get(name)
+    end
+    alias :[] :get
+
+    # Set instance variable.
+    #
+    # Returns the set value.
+    def set(name, value)
+      name = atize(name)
+      delegate.instance_variable_set(name, value)
+    end
+    alias :[]= :set
+
+    # Set an instance variable given a name and a value in an array pair.
+    #
+    # Example
+    #
+    #   f = Friend.new
+    #   f.instance << [:name, "John"]
+    #   f.name #=> "John"
+    #
+    # Returns the set value.
+    def <<(pair)
+      name, value = *pair
+      name = atize(name)
+      set(name, value)
+    end
+
+    # Remove instance variable.
+    def remove(name)
+      name = atize(name)
+      delegate.remove_instance_variable(name)
+    end
+
+    # Set instance variables given a +hash+.
+    #
+    #   instance.update('@a'=>1, '@b'=>2)
+    #   @a   #=> 1
+    #   @b   #=> 2
+    #
+    # Also, +@+ sign is not neccessary.
+    #
+    #   instance.update(:a=>1, :b=>2)
+    #   @a   #=> 1
+    #   @b   #=> 2
+    #
+    # Returns nothing.
+    def update(hash)
+      hash.each do |pair|
+        self << pair
+      end
+    end
+
+    # A hold-over from the the old #instance_assign method.
+    alias_method :assign, :update
+
+    # Same as #instance_variables.
+    def variables
+      delegate.instance_variables
+    end
+
+
+
+    # Instance vairable names as symbols.
+    #
+    # Returns [Array<Symbols>].
+    def keys
+      variables.collect do |name|
+        name[1..-1].to_sym
+      end
+    end
+
+    alias_method :names, :keys
+
+    # Instance variable values.
+    #
+    # Returns [Array<Object>].
+    def values
+      variables.collect do |name|
+        get(name)
+      end
+    end
+
+    # Instance evaluation.
+    def eval(*a,&b)
+      delegate.instance_eval(*a, &b)
+    end
+
+    # Instance execution.
+    def exec(*a,&b)
+      delegate.instance_exec(*a, &b)
+    end
+
+    # Get method. Usage of this might seem strange because Ruby's own
+    # `instance_method` method is a misnomer. It should be something
+    # like `definition` or `method_definition`. In Ruby the acutal
+    # "instance" method is accessed via the unadorned `method` method.
+    #
+    # Returns [Method].
+    def method(name)
+      bind_call(:method, name)
+    end
+
+    # Returns list of method names.
+    #
+    # Returns [Array<Symbol>].
+    def methods(*selection)
+      list = []
+
+      if selection.empty?
+        list.concat @delegate.methods
+      end
+
+      selection.each do |s|
+        case s
+        when :public, :all
+          list.concat @delegate.public_methods
+        when :protected, :all
+          list.concat @delegate.protected_methods
+        when :private, :all
+          list.concat @bind_call.private_methods
+        end
+      end
+
+      return list
+    end
+
+    # Is the object an instance of a given class?
+    #
+    # Returns [Boolean]
+    def of?(a_class)
+      delegate.instance_of?(a_class)
+    end
+
+
+    # Is an instaance variable defined?
+    #
+    # Returns [Boolean]
+    def variable_defined?(name)
+      name = atize(name)
+      delegate.instance_variable_defined?(name)
+    end
+
+    # Get object's instance id.
+    #
+    # Returns [Integer]
+    def id
+      delegate.object_id
+    end
+
+    # Fallback to get the real class of the Instance delegate itself.
+    alias :object_class :class
+
+    private
+
+    def atize(name)
+      name.to_s !~ /^@/ ? "@#{name}" : name
+    end
+
+    # TODO: Are there any method we need specific to a Class vs a Module?
+    #module ClassExtensions
+    #
+    #end
+
+  end
+end