gorillib 0.0.8 → 0.1.0

data/spec/hashlike/behave_same_as_hash_spec.rb

@@ -0,0 +1,105 @@
+require File.dirname(__FILE__)+'/../spec_helper'
+require 'enumerator'
+require 'gorillib/hashlike'
+
+require GORILLIB_ROOT_DIR('spec/support/hashlike_helper')
+require GORILLIB_ROOT_DIR('spec/support/hashlike_fuzzing_helper')
+require GORILLIB_ROOT_DIR('spec/support/hashlike_via_delegation')
+
+class InternalHashWithEquality < InternalHash
+  # Override these so we can compare exceptions.
+  def to_s()             @myhsh.to_s          ; end
+  def ==(other_hash)     @myhsh == other_hash ; end
+end
+
+describe Gorillib::Hashlike do
+
+  if ENV['FULL_SPECS']
+
+    include HashlikeFuzzingHelper
+
+    before do
+      @total = 0
+      @hsh      = HashlikeFuzzingHelper::HASH_TO_TEST_FULLY_HASHLIKE.dup
+      @hshlike  = InternalHashWithEquality.new.merge(HashlikeFuzzingHelper::HASH_TO_TEST_FULLY_HASHLIKE)
+    end
+
+    it 'does everything a hash can do' do
+      hsh_methods     = ({}.methods.map(&:to_sym) - HashlikeHelper::OMITTED_METHODS_FROM_HASH - HashlikeHelper::HASH_METHODS_MISSING_FROM_VERSION)
+      hshlike_methods = (@hshlike.methods.map(&:to_sym) -
+        ([:hash_eql?, :myhsh] + HashlikeHelper::HASH_METHODS_MISSING_FROM_VERSION))
+      hsh_methods.sort_by(&:to_s).should == hshlike_methods.sort_by(&:to_s)
+    end
+
+    it 'has specs for every Hash method' do
+      (@hshlike.methods.map(&:to_sym) -
+        (Object.new.methods.map(&:to_sym) +
+          HashlikeHelper::METHODS_TO_TEST +
+          HashlikeHelper::HASH_METHODS_MISSING_FROM_VERSION +
+          [:hash_eql?, :myhsh])
+        ).should == []
+    end
+
+    ( HashlikeHelper::METHODS_TO_TEST -
+      HashlikeHelper::HASH_METHODS_MISSING_FROM_VERSION
+      ).each do |method_to_test|
+      describe "##{method_to_test} same as for Hash" do
+        HashlikeFuzzingHelper::INPUTS_WHEN_FULLY_HASHLIKE.each do |input|
+
+          it "on #{input.inspect}" do
+            behaves_the_same(@hsh, @hshlike, method_to_test, input)
+          end
+        end
+      end
+    end
+
+
+    #
+    # With a few exceptions (see HASHLIKE_DEPENDENT_METHODS), all hashlike methods go through only the following core methods:
+    #
+    HASHLIKE_CONTRACT_METHODS = [:[], :[]=, :delete, :keys, :each_pair, :has_key?] + Object.public_instance_methods.map(&:to_sym)
+    #
+    # With a few exceptions, all hashlike methods go through only the core methods
+    # in HASHLIKE_CONTRACT_METHODS. The Enumerable methods go though :each, and
+    # these exceptions call a tightly-bound peer:
+    #
+    HASHLIKE_DEPENDENT_METHODS = Hash.new([]).merge({
+        :merge => [:update], :rassoc => [:key], :flatten => [:to_hash], :invert => [:to_hash],
+        :keep_if => [:select!], :delete_if => [:reject!], :select => [:select!, :keep_if], :reject => [:reject!, :delete_if],
+      })
+    Enumerable.public_instance_methods.map(&:to_sym).each{|meth| HASHLIKE_DEPENDENT_METHODS[meth] << :each }
+
+    include HashlikeFuzzingHelper
+    before do
+      @total = 0
+      @hsh   = HashlikeFuzzingHelper::HASH_TO_TEST_FULLY_HASHLIKE.dup
+    end
+
+    def nuke_most_methods_except(klass, method_to_test)
+      (klass.public_instance_methods.map(&:to_sym) -
+        (HASHLIKE_CONTRACT_METHODS + HASHLIKE_DEPENDENT_METHODS[method_to_test] + [method_to_test])).each do |method|
+        @hshlike_klass.send(:undef_method, method)
+      end
+    end
+
+    ( HashlikeHelper::METHODS_TO_TEST
+      ).each do |method_to_test|
+      describe "##{method_to_test} same as for Hash" do
+        before do
+          @hshlike_klass = Class.new(InternalHashWithEquality)
+          @hshlike = @hshlike_klass.new
+          @hshlike.merge!(HashlikeFuzzingHelper::HASH_TO_TEST_FULLY_HASHLIKE)
+          nuke_most_methods_except(@hshlike_klass, method_to_test)
+        end
+        HashlikeFuzzingHelper::INPUTS_WHEN_FULLY_HASHLIKE.each do |input|
+          it "on #{input.inspect}" do
+            behaves_the_same(@hsh, @hshlike, method_to_test, input)
+          end
+        end
+      end
+    end
+
+  else
+    it 'skipping full specs -- set environment variable FULL_SPECS=true to run all specs'
+  end
+end

data/spec/hashlike/hashlike_behavior_spec.rb

