cow_proxy 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93c94796743b8e64ce62fca81e4b6cbb00d10c5e
-  data.tar.gz: 8c9097cc09c2691f13564318245dd9b09b7a580f
+  metadata.gz: ce226b279191db83c5d94fdcd974f9ff078f9aed
+  data.tar.gz: 209d901098c7203cd6c08194fe5565a432885c71
 SHA512:
-  metadata.gz: cb70d45374e3edc354755f2a39e4e7d2ece560ceb2739123f37a3ba6e54aea1931bc26585d13e3472ea389e6f0d246d5ad9ba230b7740f2d3f2472267ada8271
-  data.tar.gz: 4e87fb81c8fa67831e195f8f41b79e676c97c47f6dae5545b0f8ad129f672a76f662819d5727f4af8bda4fd70fa12831c003a96ca8b687e9fad47b337aa17e30
+  metadata.gz: 02695f8b475ab7c813d169a4eb44ae91c2a6b00ec7a0ad41f690667a2bca29b3cedb228c72e1d572a917bbfafd54ddf8080badb0770e229a956e37bb00e52789
+  data.tar.gz: 64156f469d1b130068bfdaeced1988c8daad0528ce28ced26ebc132dcb74785602faa36457632ba79bc00d7bfb6c3fef2c08007543e5909d5a31115970b88a75

data/README.md

