hashery 1.5.0 → 2.0.0

data/lib/hashery/crud_hash.rb

@@ -0,0 +1,365 @@
+require 'hashery/core_ext'
+
+module Hashery
+
+  # The CRUDHash is essentailly the same as the Hash class, but it reduces the 
+  # the set of necessary methods to the fundametal CRUD requirements. All other
+  # methods route through these CRUD methods. This is a better general design,
+  # although it is, of course, a little bit slower. The utility of this class
+  # becomes appearent when subclassing or delegating, as only a handful of methods
+  # need to be changed for all other methods to work accordingly.
+  #
+  # In addition to the CRUD features, CRUDHash supports a `#key_proc`, akin to
+  # `#default_proc`, that can be used to normalize keys.
+  #
+  class CRUDHash < ::Hash
+
+    #
+    # This method is overridden to ensure that new entries pass through
+    # the `#store` method.
+    #
+    # hash - [#each] Single Hash, associative array or just a list of pairs.
+    #
+    def self.[](*hash)
+      h = new
+      if hash.size == 1
+        hash.first.each do |k,v|
+          h.store(k, v) 
+        end       
+      else
+        hash.each do |(k,v)|
+          h.store(k, v) 
+        end
+      end
+      h
+    end
+
+    #
+    # Alternate to #new which auto-creates sub-dictionaries as needed.
+    # By default the `default_proc` procuced a empty Hash and is 
+    # self-referential so every such Hash also has the same `default_proc`.
+    #
+    # args  - Pass-thru arguments to `#new`.
+    # block - Alternate internal procedure for default proc.
+    #
+    # Examples
+    #
+    #   d = CRUDHash.auto
+    #   d["a"]["b"]["c"] = "abc"  #=> { "a"=>{"b"=>{"c"=>"abc"}}}
+    #
+    # Returns `Hash`.
+    #
+    def self.auto(*args, &block)
+      if block
+        leet = lambda { |hsh, key| hsh[key] = block.call(hsh, key) }
+      else
+        leet = lambda { |hsh, key| hsh[key] = new(&leet) }
+      end
+      new(*args, &leet)
+    end
+
+    #
+    # Set `key_proc`.
+    #
+    # Examples
+    #
+    #   ch = CRUDHash.new
+    #   ch.key_proc = Proc.new{ |key| key.to_sym }
+    #
+    # Returns `Proc`.
+    #
+    def key_proc=(proc)
+      raise ArgumentError unless Proc === proc or NilClass === proc
+      @key_proc = proc
+    end
+
+    #
+    # Get/set `key_proc`.
+    #
+    # Examples
+    #
+    #   ch = CRUDHash.new
+    #   ch.key_proc
+    #
+    # Returns `Proc`.
+    #
+    def key_proc(&block)
+      @key_proc = block if block
+      @key_proc
+    end
+
+    #
+    # Allow `#default_proc` to take a block.
+    #
+    # block - The `Proc` object to set the `default_proc`.
+    #
+    # Returns `Proc`, the `default_proc`.
+    #
+    def default_proc(&block)
+      self.default_proc = block if block
+      super()
+    end
+
+    #
+    # CRUD method for checking if key exists.
+    #
+    # key - Hash key to lookup.
+    #
+    # Returns `true/false`.
+    #
+    def key?(key)
+      super cast_key(key)
+    end
+
+    #
+    # CRUD method for reading value.
+    #
+    # key - Hash key to lookup.
+    #
+    # Returns value of Hash entry.
+    #
+    def read(key)
+      super cast_key(key)
+    end
+
+    #
+    # CRUD method for create and update.
+    #
+    # key   - The `Object` to act as indexing key.
+    # value - The `Object` to associate with key.
+    #
+    # Returns +value+.
+    #
+    def store(key, value)
+      super(cast_key(key), value)
+    end
+
+    #
+    # CRUD method for delete.
+    #
+    # key - Hash key to remove.
+    #
+    # Returns value of deleted Hash entry.
+    #
+    def delete(key)
+      super cast_key(key)
+    end
+
+    #
+    # Like #read but raises an error if key is not present.
+    #
+    # key - Hash key to lookup.
+    #
+    # Returns the `Object` that is the Hash entry's value.
+    #
+    def fetch(key)
+      raise KeyError, "key not found: #{key.inspect}" unless key?(key)
+      read key
+    end
+
+    #
+    # Update Hash with +assoc+.
+    #
+    # assoc - Two-element `Array` or a `Hash`.
+    #
+    # Returns +assoc+.
+    #
+    def <<(assoc)
+      case assoc
+      when Hash
+        update(assoc)
+      when Array
+        assoc.each_slice(2) do |(k,v)|
+          store(k,v)
+        end
+      else
+        raise ArgumentError  # or TypeError ?
+      end
+    end
+
+    #
+    # Operator for `#read`.
+    #
+    # key - Index key to lookup.
+    #
+    # Returns `Object` value of key.
+    #
+    def [](key)
+      #if key?(key)
+      #  fetch(key)
+      #elsif default_proc
+      #  default_proc.call(self, key)
+      #else
+      #  default
+      #end
+      read(key)
+    end
+
+    #
+    # Operator for `#store`.
+    #
+    # key   - The `Object` to act as indexing key.
+    # value - The `Object` to associate with key.
+    #
+    # Returns +value+.
+    #
+    def []=(key,value)
+      store(key,value)
+    end
+
+    #
+    # Update the Hash with another hash.
+    # 
+    # other - Other hash or hash-like object to add to the hash.
+    #
+    # Returns +self+.
+    #
+    def update(other)
+      other.each do |k,v|
+        store(k, v)
+      end
+      self
+    end
+
+    #
+    # Alias for `#update`.
+    #
+    alias merge! update
+
+    #
+    # Merge the Hash with another hash, returning a new Hash.
+    # 
+    # other - Other hash or hash-like object to add to the hash.
+    #
+    # Returns `Hash`.
+    #
+    def merge(other)
+      #super(other.rekey{ |key| cast_key(key) })
+      copy = dup
+      other.each{ |k,v| copy.store(k, v) }
+      copy
+    end
+
+    #
+    # Iterate over each hash pair.
+    #
+    def each #:yield:
+      if block_given?
+        keys.each do |k|
+          yield(k, read(k))
+        end
+      else
+        to_enum(:each)
+      end
+    end
+
+    #
+    # Alias for #each.
+    #
+    alias each_pair each
+
+    #
+    # Alias for `#key?`.
+    #
+    alias has_key? key?
+
+    #
+    # Alias for `#key?`.
+    #
+    alias member? key?
+
+    #
+    # Alias for `#key?`.
+    #
+    alias include? key?   # why isn't it an alias for `#has_value?` ?
+
+    #
+    # Replace current entries with those from another Hash,
+    # or Hash-like object. Each entry is run through the
+    # casting procedure as it is added.
+    #
+    # other - Hash-like object.
+    #
+    # Returns +self+.
+    # 
+    def replace(other)
+      super cast(other)
+   end
+
+    #
+    # Get the values at.
+    #
+    # keys - List of keys to lookup.
+    #
+    # Returns `Array` of values.
+    #
+    def values_at(*keys)
+      super *keys.map{ |key| cast_key(key) }
+    end
+
+    # Convert CRUDHash to regular Hash.
+    #
+    # TODO: Since a CRUDHash is a subclass of Hash should #to_hash just `#dup`
+    #       insted of converting to traditional Hash?
+    #
+    def to_hash
+      h = {}; each{ |k,v| h[k] = v }; h
+    end #unless method_defined?(:to_hash)
+
+    #
+    # Convert CRUDHash to regular Hash.
+    #
+    # TODO: Since a CRUDHash is a subclass of Hash should #to_h just `#dup`
+    #       insted of converting to traditional Hash?
+    #
+    # Returns `Hash`.
+    #
+    alias :to_h :to_hash
+
+  private
+
+    #
+    # Cast a given `hash` in accordance to the `#key_proc`.
+    #
+    # hash - Any object the responds to `#each` like a Hash.
+    #
+    # Returns `Hash`.
+    #
+    def cast(hash)
+      h = {}
+      hash.each do |k,v|
+        h[cast_key(k)] = v
+      end
+      h
+    end
+
+    #
+    # Callback for normalizing hash keys.
+    #
+    # key - Index key.
+    #
+    # Returns key after passing through the `key_proc`.
+    #
+    def cast_key(key)
+      @key_proc ? @key_proc.call(key) : key
+    end
+
+    # TODO: Consider value callback procs for future version of CRUDHash.
+    #
+    #    #
+    #    # Callback for writing value.
+    #    #
+    #    def cast_write(value)
+    #      @write_proc ? @write_proc.call(value) : value
+    #    end
+    #
+    #    #
+    #    # Callback for reading value.
+    #    #
+    #    def cast_read(value)
+    #      @read_proc ? @read_proc.call(value) : value
+    #    end
+
+  end
+
+end

