hash-proxy 0.0.1 → 0.0.2

data/.rvmrc

@@ -1 +1 @@
-rvm gemset use hash-proxy
+rvm gemset use hash-proxy --create

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'bones'
+gem 'bones-rspec'
+gem 'bones-git'
+gem 'bones-yard'
+gem 'redcarpet'

data/Gemfile.lock

@@ -0,0 +1,40 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bones (3.8.0)
+      little-plugger (~> 1.1.3)
+      loquacious (~> 1.9.1)
+      rake (>= 0.8.7)
+    bones-git (1.3.0)
+      bones (>= 3.6)
+      git (>= 1.2.5)
+    bones-rspec (2.0.1)
+      bones (>= 3.6)
+      rspec (>= 1.3)
+    bones-yard (1.0.0)
+      yard (>= 0.5.8)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    little-plugger (1.1.3)
+    loquacious (1.9.1)
+    rake (0.9.2.2)
+    redcarpet (2.1.1)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    yard (0.8.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bones
+  bones-git
+  bones-rspec
+  bones-yard
+  redcarpet

data/History.txt

@@ -1,3 +1,6 @@
-== 0.0.1 / 2012-06-07
-
-* First release of hash-proxy
+# == Version 0.0.1 / 2012-06-07
+# * First release of hash-proxy
+# 
+# == Version 0.0.2 / 2012-06-08
+# * Convert to yard doc for "rake doc" task.
+# * Handle respond_to? in a sensible fashion.

data/README.md

@@ -8,25 +8,44 @@ Features
 --------
 
 * Treat Hash as an object
+* Lazily turns nested Hash objects into proxies as they are referenced
+* TODO: Lazily turn array elements into proxies.  Currently, if an array
+  is referenced, all of it's elements that are Hashes are turned into
+  proxies and what's worse, if the Array contains sub-arrays, all the
+  nested sub Array objects recursively have their own elements converted
+  to proxies.  This can have bad performance implications:
+
+          h = {:foo => [{:key1 => 'val1'}, {:key1 => 'val2'}, ... MANY MORE ..., {:key1 => 'val2'}]}
+          p = HashProxy.create_from(h)
+          # Even though we only look at the first two objects in the Array,
+          # we silently convert all of the Array's contained Hash objects to
+          # HashProxy::Proxy instances just by referencing the foo key.
+          p.foo[0..1]
 
 Examples
 --------
 
     require 'hash-proxy'
     hash = {foo: 'bar', baz: [{key: 'value', key2: 2, key3: [1,2,3]}, {key: 'value2', key2: 22, key3: [4,5,6]}], bip: 'bop'}
-    proxy = HashProxy::Proxy.new(hash)
-    proxy.baz.key3.should == [4,5,6]
+    proxy = HashProxy.create_from(hash)
+    proxy.baz.last.key3.should == [4,5,6]
 
 Requirements
 ------------
 
-* No dependencies
+* No runtime dependencies
+* To build and test, run bundle install after cloning from github
 
 Install
 -------
 
 * gem install hash-proxy
 
+Source
+------
+
+https://github.com/seifertd/hash-proxy
+
 Motivation
 ----------
 

data/Rakefile

@@ -2,7 +2,7 @@
 begin
   require 'bones'
 rescue LoadError
-  abort '### Please install the "bones" gem ###'
+  abort '### Please install the "bones" gem by doing a "bundle install" ###'
 end
 
 task :default => 'spec:run'
@@ -16,7 +16,12 @@ Bones {
   depend_on 'bones', :development => true
   depend_on 'bones-rspec', :development => true
   depend_on 'bones-git', :development => true
+  depend_on 'bones-yard', :development => true
+  depend_on 'redcarpet', :development => true
+
+  yard.exclude ['version.txt']
 }
 
 require 'bones/plugins/rspec'
 require 'bones/plugins/git'
+require 'bones/plugins/yard'

data/lib/hash_proxy.rb

@@ -1,4 +1,12 @@
-
+# Wrapper of Hash that allows method call semantics to hash keys and values.
+# Returns a NullObject if a key does not exist that responds to any method call.
+# Allows convenience like this
+#
+#   require 'hash_proxy'
+#   proxy = HashProxy.create_from({:foo => :bar, :baz => :bip, :stuff => {:nested => :more}})
+#   puts proxy.stuff.nested
+#   puts proxy.this.does.not.exist (to_s implemented to return empty string here)
+#
 module HashProxy
 
   # :stopdoc:
@@ -6,6 +14,12 @@ module HashProxy
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   VERSION = ::File.read(PATH + 'version.txt').strip
   # :startdoc:
+  
+  # Creates a new instance of a HashProxy::Proxy from the provided hash.
+  # Convenience factory method
+  def self.create_from(hash)
+    HashProxy::Proxy.new(hash)
+  end
 
   # Returns the library path for the module. If any arguments are given,
   # they will be joined to the end of the libray path using

data/lib/hash_proxy/null_object.rb

@@ -1,12 +1,31 @@
 module HashProxy
+  # Class representing a non-existing key in a proxied
+  # hash.  Returns self in response to any message.  Returns
+  # sensible values for various to_* methods.  But it
+  # is not 'false-y' ... ;)
   class NullObject
+    # Returns an empty array
     def to_a; []; end
+
+    # Returns an empty string
     def to_s; ""; end
+
+    # Returns 0.0
     def to_f; 0.0; end
+
+    # Returns 0
     def to_i; 0; end
+
+    # Always true
     def nil?; true; end
+
+    # Always true
     def blank?; true; end
+
+    #Always true
     def empty?; true; end
+
+    # Returns self in response to any message
     def method_missing(*args)
       self
     end

data/lib/hash_proxy/proxy.rb

@@ -1,13 +1,31 @@
 module HashProxy
+  # Class that wraps a hash and converts message sends to
+  # hash lookups and sets. If sent a message ending with '=',
+  # sets a value.  Otherwise, returns the value in the
+  # hash at the key corresponding to the message.  If the
+  # key does not exist, returns a NullObject instance.
   class Proxy
+    # The one and only NullObject instance
     NO_OBJECT = NullObject.new
+
+    # Used to check if a setter is being called
     EQUALS = '='.freeze
 
+    # Create a hashProxy::Proxy object from the provided Hash.
+    #
+    # @param [Hash] hash The hash we are proxying
+    # @option options [Boolean] :lazy (true) If true, values in the hash are converted
+    #     to hash proxies only when requested via
+    #     a method call.  If false, all nested Hash
+    #     and Array objects are converted to Proxy
+    #     objects at creation time
     def initialize(hash, options = {})
       @hash = hash
       @converted = {}
     end
 
+    # The magic.  Turns arbitrary method invocations into
+    # lookups or sets on the contained hash
     def method_missing(name, *args)
       name_str = name.to_s
       if name_str.end_with?(EQUALS)
@@ -15,10 +33,42 @@ module HashProxy
       else
         # Move the value from the original hash to the converted hash.
         # Support both symbol or string keys
-        @converted[name_str] ||= convert_value(@hash.delete(name) || @hash.delete(name_str))
+        if @converted.has_key?(name_str)
+          @converted[name_str]
+        else
+          unconverted = @hash.delete(name) || @hash.delete(name_str)
+          converted = convert_value(unconverted)
+          @converted[name_str] = converted
+        end
       end
     end
 
+    # Try to do the right thing.  Indicate that this object
+    # responds to any getter or setter method with a corresponding
+    # key in either the original or converted hash.  This can lead to 
+    # possibly confusing behavior:
+    #
+    #    p = Proxy.new(:foo => :bar)
+    #    p.respond_to?(:stuff) => false
+    #    p.stuff => NullObject
+    #    p.respond_to?(:stuff) => true
+    #
+    def respond_to?(method)
+      method_name = method.to_s
+      method_name.gsub(/=$/, '')
+      (@hash.keys.map(&:to_s) + @converted.keys.map(&:to_s)).include?(method_name) || super
+    end
+
+    # Converts an arbitrary object as follows:
+    #
+    #   1. A Proxy instance if the object is an instance of Hash
+    #   2. If the object is an array, all elements of the array
+    #      that are hashes are converted to Proxy objects.
+    #      Nested arrays are handled recursivley.
+    #   3. Non array or hash objects are left alone
+    #   4. nil is replaced by Proxy::NO_VALUE
+    #
+    # @param [Object] value The value to convert
     def convert_value(value)
       case value
       when Array

data/spec/hash_proxy_spec.rb

@@ -41,7 +41,8 @@ describe HashProxy do
   it "should not convert values if nothing is referenced" do
     hash = {'foo' => 'bar', 'arr1' => [1,2,3], 'baz' => 'bip'}
     proxy = HashProxy::Proxy.new(hash)
-    proxy.should_not_receive(:convert_value)
+    HashProxy::Proxy.should_not_receive(:convert_value)
+    proxy.to_s
   end
 
   it "should convert values if they are referenced" do
@@ -51,4 +52,27 @@ describe HashProxy do
     proxy.foo.should eq('bar')
   end
 
+  it "can be created using the factory method" do
+    hash = {foo: 'bar', baz: 'bip'}
+    proxy = HashProxy.create_from(hash)
+    proxy.foo.should eq('bar')
+  end
+
+  it "handles keys that do not exist" do
+    hash = {foo: 'bar', baz: 'bip'}
+    proxy = HashProxy.create_from(hash)
+    proxy.key.does.not.exist.to_s.should eq('')
+    proxy.key.does.not.exist.nil?.should eq(true)
+    proxy.key.does.not.exist.blank?.should eq(true)
+    proxy.key.does.not.exist.empty?.should eq(true)
+    proxy.key.does.not.exist.to_a.should eq([])
+  end
+
+  # TODO: Am I itching badly enough to make this pass? ....
+  #it "should lazily handle nested arrays" do
+  #  hash = {:foo => [{:key1 => 'val11', :key2 => 'val12'}, {:key1 => 'val21', :key2 => 'val22'}], :bar => :baz}
+  #  proxy = HashProxy.create_from(hash)
+  #  proxy.foo.should eq([{:key1 => 'val11', :key2 => 'val12'}, {:key1 => 'val21', :key2 => 'val22'}])
+  #end
+
 end

data/version.txt

@@ -1 +1 @@
-0.0.1
+0.0.2

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hash-proxy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -59,6 +59,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: bones-yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.1
 - !ruby/object:Gem::Dependency
   name: bones
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +119,8 @@ files:
 - .bnsignore
 - .gitignore
 - .rvmrc
+- Gemfile
+- Gemfile.lock
 - History.txt
 - README.md
 - Rakefile