@@ -1,11 +1,20 @@
+[![Gem
+Version](https://badge.fury.io/rb/cow_proxy.svg)](http://badge.fury.io/rb/cow_proxy)
+[![Build Status](https://secure.travis-ci.org/Programatica/cow_proxy.png?branch=master)](http://travis-ci.org/Programatica/cow_proxy)
+[![Code Climate](https://codeclimate.com/github/Programatica/cow_proxy/badges/gpa.svg)](https://codeclimate.com/github/Programatica/cow_proxy)
+[![Dependency Status](https://gemnasium.com/Programatica/cow_proxy.png?branch=master)](https://gemnasium.com/Programatica/cow_proxy)
+[![Test Coverage](https://codeclimate.com/github/Programatica/cow_proxy/badges/coverage.svg)](https://codeclimate.com/github/Programatica/cow_proxy/coverage)
+[![Inline docs](https://inch-ci.org/github/Programatica/cow_proxy.svg?branch=master)](https://inch-ci.org/github/Programatica/cow_proxy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Overview
 ========
 
 This is a copy-on-write proxy for frozen Ruby objects, so duplicating frozen object is delayed until a method tries to change frozen object.
 
-CowProxy classes for array, hash, string and struct are provided. Objects from other classes will be proxied without copy-on-write, you have to create a CowProxy class for them. Also you have to create CowProxy class for each object which have any getter method with arguments, because default CowProxy won't wrap returned value. Immutable classes such as Integer or TrueClass doesn't need copy-on-write proxy because they can't be changed.
+CowProxy classes for array, hash, string and struct are provided. Objects from other classes will be proxied without copy-on-write, you have to create a CowProxy class for them to enable copy-on-write. Also you have to create CowProxy class for each object which have any getter method with arguments, because default CowProxy won't wrap returned value. Immutable classes such as Integer or TrueClass doesn't need copy-on-write proxy because they can't be changed.
 
-You can wrap every object in a proxy. Proxy will always send method calls to wrapped object, and wrap returned value with CowProxy if method had no argument, so a proxy will always return proxy objects for getters without arguments. When a method tries to change a frozen object, if proxy has copy-on-write enabled, it will duplicate frozen object and will send next method calls to duplicated object, in other case an exception is raised.
+You can wrap every object in a proxy. Proxy will always send method calls to wrapped object, and wrap returned value with a CowProxy class if method has no argument, so a proxy will always return proxy objects for getters without arguments. When a method tries to change a frozen object, if proxy has copy-on-write enabled, it will duplicate frozen object and will send next method calls to duplicated object, in other case an exception is raised.
 
 Usage
 -----
@@ -40,7 +49,7 @@ module CowProxy
 end
 ```
 
-If your custom class has some getters with arguments, such as [] method of Array or Hash, you will have to define it in your Proxy so it wraps returned values and memoizes them, and override _copy_on_write to set memoized proxies to duplicated object. Wrapped object can be accessed from proxy with \__getobj\__ method. You can see an example in CowProxy::Container module, which is used for Array and Hash classes.
+If your custom class has some getters with arguments, such as [] method of Array or Hash, you will have to define it in your Proxy so it wraps returned values and memoizes them, and override _copy_on_write to set memoized proxies to duplicated object. Wrapped object can be accessed from proxy with \__getobj\__ method. You can see an example in CowProxy::Indexable module, which is used for Array and Hash classes.
  
 If your custom class inherits from a class with CowProxy class, you don't need to create an own class, unless you need to override some method:
  

data/lib/cow_proxy.rb

@@ -1,94 +1,90 @@
+# This module include public api for CowProxy usage
+#
+# @example Create a CowProxy class and register to be used by wrap
+#   module CowProxy
+#     class CustomClass < WrapClass(::CustomClass)
+#     end
+#   end
+#
+# @example Call CowProxy.wrap with object to be proxied
+#   obj = CustomClass.new
+#   obj.freeze
+#   proxy = CowProxy.wrap(obj)
+
 module CowProxy
   class << self
+    # @!visibility private
     @@wrapper_classes = {}
 
-    # create new proxy class for klass, with copy on write
-    # in other case CowProxy will wrap objects with class without copy on write
+    # Create new proxy class for klass, with copy on write enabled.
+    #
+    # In other case CowProxy will wrap objects of klass without copy on write
     #
-    # module CowProxy
-    #   module MyModule
-    #     class MyClass < WrapClass(::MyModule::MyClass)
+    #   module CowProxy
+    #     module MyModule
+    #       class MyClass < WrapClass(::MyModule::MyClass)
+    #       end
     #     end
     #   end
-    # end
+    #
+    # @return new proxy class, so it can be used to create a class which inherits from it
     def WrapClass(klass)
       _WrapClass(klass)
     end
 
-    # register proxy to be used when another proxy returns a value of klass,
-    # so it wraps with proxy_klass.
+    # Register proxy to be used when wrapping an object of klass.
     #
-    # called automatically when inheriting from class returned by WrapClass
+    # It's called automatically when inheriting from class returned by WrapClass
+    #
+    # @return proxy_klass
     def register_proxy(klass, proxy_klass)
-      puts "register proxy for #{klass} with #{proxy_klass} < #{proxy_klass.superclass}" if ENV['DEBUG'] && !@@wrapper_classes[klass]
+      debug "register proxy for #{klass} with #{proxy_klass} < #{proxy_klass.superclass}" unless @@wrapper_classes[klass]
       @@wrapper_classes[klass] ||= proxy_klass
     end
 
-    # return a proxy wrapping obj, using registered class for obj's class
-    # if no class is registered for obj, it uses default proxy without
+    # Returns a proxy wrapping obj, using registered class for obj's class.
+    # If no class is registered for obj's class, it uses default proxy, without
     # copy on write
+    #
+    # @return wrapped obj with CowProxy class
     def wrap(obj)
       wrapper_class(obj).new(obj)
     end
 
-    # returns proxy wrapper class for obj, registered proxy or default proxy
-    # without copy on write
+    # Returns proxy wrapper class for obj.
+    # It will return registered proxy or default proxy without copy on write
+    # if none is registered.
+    #
+    # @return registered proxy or default proxy without copy on write
+    #   if none is registered
     def wrapper_class(obj)
       # only classes with defined wrapper and Structs has COW enabled by default
       @@wrapper_classes[obj.class] || _WrapClass(obj.class, obj.class < Struct, true)
     end
 
-    protected
-    def wrapping_block(mid, cow_allowed)
-      lambda do |*args, &block|
-        target = __getobj__
-        inst_var = "@#{mid}" if mid.to_s =~ /^\w+$/
-        return _instance_variable_get(inst_var) if inst_var && _instance_variable_defined?(inst_var)
-        if mid.to_s =~ /^(\w+)=$/ && _instance_variable_defined?("@#{$1}")
-          Kernel.puts "remove #{$1}" if ENV['DEBUG']
-          _remove_instance_variable "@#{$1}"
-        end
-
-        cow = cow_allowed
-        begin
-          Kernel.puts "run on #{target.class.name} (#{target.object_id}) #{mid} #{args.inspect unless args.empty?}" if ENV['DEBUG']
-          value = target.__send__(mid, *args, &block)
-          if inst_var && args.empty? && block.nil?
-            wrap_value = wrap(value, inst_var)
-            _instance_variable_set(inst_var, wrap_value) if wrap_value
-          end
-          wrap_value || value
-        rescue => e
-          raise unless cow && e.message =~ /^can't modify frozen/
-          Kernel.puts "copy on write to run #{mid} #{args.inspect unless args.empty?} (#{e.message})" if ENV['DEBUG']
-          target = _copy_on_write
-          Kernel.puts "new target #{target.class.name} (#{target.object_id})" if ENV['DEBUG']
-          cow = false
-          retry
-        ensure
-          Kernel.puts '-----' if ENV['DEBUG']
-          # cleanup exception from cow proxy files
-          $@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
-        end
-      end
+    # Print debug line if debug is enabled (ENV['DEBUG'] true)
+    # @param [String] line debug line to print
+    # @return nil
+    def debug(line)
+      Kernel.puts line if ENV['DEBUG']
     end
 
     private
     def _WrapClass(klass, cow = true, register = false)
       proxy_superclass = get_proxy_klass_for(klass.superclass) || Base
-      Kernel.puts "create new proxy class for #{klass}#{" from #{proxy_superclass}" if proxy_superclass}" if ENV['DEBUG']
+      debug "create new proxy class for #{klass}#{" from #{proxy_superclass}" if proxy_superclass}"
       proxy_klass = Class.new(proxy_superclass) do |k|
         k.wrapped_class = klass
       end
       register_proxy klass, proxy_klass if register
       methods = klass.instance_methods
-      methods -= [:_copy_on_write, :===, :frozen?]
+      methods -= [:__copy_on_write__, :__wrap__, :__wrapped_value__, :__wrapped_method__, :__getobj__, :send, :===, :frozen?]
       methods -= proxy_superclass.wrapped_class.instance_methods if proxy_superclass.wrapped_class
       methods -= [:inspect] if ENV['DEBUG']
 
       proxy_klass.module_eval do
         methods.each do |method|
-          define_method method, CowProxy.send(:wrapping_block, method, cow)
+          define_method method, proxy_klass.wrapping_block(method, cow)
         end
       end
       proxy_klass.define_singleton_method :public_instance_methods do |all=true|
@@ -111,7 +107,7 @@ module CowProxy
 end
 
 require 'cow_proxy/base.rb'
-require 'cow_proxy/container.rb'
+require 'cow_proxy/indexable.rb'
 require 'cow_proxy/array.rb'
 require 'cow_proxy/hash.rb'
 require 'cow_proxy/string.rb'

data/lib/cow_proxy/array.rb

@@ -1,6 +1,6 @@
 module CowProxy
   class Array < WrapClass(::Array)
-    include Container
+    include Indexable
   end
 
 end

data/lib/cow_proxy/base.rb

@@ -1,25 +1,72 @@
 module CowProxy
+  # Base class to create CowProxy classes
+  #
+  # Also, it's used as default CowProxy class for non-registered classes
+  # with copy-on-write disabled, so returned values are wrapped but
+  # methods trying to change object still raise exception.
   class Base
     class << self
+      # Class which will be wrapped with this CowProxy class
       attr_accessor :wrapped_class
 
+      # Setup wrapped_class and register itself into CowProxy
+      # with {CowProxy.register_proxy CowProxy.register_proxy}
       def inherited(subclass)
         subclass.wrapped_class = wrapped_class
         CowProxy.register_proxy wrapped_class, subclass if wrapped_class
       end
+
+      protected
+      # Return block with proxy implementation.
+      #
+      # Block calls a method in wrapped object
+      #
+      # @param [Symbol] method Method name to call in wrapped object
+      # @param [Boolean] cow_enabled True if copy-on-write is enabled
+      #   for proxy class, it will _copy_on_write when method will
+      #   modify wrapped object.
+      # @return [Proc] Block with proxy implementation.
+      def wrapping_block(method, cow_enabled)
+        lambda do |*args, &block|
+          inst_var = "@#{method}" if method.to_s =~ /^\w+$/
+          return _instance_variable_get(inst_var) if inst_var && _instance_variable_defined?(inst_var)
+          if method.to_s =~ /^(\w+)=$/ && _instance_variable_defined?("@#{$1}")
+            CowProxy.debug "remove #{$1}"
+            _remove_instance_variable "@#{$1}"
+          end
+          __wrapped_method__(inst_var, cow_enabled, method, *args, &block)
+        end
+      end
     end
 
+    # Creates a CowProxy object wrapping obj
+    #
+    # @param obj An object to wrap with CowProxy class
+    # @param parent CowProxy object wrapping obj
+    # @param parent_var instance variable name in parent
+    #   which keeps this CowProxy object
     def initialize(obj, parent = nil, parent_var = nil)
       @delegate_dc_obj = obj
       @parent_proxy = parent
       @parent_var = parent_var
+      @dc_obj_duplicated = false
     end
 
-    def _copy_on_write(parent = true)
-      Kernel.puts "copy on write on #{__getobj__.class.name}" if ENV['DEBUG']
+    protected
+    # Replace wrapped object with a copy, so object can
+    # be modified.
+    #
+    # @param [Boolean] parent Replace proxy object in parent with
+    #   duplicated wrapped object, if this proxy was created from
+    #   another CowProxy.
+    # @return duplicated wrapped object
+    def __copy_on_write__(parent = true)
+      CowProxy.debug "copy on write on #{__getobj__.class.name}"
+      return @delegate_dc_obj if @dc_obj_duplicated
       @delegate_dc_obj = @delegate_dc_obj.dup.tap do |new_target|
+        @dc_obj_duplicated = true
         if parent && @parent_proxy
-          @parent_proxy._copy_on_write(false)
+          @parent_proxy.send :__copy_on_write__, false
           if @parent_var
             parent_dc = @parent_proxy._instance_variable_get(:@delegate_dc_obj)
             method = @parent_var[1..-1] + '='
@@ -30,17 +77,36 @@ module CowProxy
     end
 
     private
-    def __getobj__  # :nodoc:
+    def __getobj__
       @delegate_dc_obj
     end
 
-    def wrap(value, inst_var = nil)
+    def __wrap__(value, inst_var = nil)
       if value.frozen?
-        Kernel.puts "wrap #{value.class.name} with parent #{self.class.name}" if ENV['DEBUG']
-        CowProxy.wrapper_class(value).new(value, self, inst_var)
+        CowProxy.debug "wrap #{value.class.name} with parent #{self.class.name}"
+        wrap_value = CowProxy.wrapper_class(value).new(value, self, inst_var)
+        _instance_variable_set(inst_var, wrap_value) if inst_var
+        wrap_value
       end
     end
 
+    def __wrapped_value__(inst_var, method, *args, &block)
+      CowProxy.debug "run on #{__getobj__.class.name} (#{__getobj__.object_id}) #{method} #{args.inspect unless args.empty?}"
+      value = __getobj__.__send__(method, *args, &block)
+      wrap_value = __wrap__(value, inst_var) if inst_var && args.empty? && block.nil?
+      wrap_value || value
+    end
+
+    def __wrapped_method__(inst_var, cow, method, *args, &block)
+      __wrapped_value__(inst_var, method, *args, &block)
+    rescue => e
+      raise unless cow && e.message =~ /^can't modify frozen/
+      CowProxy.debug "copy on write to run #{method} #{args.inspect unless args.empty?} (#{e.message})"
+      __copy_on_write__
+      CowProxy.debug "new target #{__getobj__.class.name} (#{__getobj__.object_id})"
+      __wrapped_value__(inst_var, method, *args, &block)
+    end
+
     alias :_instance_variable_get :instance_variable_get
     alias :_instance_variable_set :instance_variable_set
     alias :_remove_instance_variable :remove_instance_variable

data/lib/cow_proxy/hash.rb

@@ -1,6 +1,6 @@
 module CowProxy
   class Hash < WrapClass(::Hash)
-    include Container
+    include Indexable
   end
 
 end

data/lib/cow_proxy/indexable.rb

@@ -0,0 +1,44 @@
+module CowProxy
+  # A mixin to add wrapper getter and copy-on-write for
+  # indexable classes, such as Array and Hash, i.e. classes
+  # with [] method
+  module Indexable
+    # Calls [](index) in wrapped object and keep wrapped
+    # value, so same wrapped value is return on following
+    # calls with same index.
+    #
+    # @return CowProxy wrapped value from wrapped object
+    def [](index)
+      return @hash[index] if @hash && @hash.has_key?(index)
+
+      begin
+        value = __getobj__[index]
+        return value if @hash.nil?
+        wrap_value = __wrap__(value)
+        @hash[index] = wrap_value if wrap_value
+        wrap_value || value
+      end
+    end
+
+    # Extends {CowProxy::Base#initialize}
+    def initialize(*)
+      super
+      @hash = {}
+    end
+
+    protected
+    # Copy wrapped values to duplicated wrapped object
+    # @see CowProxy::Base#__copy_on_write__
+    # @return duplicated wrapped object
+    def __copy_on_write__(*)
+      super.tap do
+        if @hash
+          @hash.each do |k, v|
+            __getobj__[k] = v
+          end
+          @hash = nil
+        end
+      end
+    end
+  end
+end

data/lib/cow_proxy/version.rb

@@ -2,7 +2,7 @@ module CowProxy
   module Version
     MAJOR = 0
     MINOR = 1
-    PATCH = 0
+    PATCH = 1
 
     STRING = [MAJOR, MINOR, PATCH].compact.join('.')
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cow_proxy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sergio Cambra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-16 00:00:00.000000000 Z
+date: 2017-03-21 00:00:00.000000000 Z
 dependencies: []
 description: Make a COW proxy for a frozen object (or deep frozen), it will delegate
   every read method to proxied object, wrap value in COW proxy if frozen. Trying to
@@ -24,8 +24,8 @@ files:
 - lib/cow_proxy.rb
 - lib/cow_proxy/array.rb
 - lib/cow_proxy/base.rb
-- lib/cow_proxy/container.rb
 - lib/cow_proxy/hash.rb
+- lib/cow_proxy/indexable.rb
 - lib/cow_proxy/set.rb
 - lib/cow_proxy/string.rb
 - lib/cow_proxy/version.rb
@@ -49,7 +49,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Copy-on-write proxy class, to use with frozen objects

data/lib/cow_proxy/container.rb

@@ -1,33 +0,0 @@
-module CowProxy
-  module Container
-    def [](index)
-      return @hash[index] if @hash && @hash.has_key?(index)
-
-      begin
-        value = __getobj__[index]
-        return value if @hash.nil?
-        wrap_value = wrap(value)
-        @hash[index] = wrap_value if wrap_value
-        wrap_value || value
-      ensure
-        $@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
-      end
-    end
-
-    def initialize(obj, *)
-      super
-      @hash = {}
-    end
-
-    def _copy_on_write(*)
-      super.tap do
-        if @hash
-          @hash.each do |k, v|
-            __getobj__[k] = v
-          end
-          @hash = nil
-        end
-      end
-    end
-  end
-end