data/lib/hashery/dictionary.rb

@@ -1,90 +1,160 @@
-# = Dictionary
-#
-# The Dictionary class is a Hash that preserves order.
-# So it has some array-like extensions also. By defualt
-# a Dictionary object preserves insertion order, but any
-# order can be specified including alphabetical key order.
-#
-# == Usage
-#
-# Just require this file and use Dictionary instead of Hash.
-#
-#   # You can do simply
-#   hsh = Dictionary.new
-#   hsh['z'] = 1
-#   hsh['a'] = 2
-#   hsh['c'] = 3
-#   p hsh.keys     #=> ['z','a','c']
-#
-#   # or using Dictionary[] method
-#   hsh = Dictionary['z', 1, 'a', 2, 'c', 3]
-#   p hsh.keys     #=> ['z','a','c']
-#
-#   # but this don't preserve order
-#   hsh = Dictionary['z'=>1, 'a'=>2, 'c'=>3]
-#   p hsh.keys     #=> ['a','c','z']
-#
-#   # Dictionary has useful extensions: push, pop and unshift
-#   p hsh.push('to_end', 15)       #=> true, key added
-#   p hsh.push('to_end', 30)       #=> false, already - nothing happen
-#   p hsh.unshift('to_begin', 50)  #=> true, key added
-#   p hsh.unshift('to_begin', 60)  #=> false, already - nothing happen
-#   p hsh.keys                     #=> ["to_begin", "a", "c", "z", "to_end"]
-#   p hsh.pop                      #=> ["to_end", 15], if nothing remains, return nil
-#   p hsh.keys                     #=> ["to_begin", "a", "c", "z"]
-#   p hsh.shift                    #=> ["to_begin", 30], if nothing remains, return nil
-#
-# == Usage Notes
-#
-# * You can use #order_by to set internal sort order.
-# * #<< takes a two element [k,v] array and inserts.
-# * Use ::auto which creates Dictionay sub-entries as needed.
-# * And ::alpha which creates a new Dictionary sorted by key.
-#
-# == Acknowledgments
-#
-# Dictionary is a ported of OrderHash 2.0 Copyright (c) 2005 Jan Molic.
-#
-# People who have contributed to this class since then include:
-#
-# * Andrew Johnson (merge, to_a, inspect, shift and Hash[])
-# * Jeff Sharpe    (reverse and reverse!)
-# * Thomas Leitner (has_key? and key?)
-#
-# Copyright (c) 2005, 2009 Jan Molic, Thomas Sawyer
-
-class Dictionary
-
-  include Enumerable
-
-  class << self
-    #--
-    # TODO is this needed? Doesn't the super class do this?
-    #++
-
-    def [](*args)
-      hsh = new
-      if Hash === args[0]
-        hsh.replace(args[0])
-      elsif (args.size % 2) != 0
-        raise ArgumentError, "odd number of elements for Hash"
-      else
-        while !args.empty?
-          hsh[args.shift] = args.shift
+module Hashery
+
+  # The Dictionary class is a Hash that preserves order.
+  # So it has some array-like extensions also. By defualt
+  # a Dictionary object preserves insertion order, but any
+  # order can be specified including alphabetical key order.
+  #
+  # Using a Dictionary is almost the same as using a Hash.
+  #
+  #   # You can do simply
+  #   hsh = Dictionary.new
+  #   hsh['z'] = 1
+  #   hsh['a'] = 2
+  #   hsh['c'] = 3
+  #   p hsh.keys     #=> ['z','a','c']
+  #
+  #   # or using Dictionary[] method
+  #   hsh = Dictionary['z', 1, 'a', 2, 'c', 3]
+  #   p hsh.keys     #=> ['z','a','c']
+  #
+  #   # but this don't preserve order
+  #   hsh = Dictionary['z'=>1, 'a'=>2, 'c'=>3]
+  #   p hsh.keys     #=> ['a','c','z']
+  #
+  #   # Dictionary has useful extensions: push, pop and unshift
+  #   p hsh.push('to_end', 15)       #=> true, key added
+  #   p hsh.push('to_end', 30)       #=> false, already - nothing happen
+  #   p hsh.unshift('to_begin', 50)  #=> true, key added
+  #   p hsh.unshift('to_begin', 60)  #=> false, already - nothing happen
+  #   p hsh.keys                     #=> ["to_begin", "a", "c", "z", "to_end"]
+  #   p hsh.pop                      #=> ["to_end", 15], if nothing remains, return nil
+  #   p hsh.keys                     #=> ["to_begin", "a", "c", "z"]
+  #   p hsh.shift                    #=> ["to_begin", 30], if nothing remains, return nil
+  #
+  # == Notes
+  #
+  # * You can use #order_by to set internal sort order.
+  # * #<< takes a two element [k,v] array and inserts.
+  # * Use ::auto which creates Dictionay sub-entries as needed.
+  # * And ::alpha which creates a new Dictionary sorted by key.
+  #
+  # == Acknowledgments
+  #
+  # Dictionary is a port of OrderHash 2.0 Copyright (c) 2005 Jan Molic.
+  #
+  # People who have contributed to this class since then include:
+  #
+  # * Andrew Johnson (merge, to_a, inspect, shift and Hash[])
+  # * Jeff Sharpe    (reverse and reverse!)
+  # * Thomas Leitner (has_key? and key?)
+  #
+  # OrderedHash is public domain.
+  #
+  class Dictionary
+
+    include Enumerable
+
+    class << self
+      #--
+      # TODO is this needed? Doesn't the super class do this?
+      #++
+
+      def [](*args)
+        hsh = new
+        if Hash === args[0]
+          hsh.replace(args[0])
+        elsif (args.size % 2) != 0
+          raise ArgumentError, "odd number of elements for Hash"
+        else
+          while !args.empty?
+            hsh[args.shift] = args.shift
+          end
         end