@@ -0,0 +1,824 @@
+unless defined?(HASHLIKE_BEHAVIOR_SPEC)
+describe '' do
+
+  # ===========================================================================
+  #
+  # Fundamental behavior
+
+  shared_examples_for :hashlike_store_and_retrieve do
+    it 'stores and retrieves values' do
+      @hshlike[:a].should == 100
+      @hshlike[:a] = 999
+      @hshlike[:a].should == 999
+    end
+
+    it 'returns nil on a missing (but valid) key' do
+      @hshlike[:new_key].should == nil
+    end    
+  end
+
+  shared_examples_for :references_string_and_symbol_keys_equivalently do
+    it 'treats string and symbol keys as the same thing' do
+      @hshlike['c'].should == 300
+      @hshlike[:c].should  == 300
+      @hshlike['c'] = 999
+      @hshlike['c'].should == 999
+      @hshlike[:c].should  == 999
+      @hshlike.delete('c').should == 999
+      @hshlike['c'].should be_nil
+      @hshlike[:c].should  be_nil
+    end
+  end
+
+  shared_examples_for :references_complex_keys do
+    it 'treats string and symbol keys as distinct' do
+      @hshlike['c'].should be_nil
+      @hshlike[:c].should  == 300
+      @hshlike['c'] = 999
+      @hshlike['c'].should == 999
+      @hshlike[:c].should  == 300
+      @hshlike.delete('c').should == 999
+      @hshlike['c'].should be_nil
+      @hshlike[:c].should  == 300
+    end
+
+    it 'allows nil, Object, and other non-stringy keys' do
+      @hshlike[300] = :i_haz_num ; @hshlike[300].should == :i_haz_num; @hshlike.delete(300).should == :i_haz_num
+      @hshlike[nil] = :i_haz_nil ; @hshlike[nil].should == :i_haz_nil; @hshlike.delete(nil).should == :i_haz_nil
+      obj = Object.new
+      @hshlike[obj] = :i_haz_obj ; @hshlike[obj].should == :i_haz_obj; @hshlike.delete(obj).should == :i_haz_obj
+      @hshlike.should be_hash_eql(HashlikeHelper::BASE_HSH)
+    end    
+  end
+
+  shared_examples_for :accepts_arbitrary_keys do
+    it 'never-seen keys' do
+      @hshlike[:fnord] = 69
+      @hshlike[:fnord].should == 69
+      @hshlike.delete(:fnord).should == 69
+      @hshlike[:boink].should be_nil     
+    end
+  end
+
+  shared_examples_for :hashlike_delete do
+    it 'removes the key/value association and returns the value' do
+      @hshlike.delete(:a).should == 100
+      @hshlike.delete(:is_missing).should be_nil
+      @hshlike.delete(:false_val).should == false
+      @hshlike.should be_hash_eql({ :b  => 200, :c => 300, :nil_val => nil })
+    end
+    describe 'with optional code block' do
+      it 'returns the value of executing the block (passing in the key)' do
+        set_in_block = nil
+        ret_val = @hshlike.delete(:is_missing){|k| set_in_block = "got: #{k}" ; "hello!" }
+        set_in_block.should == "got: is_missing"
+        ret_val.should == "hello!"
+      end
+    end
+    it 'does not include? key after deleting' do
+      @hshlike.should include(:a)
+      @hshlike.delete(:a)
+      @hshlike.should_not include(:a)
+      @hshlike[:a].should be_nil
+    end
+  end
+
+  shared_examples_for :hashlike_keys do
+    it 'lists keys, even where values are nil' do
+      @hshlike.keys.should be_array_eql([:a, :b, :c, :nil_val, :false_val])
+      @hshlike[:nil_val].should be_nil
+    end
+    it 'is an empty array when there are no keys' do
+      @empty_hshlike.keys.should == []
+    end
+    it 'setting an association creates a new key' do
+      @hshlike[:new_key] = 3
+      @hshlike.keys.should be_array_eql([:a, :b, :c, :nil_val, :false_val, :new_key])
+    end
+  end
+
+  # ===========================================================================
+  #
+  # Iteration
+  
+  shared_examples_for :with_no_block_returns_enumerator do |method_to_test|
+    it('returns an enumerator'){ @hshlike.send(method_to_test).should enumerate_method(@hshlike, method_to_test) }
+  end
+
+  shared_examples_for :each_pair_on_stringlike_keys do |method_to_test|
+    it 'calls block once for each key/value pair in hsh' do
+      seen_arg1 = []
+      seen_arg2 = []
+      @hshlike.send(method_to_test){|arg1,arg2| seen_arg1 << arg1 ; seen_arg2 << arg2 }
+      seen_arg1.should be_array_eql([:a,  :b,  :c, :nil_val, :false_val ])
+      seen_arg2.should be_array_eql([100, 200, 300, nil,      false      ])
+    end
+    it 'with arity 1, returns arrays' do
+      seen_args = []
+      @hshlike.send(method_to_test){|arg| seen_args << arg }
+      seen_args.should be_array_eql([[:a, 100], [:b, 200], [:c, 300], [:nil_val, nil], [:false_val, false]])
+    end
+    it 'handles array vals' do
+      seen_args = []
+      @hshlike_with_array_vals.send(method_to_test){|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, [100, 111], nil], [:b, 200, nil], [:c, [1, [2, 3, [4, 5, 6]]], nil]])
+      seen_args = []
+      @hshlike_with_array_vals.send(method_to_test){|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, [100, 111]], [:b, nil, 200], [:c, nil, [1, [2, 3, [4, 5, 6]]]]])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.send(method_to_test){|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  #
+  # For a struct, the keys exist eternally, so even an unset key/value pair is iterated
+  #
+  shared_examples_for :each_pair_on_stringlike_fixed_keys do |method_to_test|
+    it 'calls block once for each key/value pair in hsh' do
+      seen_arg1 = []
+      seen_arg2 = []
+      @hshlike.send(method_to_test){|arg1,arg2| seen_arg1 << arg1 ; seen_arg2 << arg2 }
+      seen_arg1.should be_array_eql([:a,  :b,  :c, :nil_val, :false_val, :new_key ])
+      seen_arg2.should be_array_eql([100, 200, 300, nil,      false,      nil      ])
+    end
+    it 'with arity 1, returns array pairs' do
+      seen_args = []
+      @hshlike.send(method_to_test){|arg| seen_args << arg }
+      # seen_args.should be_array_eql([[:a, 100], [:b, 200], [:c, 300], [:nil_val, nil], [:false_val, false], [:new_key, nil]])
+      seen_args.should be_array_eql([:a, :b, :c, :nil_val, :false_val, :new_key])
+    end
+    it 'handles array vals' do
+      seen_args = []
+      @hshlike_with_array_vals.send(method_to_test){|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, [100, 111], nil], [:b, 200, nil], [:c, [1, [2, 3, [4, 5, 6]]], nil], [:nil_val, nil, nil], [:false_val, nil, nil], [:new_key, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_vals.send(method_to_test){|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, [100, 111]], [:b, nil, 200], [:c, nil, [1, [2, 3, [4, 5, 6]]]], [:nil_val, nil, nil], [:false_val, nil, nil], [:new_key, nil, nil]])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.send(method_to_test){|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  shared_examples_for :each_key_on_stringlike_keys do 
+    it 'calls block once for each key in hsh' do
+      seen_keys = []
+      @hshlike.each_key{|k| seen_keys << k }
+      seen_keys.should be_array_eql([:a,  :b,  :c, :nil_val, :false_val ])
+    end
+    it 'handles array vals and extra arity' do
+      seen_args = []
+      @hshlike.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil], [:nil_val, nil, nil], [:false_val, nil, nil] ])
+      seen_args = []
+      @hshlike_with_array_vals.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil] ])
+      seen_args = []
+      @hshlike_with_array_vals.each_key{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil] ])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.each_key{|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  #
+  # For a struct, the keys exist eternally, so even an unset key/value pair is iterated
+  #
+  shared_examples_for :each_key_on_stringlike_fixed_keys do |method_to_test|
+    it 'calls block once for each key in hsh' do
+      seen_keys = []
+      @hshlike.each_key{|k| seen_keys << k }
+      seen_keys.should be_array_eql([:a,  :b,  :c, :nil_val, :false_val, :new_key ])
+    end
+    it 'handles array keys and extra arity' do
+      seen_args = []
+      @hshlike.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil], [:nil_val, nil, nil], [:false_val, nil, nil], [:new_key, nil, nil] ])
+      seen_args = []
+      @hshlike_with_array_vals.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil], [:nil_val, nil, nil], [:false_val, nil, nil], [:new_key, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_vals.each_key{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil], [:nil_val, nil, nil], [:false_val, nil, nil], [:new_key, nil, nil]])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.each_key{|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  shared_examples_for :each_value_on_stringlike_keys do
+    it 'calls block once for each key in hsh, passing the value as parameter' do
+      seen_vals = []
+      @hshlike.each_value{|k| seen_vals << k }
+      seen_vals.should be_array_eql([100, 200, 300, nil, false])
+    end
+    it 'calls block on each value even when nil, false, empty or duplicate' do
+      @hshlike[:a]       = 999
+      @hshlike[:new_key] = 999
+      seen_vals = []
+      @hshlike.each_value{|k| seen_vals << k }
+      seen_vals.should be_array_eql([999, 200, 300, nil, false, 999])
+    end
+    it 'handles array vals and extra arity' do
+      seen_args = []
+      @hshlike.each_value{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, nil, nil], [200, nil, nil], [300, nil, nil], [nil, nil, nil], [false, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_vals.each_value{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, 111, nil], [200, nil, nil], [1, [2, 3, [4, 5, 6]], nil]])
+      seen_args = []
+      @hshlike_with_array_vals.each_value{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, nil, 111], [200, nil, nil], [1, nil, [2, 3, [4, 5, 6]]]])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.each_value{|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  #
+  # For a struct, the keys exist eternally, so even an unset key/value pair is iterated
+  #
+  shared_examples_for :each_value_on_stringlike_fixed_keys do
+    it 'calls block once for each key in hsh, passing the value as parameter' do
+      seen_vals = []
+      @hshlike.each_value{|k| seen_vals << k }
+      seen_vals.should be_array_eql([100, 200, 300, nil, false, nil])
+    end
+    it 'calls block on each value even when nil, false, empty or duplicate' do
+      @hshlike[:a]       = 999
+      @hshlike[:new_key] = 999
+      seen_vals = []
+      @hshlike.each_value{|k| seen_vals << k }
+      seen_vals.should be_array_eql([999, 200, 300, nil, false, 999 ])
+    end
+    it 'handles array vals and extra arity' do
+      seen_args = []
+      @hshlike.each_value{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, nil, nil], [200, nil, nil], [300, nil, nil], [nil, nil, nil], [false, nil, nil], [nil, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_vals.each_value{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, 111, nil], [200, nil, nil], [1, [2, 3, [4, 5, 6]], nil], [nil, nil, nil], [nil, nil, nil], [nil, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_vals.each_value{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[100, nil, 111], [200, nil, nil], [1, nil, [2, 3, [4, 5, 6]]], [nil, nil, nil], [nil, nil, nil], [nil, nil, nil]])
+    end
+    it 'returns self' do
+      ret_val = @hshlike.each_value{|k,v| 3 }
+      ret_val.should equal(@hshlike)
+    end
+  end
+
+  shared_examples_for :each_pair_on_complex_keys do |method_to_test|
+    it 'handles array keys' do
+      seen_args = []
+      @hshlike_with_array_keys.each_pair{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[[:a, :aa], 100, nil], [:b, 200, nil], [[:c, :cc], [300, 333], nil], [[1, 2, [3, 4]], [1, [2, 3, [4, 5, 6]]], nil]])
+      seen_args = []
+      @hshlike_with_array_keys.each_pair{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, :aa, 100], [:b, nil, 200], [:c, :cc, [300, 333]], [1, 2, [1, [2, 3, [4, 5, 6]]]]])
+    end
+  end
+
+  shared_examples_for :each_key_on_complex_keys do
+    it 'handles array keys and extra arity' do
+      seen_args = []
+      @hshlike.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, nil], [:b, nil, nil], [:c, nil, nil], [:nil_val, nil, nil], [:false_val, nil, nil]])
+      seen_args = []
+      @hshlike_with_array_keys.each_key{|arg1, arg2, arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, :aa, nil], [:b, nil, nil], [:c, :cc, nil], [1, 2, [3, 4]]])
+      seen_args = []
+      @hshlike_with_array_keys.each_key{|(arg1, arg2), arg3| seen_args << [arg1, arg2, arg3] }
+      seen_args.should be_array_eql([[:a, nil, :aa], [:b, nil, nil], [:c, nil, :cc], [1, nil, 2]])
+    end
+  end
+  
+  # ===========================================================================
+  #
+  # Retrieval and Membership
+
+  shared_examples_for :hashlike_values do
+    it 'returns a new array populated with the values from hsh' do
+      @hshlike.values.should be_array_eql([100, 200, 300, nil, false])
+    end    
+  end
+
+  shared_examples_for :hashlike_values_at_or_of do |method_to_test|
+    it 'returns an array containing the values associated with the given keys' do
+      @hshlike.send(method_to_test, :b, :a, :z, :nil_val).should == [200, 100, nil, nil]
+    end
+    it 'returns duplicate keys or missing keys in given slot' do
+      @hshlike.send(method_to_test, :b, :b, :i_am_missing, :nil_val, :c, '300').should == [200, 200, nil, nil, 300, nil]
+    end
+  end
+
+  shared_examples_for :hashlike_length do |method_to_test|
+    it 'returns the number of key/value pairs in the hashlike' do
+      @hshlike.send(method_to_test).should == 5
+      @hshlike[:new_key] = 69
+      @hshlike.send(method_to_test).should == 6
+      @hshlike.delete(:a)
+      @hshlike.delete(:b)
+      @hshlike.send(method_to_test).should == 4
+    end
+    it 'is zero for an empty hashlike' do
+      @empty_hshlike.send(method_to_test).should == 0
+    end    
+  end
+
+  shared_examples_for :hashlike_has_key? do |method_to_test|
+    it 'returns true if the given key is present' do
+      @hshlike.send(method_to_test, :a).should == true
+    end
+    it 'returns false if the key is absent, whether pre-defined or not' do
+      @hshlike.send(method_to_test, :new_key).should == false
+      @hshlike[:new_key] = nil
+      @hshlike.send(method_to_test, :new_key).should == true
+      @hshlike.send(method_to_test, :fnord).should == false
+    end
+    it 'is true even if value is nil, empty or false' do
+      @hshlike.should evaluate_to_true(method_to_test, :nil_val)
+      @hshlike.should evaluate_to_true(method_to_test, :false_val)
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :hashlike_has_key_predefined_always_present do |method_to_test|
+    it 'returns true if the given key is present' do
+      @hshlike.send(method_to_test, :a).should == true
+    end
+    it 'returns false if the key is absent, whether pre-defined or not' do
+      @hshlike.send(method_to_test, :new_key).should == true
+      @hshlike[:new_key] = nil
+      @hshlike.send(method_to_test, :new_key).should == true
+      @hshlike.send(method_to_test, :fnord).should == false
+    end
+    it 'is true even if value is nil, empty or false' do
+      @hshlike.should evaluate_to_true(method_to_test, :nil_val)
+      @hshlike.should evaluate_to_true(method_to_test, :false_val)
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :hashlike_has_key_string_and_symbol_equivalent do |method_to_test|
+    it 'treats symbol and string keys as equivalent' do
+      @hshlike.send(method_to_test, :a).should  == true
+      @hshlike.send(method_to_test, 'a').should == true
+      @hshlike.send(method_to_test, :c).should  == true
+      @hshlike.send(method_to_test, 'c').should == true
+    end
+  end
+
+  shared_examples_for :hashlike_has_key_on_complex_keys do |method_to_test|
+    it 'treats symbol and string keys as equivalent' do
+      @hshlike.send(method_to_test, :a).should  == true
+      @hshlike.send(method_to_test, 'a').should == false
+      @hshlike.send(method_to_test, :c).should  == true
+      @hshlike.send(method_to_test, 'c').should == false
+      @hshlike.send(method_to_test, nil).should == false
+      @hshlike[nil] = 1
+      @hshlike.send(method_to_test, nil).should == true
+      obj = Object.new
+      @hshlike.send(method_to_test, obj).should == false
+      @hshlike[obj] = 1
+      @hshlike.send(method_to_test, obj).should == true
+    end
+  end
+
+  shared_examples_for :hashlike_has_value? do |method_to_test|
+    it 'returns true if the given value is present' do
+      @hshlike.send(method_to_test, 100).should == true
+    end
+    it 'returns false if the value is absent' do
+      @hshlike.send(method_to_test, :i_am_missing).should == false
+    end
+    it 'returns true if the given value is present-but-nil or present-but-false' do
+      @hshlike[:false_val].should == false
+      @hshlike[:nil_val].should   == nil
+      @hshlike.send(method_to_test, false).should == true
+      @hshlike.send(method_to_test, nil).should   == true
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :hashlike_has_value_on_complex_keys do |method_to_test|
+    it 'is true even if key or value is nil, empty or false values' do
+      @hshlike[nil]   = :key_is_nil
+      @hshlike[false] = :key_is_false
+      @hshlike.should be_hash_eql({:a=>100, :b=>200, :c=>300, :nil_val=>nil, :false_val=>false, nil=>:key_is_nil, false=>:key_is_false})
+      @hshlike.should evaluate_to_true(method_to_test, nil)
+      @hshlike.should evaluate_to_true(method_to_test, false)
+      @hshlike.should evaluate_to_true(method_to_test, :key_is_nil)
+      @hshlike.should evaluate_to_true(method_to_test, :key_is_false)
+    end
+  end
+
+  shared_examples_for :hashlike_fetch do
+    it 'returns a value from the hashlike for the given key' do
+      @hshlike.fetch(:a).should       == 100
+      @hshlike.fetch(:c).should       == 300
+      @hshlike.fetch(:nil_val).should == nil
+    end
+    describe 'on a missing key' do
+      it 'with no other arguments, raises a +KeyError+ exception' do
+        lambda{ @hshlike.fetch(:new_key) }.should raise_error(KeyError, 'key not found: :new_key')
+      end
+      it 'if block given, runs the block with the given key and returns its value' do
+        set_in_block = nil
+        ret_val = @hshlike.fetch(:new_key){|k| set_in_block = "got: #{k}" ; "hello!" }
+        ret_val.should      == "hello!"
+        set_in_block.should == "got: new_key"
+      end
+      it 'if default given, returns the default arg' do
+        ret_val = @hshlike.fetch(:new_key, :returned_as_default)
+        ret_val.should      == :returned_as_default
+      end
+      it 'if block and default are both given, issues a warning and runs the block' do
+        set_in_block = nil
+        ret_val = @hshlike.fetch(:new_key, :spurious_default){|k| set_in_block = "got: #{k}" ; "hello!" }
+        ret_val.should      == "hello!"
+        set_in_block.should == "got: new_key"
+      end
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :hashlike_key do
+    it 'searches for an entry with the given val, returning the corresponding key; if not found, returns nil' do
+      @hshlike.key(100).should == :a
+      @hshlike.key(300).should == :c
+      @hshlike.key(nil).should == :nil_val
+      @hshlike.key(:i_am_missing).should be_nil
+    end
+    it 'returns the first matching key/value pair' do
+      @hshlike[:a]       = 999
+      @hshlike[:new_key] = 999
+      if (RUBY_VERSION >= '1.9')
+        @hshlike.key(999).should == :a
+      end
+    end    
+  end
+
+  shared_examples_for :hashlike_assoc do
+    it 'searches for an entry with the given key, returning the corresponding key/value pair' do
+      @hshlike.assoc(:a).should       == [:a,  100]
+      @hshlike.assoc(:nil_val).should == [:nil_val, nil]
+    end
+    it 'returns nil if missing' do
+      @hshlike.assoc(:i_am_missing).should be_nil
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :hashlike_rassoc do
+    it 'searches for an entry with the given val, returning the corresponding key/value pair' do
+      @hshlike.rassoc(100).should == [:a,  100]
+      @hshlike.rassoc(300).should == [:c,  300]
+      @hshlike.rassoc(nil).should == [:nil_val, nil]
+    end
+    it 'returns nil if missing' do
+      @hshlike.rassoc(:i_am_missing).should be_nil
+    end    
+  end
+
+  shared_examples_for :hashlike_empty? do
+    it 'returns true if the hashlike contains no key-value pairs, false otherwise' do
+      @hshlike.empty?.should       == false
+      @empty_hshlike.empty?.should == true
+      @empty_hshlike[:a] = nil
+      @empty_hshlike.empty?.should == false
+    end
+  end
+  
+  # ===========================================================================
+  #
+  # Update, merge!, merge
+
+  shared_examples_for :merging_method do |method_to_test|
+    it 'adds the contents of another hash' do
+      ret_val = @hshlike.send(method_to_test, {:a => [], :new_key => "zzz" })
+      ret_val.should   be_hash_eql({:a=>[], :b=>200, :c=>300, :nil_val=>nil, :false_val=>false, :new_key => "zzz"})
+    end
+    it 'adds the contents of a Struct' do
+      bob_klass = Struct.new(:a, :b, :nil_val, :new_key)
+      bob = bob_klass.new("aaa", 200, "here", "zzz")
+      ret_val = @hshlike.send(method_to_test, bob)
+      ret_val.should   be_hash_eql({ :a => "aaa", :b => 200, :c => 300, :nil_val => "here", :false_val => false, :new_key => "zzz" })
+      bob.values.should == ["aaa", 200, "here", "zzz"]
+    end
+    it 'adds the contents of another Hashlike' do
+      bob = InternalHash.new.merge({ :a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+      ret_val = @hshlike.send(method_to_test, bob)
+      ret_val.should   be_hash_eql({ :a => "aaa", :b => 200, :c => 300, :nil_val => "here", :false_val => false, :new_key => "zzz" })
+      bob.should       be_hash_eql({ :a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+    end
+    it 'adds the contents of anything that respond_to?(:each_pair)' do
+      obj = Object.new
+      def obj.each_pair
+        [[:a, "aaa"], [:b, 200], [:nil_val, "here"], [:new_key, "zzz"]].each{|k,v| yield(k,v) }
+      end
+      ret_val = @hshlike.send(method_to_test, obj)
+      ret_val.should   be_hash_eql({ :a => "aaa", :b => 200, :c => 300, :nil_val => "here", :false_val => false, :new_key => "zzz" })
+    end
+    describe 'with no block' do
+      it 'overwrites entries in this hash with those from the other hash' do
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+        ret_val.should be_hash_eql({ :a => "aaa", :b => 200, :c => 300, :nil_val => "here", :false_val => false, :new_key => "zzz" })
+      end
+    end
+    it 'raises a type error unless given hash responds to each_pair' do
+      obj = Object.new
+      lambda{ @hshlike.send(method_to_test, obj) }.should raise_error(TypeError, "can't convert Object into Hash")
+    end
+    it 'something something convert_key'
+  end
+
+  shared_examples_for :merging_method_with_normal_keys do |method_to_test|
+    describe 'with a block' do
+      it 'sets the value for colliding keys by evaluating the block' do
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :nil_val => "here", :new_key => "zzz" }) do |key, other_val, hsh_val|
+          "key: '#{key.inspect}', other_val: '#{other_val.inspect}', hsh_val: '#{hsh_val.inspect}'"
+        end
+        ret_val.should be_hash_eql({
+            :a         => %Q{key: ':a', other_val: '"aaa"', hsh_val: '100'},
+            :b         => 200,
+            :c        => 300,
+            :nil_val   => %Q{key: ':nil_val', other_val: '"here"', hsh_val: 'nil'},
+            :false_val => false,
+            :new_key   => "zzz",
+          })
+      end
+      it 'passes params |key, current val, other hash val|' do
+        seen_args = []
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :nil_val => "here", :new_key => "zzz" }) do |key, other_val, hsh_val|
+          seen_args << [key, other_val, hsh_val]
+          3
+        end
+        ret_val.should be_hash_eql({ :a => 3, :b => 200, :c => 300, :nil_val => 3, :false_val => false, :new_key => "zzz" })
+        seen_args.should be_array_eql([ [:a, "aaa", 100], [:nil_val, "here", nil] ])
+      end
+      it 'calls the block even if colliding keys have same value' do
+        seen_args = []
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :b => 200, :new_key => "zzz" }) do |key, other_val, hsh_val|
+          seen_args << [key, other_val, hsh_val]
+          3
+        end
+        ret_val.should be_hash_eql({ :a => 3, :b => 3, :c => 300, :nil_val => nil, :false_val => false, :new_key => "zzz" })
+        seen_args.should be_array_eql([ [:a, "aaa", 100], [:b, 200, 200] ])
+      end
+    end
+  end
+
+  shared_examples_for :merging_method_with_struct_keys do |method_to_test|
+    describe 'with a block' do
+      it 'sets the value for colliding keys by evaluating the block' do
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :nil_val => "here", :new_key => "zzz" }) do |key, other_val, hsh_val|
+          "key: '#{key.inspect}', other_val: '#{other_val.inspect}', hsh_val: '#{hsh_val.inspect}'"
+        end
+        ret_val.should be_hash_eql({
+            :a         => %Q{key: ':a', other_val: '"aaa"', hsh_val: '100'},
+            :b         => 200,
+            :c         => 300,
+            :nil_val   => %Q{key: ':nil_val', other_val: '"here"', hsh_val: 'nil'},
+            :false_val => false,
+            :new_key   => %Q{key: ':new_key', other_val: '"zzz"', hsh_val: 'nil'},
+          })
+      end
+      it 'passes params |key, current val, other hash val|' do
+        seen_args = []
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :nil_val => "here", :new_key => "zzz" }) do |key, other_val, hsh_val|
+          seen_args << [key, other_val, hsh_val]
+          3
+        end
+        ret_val.should be_hash_eql({ :a => 3, :b => 200, :c => 300, :nil_val => 3, :false_val => false, :new_key => 3 })
+        seen_args.should be_array_eql([ [:a, "aaa", 100], [:nil_val, "here", nil], [:new_key, "zzz", nil] ])
+      end
+      it 'calls the block even if colliding keys have same value' do
+        seen_args = []
+        ret_val = @hshlike.send(method_to_test, {:a => "aaa", :b => 200, :new_key => "zzz" }) do |key, other_val, hsh_val|
+          seen_args << [key, other_val, hsh_val]
+          3
+        end
+        ret_val.should be_hash_eql({ :a => 3, :b => 3, :c => 300, :nil_val => nil, :false_val => false, :new_key => 3 })
+        seen_args.should be_array_eql([ [:a, "aaa", 100], [:b, 200, 200], [:new_key, "zzz", nil] ])
+      end
+    end
+  end
+
+  shared_examples_for :merging_method_inplace do |method_to_test|
+    it 'updates in-place, returning self' do
+      ret_val = @hshlike.send(method_to_test, {:a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+      ret_val.should equal(@hshlike)
+      @hshlike.should be_hash_eql({:a=>"aaa", :b=>200, :c=>300, :nil_val=>"here", :false_val=>false, :new_key=>"zzz"})
+    end    
+  end
+
+  shared_examples_for :merging_method_returning_new do |method_to_test|
+    it 'does not alter state, returning a new object' do
+      ret_val = @hshlike.send(method_to_test, {:a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+      ret_val.should_not equal(@hshlike)
+      @hshlike.should be_hash_eql({:a=>100,   :b=>200, :c=>300, :nil_val=>nil,    :false_val=>false })
+      ret_val.should  be_hash_eql({:a=>"aaa", :b=>200, :c=>300, :nil_val=>"here", :false_val=>false, :new_key=>"zzz"})
+    end
+    it 'returns an object of same class' do
+      ret_val = @hshlike_subklass_inst.send(method_to_test, {:a => "aaa", :b => 200, :nil_val => "here", :new_key => "zzz" })
+      ret_val.should be_a(@hshlike_subklass)
+    end
+  end
+
+  # ===========================================================================
+  #
+  # Filters
+
+  shared_examples_for :hashlike_filter do |method_to_test|
+    it 'passes every key-value pair to block' do
+      seen_args = []
+      ret_val = @hshlike.send(method_to_test){|key,val| seen_args << [key, val] ; val && (val.to_i > 150) }
+      #
+      seen_args.should be_array_eql([[:a, 100], [:b, 200], [:c, 300], [:nil_val, nil], [:false_val, false]])
+    end
+    it 'adapts to the arity of the block' do
+      seen_args = []
+      ret_val = @hshlike.send(method_to_test){|arg| seen_args << [arg] ; @hshlike[arg] && (@hshlike[arg].to_i > 150) }
+      #
+      seen_args.should be_array_eql([[:a], [:b], [:c], [:nil_val], [:false_val]])
+    end
+    describe 'with no block' do
+      it('returns an enumerator'){ @hshlike.send(method_to_test).should enumerate_method(@hshlike, method_to_test) }
+    end
+  end
+
+  shared_examples_for :rejection_filter do |method_to_test|
+    it 'deletes every key-value pair for which the block evaluates truthy' do
+      ret_val = @hshlike.send(method_to_test){|key,val| val && (val.to_i > 150) }
+      ret_val.should be_hash_eql({ :a => 100, :nil_val => nil, :false_val => false })
+      @hshlike.should be_hash_eql({ :a => 100, :nil_val => nil, :false_val => false })
+      #
+      ret_val = @hshlike.send(method_to_test){|key,val| 1 }
+      ret_val.should be_empty
+    end
+  end
+
+  shared_examples_for :selection_filter do |method_to_test|
+    it 'deletes every key-value pair for which the block evaluates truthy' do
+      ret_val = @hshlike.keep_if{|key,val| val }
+      ret_val.should be_hash_eql({ :a => 100, :b => 200, :c => 300  })
+      #
+      ret_val = @hshlike.keep_if{|key,val| val && (val.to_i > 150) }
+      ret_val.should be_hash_eql({ :b => 200, :c => 300  })
+      #
+      ret_val = @hshlike.keep_if{|key,val| false }
+      ret_val.should be_empty
+    end
+  end
+
+  shared_examples_for :filter_modifies_self_returns_nil_if_unchanged do |method_to_test, force_unchanged|
+    it 'modifies in-place and returns self if changes were made' do
+      ret_val = @hshlike.send(method_to_test){|key,val| val && (val.to_i > 150) }
+      ret_val.should equal(@hshlike)
+    end
+    it 'modifies in-place and returns self if changes were made (arity 1)' do
+      ret_val = @hshlike.send(method_to_test){|key| @hshlike[key] && (@hshlike[key].to_i > 150) }
+      ret_val.should equal(@hshlike)
+    end
+    it 'returns nil if unchanged' do
+      ret_val = @hshlike.send(method_to_test){|key,val| force_unchanged }
+      #
+      ret_val.should be_nil
+      @hshlike.should be_hash_eql(HashlikeHelper::BASE_HSH)
+    end
+  end
+
+  shared_examples_for :filter_modifies_self_returns_self do |method_to_test, force_unchanged|
+    it 'modifies in-place and returns self if changes were made' do
+      ret_val = @hshlike.send(method_to_test){|key,val| val && (val.to_i > 150) }
+      ret_val.should equal(@hshlike)
+    end
+    it 'modifies in-place and returns self if changes were made (arity 1)' do
+      ret_val = @hshlike.send(method_to_test){|key| @hshlike[key] && (@hshlike[key].to_i > 150) }
+      ret_val.should equal(@hshlike)
+    end
+    it 'returns self if unchanged' do
+      ret_val = @hshlike.send(method_to_test){|key,val| force_unchanged }
+      #
+      ret_val.should     equal(@hshlike)
+      @hshlike.should    be_hash_eql(HashlikeHelper::BASE_HSH)
+    end
+  end
+
+  shared_examples_for :filter_does_not_modify_self_returns_same_class do |method_to_test, force_unchanged|
+    it 'modifies in-place and returns self' do
+      ret_val = @hshlike.send(method_to_test){|key,val| val && (val.to_i > 150) }
+      ret_val.should_not be_hash_eql(@hshlike)
+      ret_val.should_not equal(@hshlike)
+      @hshlike.should    be_hash_eql(HashlikeHelper::BASE_HSH)
+    end
+    it 'is == if unchanged' do
+      ret_val = @hshlike.send(method_to_test){|key,val| force_unchanged }
+      #
+      ret_val.should_not equal(@hshlike)
+      ret_val.should     be_hash_eql(@hshlike)
+      @hshlike.should    be_hash_eql(HashlikeHelper::BASE_HSH)
+    end
+    it 'returns same class as caller' do
+      ret_val = @hshlike_subklass_inst.send(method_to_test){|key,val| val && (val.to_i > 150) }
+      ret_val.should be_a(@hshlike_subklass)
+      ret_val.should be_a(@hshlike.class)
+      ret_val.class.should_not == @hshlike.class
+    end
+  end
+
+  shared_examples_for :hashlike_clear do
+    it 'removes all key/value pairs' do
+      ret_val = @hshlike.clear
+      ret_val.should be_hash_eql(@empty_hshlike)
+      ret_val.should be_empty
+      @hshlike.should be_empty
+    end    
+  end
+
+  # ===========================================================================
+  #
+  # Conversion
+
+  shared_examples_for :hashlike_to_hash do
+    it 'returns a new Hash with each key set to its associated value' do
+      ret_val = @hshlike.to_hash
+      ret_val.should be_an_instance_of(Hash)
+      ret_val.should == HashlikeHelper::BASE_HSH
+    end    
+  end
+
+  shared_examples_for :hashlike_invert do
+    if (RUBY_VERSION >= '1.9')
+      it 'returns a new Hash using the values as keys, and the keys as values' do
+        ret_val = @hshlike.invert
+        ret_val.should == { 100 => :a, 200 => :b, 300 => :c, nil => :nil_val, false => :false_val }
+      end
+      it 'with duplicate values, the result will contain only one of them as a key' do
+        @hshlike[:a]       = 999
+        @hshlike[:new_key] = 999
+        @hshlike.invert.should == { 999 => :new_key, 200 => :b, 300 => :c, nil => :nil_val, false => :false_val }
+      end
+      it 'returns a Hash, not a self.class' do
+        ret_val = @hshlike.invert
+        ret_val.should be_an_instance_of(Hash)
+      end
+    else
+      it 'does not have tests for invert on Ruby < 1.9'
+    end
+  end
+
+  shared_examples_for :hashlike_flatten do
+    if (RUBY_VERSION >= '1.9')
+      it 'with no arg returns a one-dimensional flattening' do
+        ret_as_hash = HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS.flatten
+        ret_val     = @hshlike_with_array_vals.flatten
+        ret_val.should == ret_as_hash
+        ret_val.should == [  :a, [100, 111],  :b, 200,    :c, [1, [2, 3, [4, 5, 6]]],  ]
+        @hshlike_with_array_vals.should be_hash_eql(HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS)
+      end
+      it 'with no arg is same as level = 1' do
+        @hshlike_with_array_vals.flatten(1).should == @hshlike_with_array_vals.flatten
+      end
+      it 'with level == nil, returns a complete flattening' do
+        ret_as_hash = HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS.flatten(nil)
+        ret_val     = @hshlike_with_array_vals.flatten(nil)
+        ret_val.should == ret_as_hash
+        ret_val.should == [  :a,  100, 111,    :b,  200,  :c, 1,  2, 3,  4, 5, 6,       ]
+      end
+      it 'with an arg, flattens to that level (0)' do
+        ret_as_hash = HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS.flatten(0)
+        ret_val     = @hshlike_with_array_vals.flatten(0)
+        ret_val.should == ret_as_hash
+        ret_val.should == [ [:a, [100, 111]], [:b, 200], [:c, [1, [2, 3, [4, 5, 6]]]], ]
+      end
+      it 'with an arg, flattens to that level (3)' do
+        ret_as_hash = HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS.flatten(3)
+        ret_val     = @hshlike_with_array_vals.flatten(3)
+        ret_val.should == ret_as_hash
+        ret_val.should == [  :a,  100, 111,    :b, 200,   :c, 1,  2, 3, [4, 5, 6],]
+      end
+      it 'with an arg, flattens to that level (4)' do
+        ret_as_hash = HashlikeHelper::BASE_HSH_WITH_ARRAY_VALS.flatten(4)
+        ret_val     = @hshlike_with_array_vals.flatten(4)
+        ret_val.should == ret_as_hash
+        ret_val.should == [  :a,  100, 111,    :b, 200,   :c, 1,  2, 3,  4, 5, 6, ]
+        ret_val.should == @hshlike_with_array_vals.flatten(999)
+      end
+    else
+      it 'does not have tests for invert on Ruby < 1.9'
+    end
+  end
+
+  
+  
+end
+end ; HASHLIKE_BEHAVIOR_SPEC = true