hashery 1.5.0 → 2.0.0

data/lib/hashery/casting_hash.rb

@@ -1,165 +1,158 @@
-# CastingHash is just like Hash, except that all keys and values
-# are passed through casting procedures.
-#--
-# TODO: Handle default_proc.
-#++
-class CastingHash < Hash
+require 'hashery/crud_hash'
 
-  # Default key conversion procedure.
-  KEY_PROC = lambda{ |x| x } #.to_s }
-
-  # Default value conversion procedure.
-  VAL_PROC = lambda{ |x| x }
-
-  #
-  def self.[](hash)
-    s = new
-    hash.each{ |k,v| s[k] = v }
-    s
-  end
-
-  #
-  def initialize(hash={}, value_cast=nil, &key_cast)
-    @key_proc   = (key_cast   || KEY_PROC)
-    @value_proc = (value_cast || VAL_PROC).to_proc
-    hash.each{ |k,v| self[k] = v }
-  end
+module Hashery
 
+  # CastingHash is just like CRUDHash, except that both keys and values
+  # can be passed through casting procedures.
   #
-  def key_proc
-    @key_proc
-  end
+  class CastingHash < CRUDHash
 
-  #
-  def key_proc=(proc)
-    @key_proc = proc.to_proc
-  end
+    #
+    # Like `#new` but can take a priming Hash or Array-pairs.
+    #
+    # hash - Hash-like object.
+    #
+    # Examples
+    #
+    #   CastingHash[:a,1,:b,2]
+    #
+    # Returns `CastingHash`.
+    #
+    def self.[](hash)
+      s = new
+      hash.each{ |k,v| s[k] = v }
+      s
+    end
 
-  #
-  def value_proc
-    @value_proc
-  end
+    #
+    # Unlike traditional Hash a CastingHash's block argument
+    # coerces key/value pairs when #store is called.
+    #
+    # default   - Default value.
+    # cast_proc - Casting procedure.
+    #
+    def initialize(default=nil, &cast_proc)
+      @cast_proc = cast_proc
+      super(default, &nil)
+    end
 
-  #
-  def value_proc=(proc)
-    @value_proc = proc.to_proc
-  end
+    #
+    # The cast procedure.
+    #
+    # proc - Casting procedure.
+    #
+    # Returns `Proc` used for casting.
+    #
+    def cast_proc(&proc)
+      @cast_proc = proc if proc
+      @cast_proc
+    end
 
-  #
-  def [](k)
-    super(key_proc[k])
-  end
+    #
+    # Set `cast_proc`. This procedure must take two arguments (`key, value`)
+    # and return the same.
+    #
+    # proc - Casting procedure.
+    #
+    # Returns +proc+.
+    #
+    def cast_proc=(proc)
+      raise ArgumentError unless Proc === proc or NilClass === proc
+      @cast_proc = proc
+    end
 
-  #
-  def []=(k,v)
-    super(key_proc[k], value_proc[v])
-  end
+    #
+    # CRUD method for create and update. Unlike the parent class
+    # the key, value pair are passed threw the cast_proc before
+    # being set in the underlying hash table.
+    #
+    # key   - Key of entry.
+    # value - Value of entry.
+    #
+    # Returns the +value+.
+    #
+    def store(key, value)
+      super(*cast_pair(key, value))
+    end
 
-  #
-  def <<(other)
-    case other
-    when Hash
-      super(cast(other))
-    when Array
-      self[other[0]] = other[1]
-    else
-      raise ArgumentError
+    #
+    # 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
-  end
 
-  def fetch(k)
-    super(key_proc[k])
-  end
+    #
+    # Convert the CastingHash to a regular Hash.
+    #
+    # Returns an ordinary `Hash`.
+    #
+    def to_hash
+      h = {}; each{ |k,v| h[k] = v }; h
+    end
 
-  #
-  def store(k, v)
-    super(key_proc[k], value_proc[v])
-  end
+    #
+    # Returns an ordinary `Hash`.
+    #
+    alias_method :to_h, :to_hash
 
-  #
-  def key?(k)
-    super(key_proc[k])
-  end
+    #
+    # Recast all entries via the cast procedure.
+    #
+    # TODO: Isn't this the same as `#rehash`?
+    #
+    # Returns +self+.
+    #
+    def recast!
+      replace self
+    end
 
-  #
-  def has_key?(k)
-    super(key_proc[k])
-  end
+  private
 
-  # Synonym for Hash#rekey, but modifies the receiver in place (and returns it).
-  #
-  #   foo = { :name=>'Gavin', :wife=>:Lisa }.to_stash
-  #   foo.rekey!{ |k| k.upcase }  #=>  { "NAME"=>"Gavin", "WIFE"=>:Lisa }
-  #   foo.inspect                 #=>  { "NAME"=>"Gavin", "WIFE"=>:Lisa }
-  #
-  def rekey!(*args, &block)
-    # for backward comptability (DEPRECATE?).
-    block = args.pop.to_sym.to_proc if args.size == 1
-    if args.empty?
-      block = lambda{|k| k} unless block
-      keys.each do |k|
-        nk = block[k]
-        self[nk] = delete(k) #if nk
+    #
+    # If `cast_proc` is defined then use it to process key-value pair,
+    # otherwise return them as is.
+    #
+    # key   - Key of entry.
+    # value - Value of entry.
+    #
+    # Returns `Array` of key-value pair.
+    #
+    def cast_pair(key, value)
+      if cast_proc
+        return cast_proc.call(key, value)
+      else
+        return key, value
       end
-    else
-      raise ArgumentError, "3 for 2" if block
-      to, from = *args
-      self[to] = delete(from) if has_key?(from)
     end