+        hsh
+      end
+
+      #
+      # Like #new but the block sets the order.
+      #
+      def new_by(*args, &blk)
+        new(*args).order_by(&blk)
+      end
+
+      #
+      # Alternate to #new which creates a dictionary sorted by key.
+      #
+      #   d = Dictionary.alpha
+      #   d["z"] = 1
+      #   d["y"] = 2
+      #   d["x"] = 3
+      #   d  #=> {"x"=>3,"y"=>2,"z"=>2}
+      #
+      # This is equivalent to:
+      #
+      #   Dictionary.new.order_by { |key,value| key }
+
+      def alpha(*args, &block)
+        new(*args, &block).order_by_key
+      end
+
+      #
+      # Alternate to #new which auto-creates sub-dictionaries as needed.
+      #
+      # Examples
+      #
+      #   d = Dictionary.auto
+      #   d["a"]["b"]["c"] = "abc"  #=> { "a"=>{"b"=>{"c"=>"abc"}}}
+      #
+      def auto(*args)
+        #AutoDictionary.new(*args)
+        leet = lambda { |hsh, key| hsh[key] = new(&leet) }
+        new(*args, &leet)
       end
-      hsh
     end
 
-    # Like #new but the block sets the order.
     #
-    def new_by(*args, &blk)
-      new(*args).order_by(&blk)
+    # New Dictiionary.
+    #
+    def initialize(*args, &blk)
+      @order = []
+      @order_by = nil
+      if blk
+        dict = self                                  # This ensure autmatic key entry effect the
+        oblk = lambda{ |hsh, key| blk[dict,key] }    # dictionary rather then just the interal hash.
+        @hash = Hash.new(*args, &oblk)
+      else
+        @hash = Hash.new(*args)
+      end
+    end
+
+    #
+    # Order of keys.
+    #
+    # Returns [Array].
+    #
+    def order
+      reorder if @order_by
+      @order
+    end
+
+    #
+    # Keep dictionary sorted by a specific sort order.
+    #
+    # block - Ordering procedure.
+    #
+    # Returns +self+.
+    #
+    def order_by( &block )
+      @order_by = block
+      order
+      self
     end
 
-    # Alternate to #new which creates a dictionary sorted by key.
     #
-    #   d = Dictionary.alpha
+    # Keep dictionary sorted by key.
+    #
+    #   d = Dictionary.new.order_by_key
     #   d["z"] = 1
     #   d["y"] = 2
     #   d["x"] = 3
@@ -93,332 +163,462 @@ class Dictionary
     # This is equivalent to:
     #
     #   Dictionary.new.order_by { |key,value| key }
-
-    def alpha(*args, &block)
-      new(*args, &block).order_by_key
+    #
+    # The initializer Dictionary#alpha also provides this.
+    #
+    # Returns +self+.
+    #
+    def order_by_key
+      @order_by = Proc.new{ |k,v| k }
+      order
+      self
     end
 
-    # Alternate to #new which auto-creates sub-dictionaries as needed.
     #
-    #   d = Dictionary.auto
-    #   d["a"]["b"]["c"] = "abc"  #=> { "a"=>{"b"=>{"c"=>"abc"}}}
+    # Keep dictionary sorted by value.
     #
-    def auto(*args)
-      #AutoDictionary.new(*args)
-      leet = lambda { |hsh, key| hsh[key] = new(&leet) }
-      new(*args, &leet)
+    #   d = Dictionary.new.order_by_value
+    #   d["z"] = 1
+    #   d["y"] = 2
+    #   d["x"] = 3
+    #   d  #=> {"x"=>3,"y"=>2,"z"=>2}
+    #
+    # This is equivalent to:
+    #
+    #   Dictionary.new.order_by { |key,value| value }
+    #
+    def order_by_value
+      @order_by = Proc.new{ |k,v| v }
+      order
+      self
     end