-    self
-  end
-
-  #
-  def rekey(*args, &block)
-    dup.rekey!(*args, &block)
-  end
-
-  #
-  def delete(k)
-    super(key_proc[k])
-  end
-
-  #
-  def update(other)
-    super(cast(other))
-  end
-
-  # Same as #update.
-  def merge!(other)
-    super(cast(other))
-  end
-
-  #
-  def replace(other)
-    super(cast(other))
-  end
-
-  #
-  def values_at(*keys)
-    super(keys.map(&key_proc))
-  end
-
-  #
-  def to_hash
-    h = {}; each{ |k,v| h[k] = v }; h
-  end
-
-  #
-  alias_method :to_h, :to_hash
-
-  private
 
+    #
+    # Cast a given +hash+ according to the `#key_proc` and `#value_proc`.
+    #
+    # hash - A `Hash` or anything the responds to `#each` like a hash.
+    #
+    # Returns a recasted `Hash`.
     #
     def cast(hash)
-      h
+      h = {}
       hash.each do |k,v|
-        h[key_proc[k]] = value_proc[v]
+        k, v = cast_pair(k, v)
+        h[k] = v
       end
       h
     end
 
+  end
+
 end
 
+# TODO: Should we add #to_casting_hash to Hash classs?
 
 #class Hash
 #

data/lib/hashery/core_ext.rb

@@ -1,82 +1,110 @@
-module Hashery
+class Hash
 
-  # This module is included into Ruby's core Hash class.
   #
-  # These method derive from Ruby Facets.
-  module CoreExt
+  # Create a hash given an `initial_hash`.
+  #
+  # initial_hash - Hash or hash-like object to use as priming data.
+  # block        - Procedure used by initialize (e.g. default_proc).
+  #
+  # Returns a `Hash`.
+  #
+  def self.create(initial_hash={}, &block)
+    o = new &block
+    o.update(initial_hash)
+    o
+  end
 
-    #
-    def to_h
-      self
-    end
+  #
+  # Alias for `#[]`.
+  #
+  alias :read :[]
 
-    #
-    def to_hash
-      self
-    end
+  #
+  # Convert to Hash.
+  #
+  def to_hash
+    dup  # -or- `h = {}; each{ |k,v| h[k] = v }; h` ?
+  end
 
-    # Synonym for Hash#rekey, but modifies the receiver in place (and returns it).
-    #
-    #   foo = { :name=>'Gavin', :wife=>:Lisa }
-    #   foo.rekey!{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #   foo.inspect               #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #
-    def rekey(key_map=nil, &block)
-      if !(key_map or block)
-        block = lambda{|k| k.to_sym}
-      end
+  #
+  # For a Hash, `#to_h` is the same as `#to_hash`.
+  #
+  alias :to_h :to_hash
+
+  #
+  # Synonym for Hash#rekey, but modifies the receiver in place (and returns it).
+  #
+  # key_map - Hash of old key to new key.
+  # block   - Procedure to convert keys, which can take just the key
+  #           or both key and value as arguments.
+  #
+  # Examples
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.rekey!{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo.inspect               #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #
+  # Returns `Hash`.
+  #
+  def rekey(key_map=nil, &block)
+    if !(key_map or block)
+      block = lambda{|k| k.to_sym}
+    end
 
-      key_map ||= {} 
+    key_map ||= {} 
 
-      hash = {}
+    hash = {}
 
-      (keys - key_map.keys).each do |key|
-        hash[key] = self[key]
-      end
+    (keys - key_map.keys).each do |key|
+      hash[key] = self[key]
+    end
 
-      key_map.each do |from, to|
-        hash[to] = self[from] if key?(from)
-      end
+    key_map.each do |from, to|
+      hash[to] = self[from] if key?(from)
+    end
 
-      hash2 = {}
+    hash2 = {}
 
-      if block
-        if block.arity == 1  # TODO: is this condition needed?
-          hash.each do |k, v|
-            nk = block[k]
-            #nk = (NA == nk ? k : nk)  # TODO: Can't support this here.
-            hash2[nk] = v
-          end
-        else
-          hash.each do |k, v|
-            nk = block[k,v]
-            #nk = (NA == nk ? k : nk)  # TODO:
-            hash2[nk] = v
-          end
+    if block
+      case block.arity
+      when 0
+        raise ArgumentError, "arity of 0 for #{block.inspect}"
+      when 2
+        hash.each do |k,v|
+          nk = block.call(k,v)
+          hash2[nk] = v
         end
       else
-        hash2 = hash
+        hash.each do |k,v|
+          nk = block[k]
+          hash2[nk] = v
+        end
       end
-
-      hash2
+    else
+      hash2 = hash
     end
 
-    # Synonym for Hash#rekey, but modifies the receiver in place (and returns it).
-    #
-    #   foo = { :name=>'Gavin', :wife=>:Lisa }
-    #   foo.rekey!{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #   foo                       #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #
-    # CREDIT: Trans, Gavin Kistner
-
-    def rekey!(key_map=nil, &block)
-      replace(rekey(key_map, &block))
-    end
+    hash2
+  end
 
+  #
+  # Synonym for Hash#rekey, but modifies the receiver in place (and returns it).
+  #
+  # key_map - Hash of old key to new key.
+  # block   - Procedure to convert keys, which can take just the key
+  #           or both key and value as arguments.
+  #
+  # Examples
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.rekey!{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo                       #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #
+  # Returns `Hash`.
+  #
+  def rekey!(key_map=nil, &block)
+    replace(rekey(key_map, &block))
   end
 
 end
 
-class Hash #:nodoc:
-  include Hashery::CoreExt
-end