-  end
 
-   # New Dictiionary.
-
-  def initialize(*args, &blk)
-    @order = []
-    @order_by = nil
-    if blk
-      dict = self                                  # This ensure autmatic key entry effect the
-      oblk = lambda{ |hsh, key| blk[dict,key] }    # dictionary rather then just the interal hash.
-      @hash = Hash.new(*args, &oblk)
-    else
-      @hash = Hash.new(*args)
+    #
+    # Re-apply the sorting procedure.
+    #
+    def reorder
+      if @order_by
+        assoc = @order.collect{ |k| [k,@hash[k]] }.sort_by(&@order_by)
+        @order = assoc.collect{ |k,v| k }
+      end
+      @order
     end
-  end
-
-  #
 
-  def order
-    reorder if @order_by
-    @order
-  end
-
-  # Keep dictionary sorted by a specific sort order.
-
-  def order_by( &block )
-    @order_by = block
-    order
-    self
-  end
+    #def ==( hsh2 )
+    #  return false if @order != hsh2.order
+    #  super hsh2
+    #end
 
-  # Keep dictionary sorted by key.
-  #
-  #   d = Dictionary.new.order_by_key
-  #   d["z"] = 1
-  #   d["y"] = 2
-  #   d["x"] = 3
-  #   d  #=> {"x"=>3,"y"=>2,"z"=>2}
-  #
-  # This is equivalent to:
-  #
-  #   Dictionary.new.order_by { |key,value| key }
-  #
-  # The initializer Dictionary#alpha also provides this.
-
-  def order_by_key
-    @order_by = lambda { |k,v| k }
-    order
-    self
-  end
+    #
+    # Is the dictionary instance equivalent to another?
+    #
+    def ==(hsh2)
+      if hsh2.is_a?( Dictionary )
+        @order == hsh2.order &&
+        @hash  == hsh2.instance_variable_get("@hash")
+      else
+        false
+      end
+    end
 
-  # Keep dictionary sorted by value.
-  #
-  #   d = Dictionary.new.order_by_value
-  #   d["z"] = 1
-  #   d["y"] = 2
-  #   d["x"] = 3
-  #   d  #=> {"x"=>3,"y"=>2,"z"=>2}
-  #
-  # This is equivalent to:
-  #
-  #   Dictionary.new.order_by { |key,value| value }
+    #
+    # Lookup entry with key.
+    #
+    def [] key
+      @hash[ key ]
+    end
 
-  def order_by_value
-    @order_by = lambda { |k,v| v }
-    order
-    self
-  end
+    #
+    # Featch entry given +key+.
+    #
+    def fetch(key, *a, &b)
+      @hash.fetch(key, *a, &b)
+    end
 
-  #
+    #
+    # Store operator.
+    #
+    #   h[key] = value
+    #
+    # Or with additional index.
+    #
+    #  h[key,index] = value
+    #
+    def []=(k, i=nil, v=nil)
+      if v
+        insert(i,k,v)
+      else
+        store(k,i)
+      end
+    end
 
-  def reorder
-    if @order_by
-      assoc = @order.collect{ |k| [k,@hash[k]] }.sort_by(&@order_by)
-      @order = assoc.collect{ |k,v| k }
+    #
+    # Insert entry into dictionary at specific index position.
+    #
+    # index - [Integer] Position of order placement.
+    # key   - [Object]  Key to associate with value.
+    # value - [Object]  Value to associate with key.
+    #
+    # Returns `value` stored.
+    #
+    def insert(index, key, value)
+      @order.insert(index, key)
+      @hash.store(key, value)
     end
-    @order
-  end
 
-  #def ==( hsh2 )
-  #  return false if @order != hsh2.order
-  #  super hsh2
-  #end
+    #
+    # Add entry into dictionary.
+    #
+    # Returns `value`.
+    #
+    def store(key, value)
+      @order.push(key) unless @hash.has_key?(key)
+      @hash.store(key, value)
+    end
 
-  def ==(hsh2)
-    if hsh2.is_a?( Dictionary )
-      @order == hsh2.order &&
-      @hash  == hsh2.instance_variable_get("@hash")
-    else
-      false
+    #
+    # Clear dictionary of all entries.
+    #
+    def clear
+      @order = []
+      @hash.clear
     end
-  end
 
-  def [] k
-    @hash[ k ]
-  end
+    #
+    # Delete the entry with given +key+.
+    #
+    def delete(key)
+      @order.delete(key)
+      @hash.delete(key)
+    end
 
-  def fetch(k, *a, &b)
-    @hash.fetch(k, *a, &b)
-  end
+    #
+    # Iterate over each key.
+    #
+    def each_key
+      order.each { |k| yield( k ) }
+      self
+    end
 
-  # Store operator.
-  #
-  #   h[key] = value
-  #
-  # Or with additional index.
-  #
-  #  h[key,index] = value
+    #
+    # Iterate over each value.
+    #
+    def each_value
+      order.each { |k| yield( @hash[k] ) }
+      self
+    end
 
-  def []=(k, i=nil, v=nil)
-    if v
-      insert(i,k,v)
-    else
-      store(k,i)
+    #
+    # Iterate over each key-value pair.
+    #
+    def each
+      order.each { |k| yield( k,@hash[k] ) }
+      self
     end
-  end
 
-  def insert( i,k,v )
-    @order.insert( i,k )
-    @hash.store( k,v )
-  end
+    alias each_pair each
 
-  def store( a,b )
-    @order.push( a ) unless @hash.has_key?( a )
-    @hash.store( a,b )
-  end
+    #
+    # Delete entry if it fits conditional block.
+    #
+    def delete_if
+      order.clone.each { |k| delete k if yield(k,@hash[k]) }
+      self
+    end
 
-  def clear
-    @order = []
-    @hash.clear
-  end
+    #
+    # List of all dictionary values.
+    #
+    # Returns [Array].
+    #
+    def values
+      ary = []
+      order.each { |k| ary.push @hash[k] }
+      ary
+    end
 
-  def delete( key )
-    @order.delete( key )
-    @hash.delete( key )
-  end
+    #
+    # List of all dictionary keys.
+    #
+    # Returns [Array].
+    #
+    def keys
+      order
+    end
 
-  def each_key
-    order.each { |k| yield( k ) }
-    self
-  end
+    #
+    # Invert the dictionary.
+    #
+    # Returns [Dictionary] New dictionary that is inverse of the original.
+    #
+    def invert
+      hsh2 = self.class.new
+      order.each { |k| hsh2[@hash[k]] = k }
+      hsh2
+    end
 
-  def each_value
-    order.each { |k| yield( @hash[k] ) }
-    self
-  end
+    #
+    # Reject entries based on give condition block and return
+    # new dictionary.
+    #
+    # Returns [Dictionary].
+    #
+    def reject(&block)
+      self.dup.delete_if(&block)
+    end
 
-  def each
-    order.each { |k| yield( k,@hash[k] ) }
-    self
-  end
-  alias each_pair each
+    #
+    # Reject entries based on give condition block.
+    #
+    # Returns [Hash] of rejected entries.
+    #
+    # FIXME: This looks like it is implemented wrong!!!
+    #
+    def reject!( &block )
+      hsh2 = reject(&block)
+      self == hsh2 ? nil : hsh2
+    end
 
-  def delete_if
-    order.clone.each { |k| delete k if yield(k,@hash[k]) }
-    self
-  end
+    #
+    # Replace dictionary entries with new table.
+    #
+    def replace(hsh2)
+      case hsh2
+      when Dictionary
+        @order = hsh2.order
+        @hash  = hsh2.to_h
+      when Hash
+        @hash  = hsh2
+        @order = @hash.keys
+      else
+        @hash  = hsh2.to_h
+        @order = @hash.keys
+      end
+      reorder
+    end
 
-  def values
-    ary = []
-    order.each { |k| ary.push @hash[k] }
-    ary
-  end
+    #
+    # Remove entry from the to top of dictionary.
+    #
+    def shift
+      key = order.first
+      key ? [key,delete(key)] : super
+    end
 
-  def keys
-    order
-  end
+    #
+    # Push entry on to the top of dictionary.
+    #
+    def unshift( k,v )
+      unless @hash.include?( k )
+        @order.unshift( k )
+        @hash.store( k,v )
+        true
+      else
+        false
+      end
+    end
 
-  def invert
-    hsh2 = self.class.new
-    order.each { |k| hsh2[@hash[k]] = k }
-    hsh2
-  end
+    #
+    # Same as #push.
+    #
+    def <<(kv)
+      push(*kv)
+    end
 
-  def reject(&block)
-    self.dup.delete_if(&block)
-  end
+    #
+    # Push entry on to bottom of the dictionary.
+    #
+    def push(k,v)
+      unless @hash.include?( k )
+        @order.push( k )
+        @hash.store( k,v )
+        true
+      else
+        false
+      end
+    end
 
-  def reject!( &block )
-    hsh2 = reject(&block)
-    self == hsh2 ? nil : hsh2
-  end
+    #
+    # Pop entry off the bottom of dictionary.
+    #
+    def pop
+      key = order.last
+      key ? [key,delete(key)] : nil
+    end
 
-  def replace(hsh2)
-    case hsh2
-    when Hash
-      @order = hsh2.keys
-      @hash  = hsh2
-    else
-      @order = hsh2.order
-      @hash  = hsh2.hash
+    #
+    # Inspection string for Dictionary.
+    #
+    # Returns [String].
+    #
+    def inspect
+      ary = []
+      each {|k,v| ary << k.inspect + "=>" + v.inspect}
+      '{' + ary.join(", ") + '}'
     end
-    reorder
-  end
 
-  def shift
-    key = order.first
-    key ? [key,delete(key)] : super
-  end
+    #
+    # Duplicate dictionary.
+    #
+    # Returns [Dictionary].
+    #
+    def dup
+      a = []
+      each{ |k,v| a << k; a << v }
+      self.class[*a]
+    end
 
-  def unshift( k,v )
-    unless @hash.include?( k )
-      @order.unshift( k )
-      @hash.store( k,v )
-      true
-    else
-      false
+    #
+    # Update dictionary with other hash.
+    #
+    # Returns self.
+    #
+    def update( hsh2 )
+      hsh2.each { |k,v| self[k] = v }
+      reorder
+      self
     end
-  end
 
-  def <<(kv)
-    push(*kv)
-  end
+    alias :merge! update
 
-  def push( k,v )
-    unless @hash.include?( k )
-      @order.push( k )
-      @hash.store( k,v )
-      true
-    else
-      false
+    #
+    # Merge other hash creating new dictionary.
+    #
+    # Returns [Dictionary].
+    #
+    def merge(hsh2)
+      self.dup.update(hsh2)
     end
-  end
 
-  def pop
-    key = order.last
-    key ? [key,delete(key)] : nil
-  end
+    #
+    # Select items from dictiornary.
+    #
+    # Returns [Array] of two-element arrays.
+    #
+    def select
+      ary = []
+      each { |k,v| ary << [k,v] if yield k,v }
+      ary
+    end
 
-  def inspect
-    ary = []
-    each {|k,v| ary << k.inspect + "=>" + v.inspect}
-    '{' + ary.join(", ") + '}'
-  end
+    #
+    # Reverse the order of the dictionary.
+    #
+    # Returns self.
+    #
+    def reverse!
+      @order.reverse!
+      self
+    end
 
-  def dup
-    a = []
-    each{ |k,v| a << k; a << v }
-    self.class[*a]
-  end
+    #
+    # Reverse the order of duplicte dictionary.
+    #
+    # Returns [Dictionary].
+    #
+    def reverse
+      dup.reverse!
+    end
 
-  def update( hsh2 )
-    hsh2.each { |k,v| self[k] = v }
-    reorder
-    self
-  end
-  alias :merge! update
+    #
+    # Get/set initial entry value.
+    #
+    def first(x=nil)
+      return @hash[order.first] unless x
+      order.first(x).collect { |k| @hash[k] }
+    end
 
-  def merge( hsh2 )
-    self.dup.update(hsh2)
-  end
+    #
+    # Get/set last entry value.
+    #
+    def last(x=nil)
+      return @hash[order.last] unless x
+      order.last(x).collect { |k| @hash[k] }
+    end
 
-  def select
-    ary = []
-    each { |k,v| ary << [k,v] if yield k,v }
-    ary
-  end
+    #
+    # Number of items in the dictionary.
+    #
+    def length
+      @order.length
+    end
 
-  def reverse!
-    @order.reverse!
-    self
-  end
+    alias :size :length
 
-  def reverse
-    dup.reverse!
-  end
+    #
+    # Is the dictionary empty?
+    #
+    # Returns `true` or `false`.
+    #
+    def empty?
+      @hash.empty?
+    end
 
-  #
-  def first(x=nil)
-    return @hash[order.first] unless x
-    order.first(x).collect { |k| @hash[k] }
-  end
+    #
+    # Does the dictionary have a given +key+.
+    #
+    # Returns `true` or `false`.
+    #
+    def has_key?(key)
+      @hash.has_key?(key)
+    end
 
-  #
-  def last(x=nil)
-    return @hash[order.last] unless x
-    order.last(x).collect { |k| @hash[k] }
-  end
+    #
+    # Does the dictionary have a given +key+.
+    #
+    # Returns `true` or `false`.
+    #
+    def key?(key)
+      @hash.key?(key)
+    end
 
-  def length
-    @order.length
-  end
-  alias :size :length
+    #
+    # Convert to array.
+    #
+    # Returns [Array] of two-element arrays.
+    #
+    def to_a
+      ary = []
+      each { |k,v| ary << [k,v] }
+      ary
+    end
 
-  def empty?
-    @hash.empty?
-  end
+    #
+    # Convert to array then to string.
+    #
+    # Returns [String].
+    #
+    def to_s
+      self.to_a.to_s
+    end
 
-  def has_key?(key)
-    @hash.has_key?(key)
-  end
+    #
+    # Get a duplicate of the underlying hash table.
+    #
+    # Returns [Hash].
+    #
+    def to_hash
+      @hash.dup
+    end
 
-  def key?(key)
-    @hash.key?(key)
-  end
+    #
+    # Get a duplicate of the underlying hash table.
+    #
+    # Returns [Hash].
+    #
+    def to_h
+      @hash.dup
+    end
 
-  def to_a
-    ary = []
-    each { |k,v| ary << [k,v] }
-    ary
-  end
+  protected
 
-  def to_s
-    self.to_a.to_s
-  end
+    #
+    # Underlying hash table.
+    #
+    def hash_table
+      @hash
+    end
 
-  def to_hash
-    @hash.dup
   end
 
-  def to_h
-    @hash.dup
-  end
 end