hashery 1.0.0

data/HISTORY

@@ -0,0 +1,15 @@
+== 1.0.0 // 2010-04-21
+
+This is the first release of the Facets Hashery.
+Most of included classes come directly from Ruby
+Facets, so they have been around a while and are
+in good working condition.
+
+Some improvements are planned for the next release.
+In particular the OrderHash and Dictionary, which
+presently have essentially the same coding, will
+diverge to target slightly different use cases.
+
+Changes:
+
+* Happy Birthday!

data/LICENSE

@@ -0,0 +1,23 @@
+The MIT License
+
+Copyright (c) 2005 Thomas Sawyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+

data/README.rdoc

@@ -0,0 +1,47 @@
+= Facets Hashery
+
+* home: http://rubyworks.github.com/hashery
+* work: http://github.com/rubyworks/hashery
+
+== DESCRIPTION
+
+Among Ruby Facets most common additions were an assortment
+of Hash-like classes. To better support this collection of
+of libraries it was deemed prudent to create a side project
+specifically for them. Hence the Facets Hashery.
+
+Included in this collect are the widely used OrderedHash, 
+the related but more featured Dictionary class, a number
+of _open_ classes, similiar to the standard OpenStruct, 
+and variations of the standard Hash.
+
+
+== RELEASE NOTES
+
+Please see the HISTORY file.
+
+
+== HOW TO USE
+
+For usage information, see the individual library files include
+in this collection.
+
+
+== HOW TO INSTALL
+
+To install with RubyGems simply open a console and type:
+
+  $ sudo gem install hashery
+
+Tarball packages are available for manual site installations
+via <a href="http://proutils.github.com/setup">Setup.rb</a>.
+
+
+== LICENSE
+
+Copyright (c) 2005,2010 Thomas Sawyer
+
+This program is ditributed unser the terms of the MIT license.
+
+See LICENSE file for details.
+

data/ROADMAP.rdoc

@@ -0,0 +1,13 @@
+= ROADMAP
+
+== 1.1.0
+
+* Improve test coverage.
+* Consider using Hashery:: namespace.
+* Should Stash have a more explict name?
+
+== 1.2.0
+
+* Add a defined property Hash. Needed?
+* Any other Hash-like classes to add?
+

data/lib/hashery.rb

@@ -0,0 +1,13 @@
+require 'hashery/castinghash'
+require 'hashery/dictionary'
+require 'hashery/lruhash'
+require 'hashery/memoizer'
+require 'hashery/opencascade'
+require 'hashery/openhash'
+require 'hashery/openobject'
+require 'hashery/orderedhash'
+require 'hashery/ostructable'
+require 'hashery/queryhash'
+require 'hashery/stash'
+require 'hashery/statichash'
+

data/lib/hashery/castinghash.rb

@@ -0,0 +1,171 @@
+# CastingHash is just like Hash, except that all keys and values
+# are passed through casting procedures.
+#--
+# TODO: Handle default_proc.
+#++
+class CastingHash < 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.to_proc || VAL_PROC
+    hash.each{ |k,v| self[k] = v }
+  end
+
+  #
+  def key_proc
+    @key_proc
+  end
+
+  #
+  def key_proc=(proc)
+    @key_proc = proc.to_proc
+  end
+
+  #
+  def value_proc
+    @value_proc
+  end
+
+  #
+  def value_proc=(proc)
+    @value_proc = proc.to_proc
+  end
+
+  #
+  def [](k)
+    super(key_proc[k])
+  end
+
+  #
+  def []=(k,v)
+    super(key_proc[k], value_proc[v])
+  end
+
+  #
+  def <<(other)
+    case other
+    when Hash
+      super(cast(other))
+    when Array
+      self[other[0]] = other[1]
+    else
+      raise ArgumentError
+    end
+  end
+
+  def fetch(k)
+    super(key_proc[k])
+  end
+
+  #
+  def store(k, v)
+    super(key_proc[k], value_proc[v])
+  end
+
+  #
+  def key?(k)
+    super(key_proc[k])
+  end
+
+  #
+  def has_key?(k)
+    super(key_proc[k])
+  end
+
+  # 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
+      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
+
+    #
+    def cast(hash)
+      h
+      hash.each do |k,v|
+        h[key_proc[k]] = value_proc[v]
+      end
+      h
+    end
+
+end
+
+
+#class Hash
+#
+#  # Convert a Hash to a CastingHash.
+#  def to_casting_hash(value_cast=nil, &key_cast)
+#    CastingHash.new(self, value_cast, &key_cast)
+#  end
+#
+#end

data/lib/hashery/dictionary.rb

@@ -0,0 +1,430 @@
+# = Dictionary.rb
+#
+# Copyright (c) 2005, 2009 Jan Molic, Thomas Sawyer
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+# == Acknowledgments
+#
+# * Andrew Johnson (merge, to_a, inspect, shift and Hash[])
+# * Jeff Sharpe    (reverse and reverse!)
+# * Thomas Leitner (has_key? and key?)
+#
+# Ported from OrderHash 2.0, Copyright (c) 2005 Jan Molic
+
+# = 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.
+#
+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.
+    #
+    #   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
+  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)
+    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
+
+  # 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
+
+  # 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 }
+
+  def order_by_value
+    @order_by = lambda { |k,v| v }
+    order
+    self
+  end
+
+  #
+  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
+
+  #def ==( hsh2 )
+  #  return false if @order != hsh2.order
+  #  super hsh2
+  #end
+
+  def ==(hsh2)
+    if hsh2.is_a?( Dictionary )
+      @order == hsh2.order &&
+      @hash  == hsh2.instance_variable_get("@hash")
+    else
+      false
+    end
+  end
+
+  def [] k
+    @hash[ k ]
+  end
+
+  def fetch(k, *a, &b)
+    @hash.fetch(k, *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 insert( i,k,v )
+    @order.insert( i,k )
+    @hash.store( k,v )
+  end
+
+  def store( a,b )
+    @order.push( a ) unless @hash.has_key?( a )
+    @hash.store( a,b )
+  end
+
+  def clear
+    @order = []
+    @hash.clear
+  end
+
+  def delete( key )
+    @order.delete( key )
+    @hash.delete( key )
+  end
+
+  def each_key
+    order.each { |k| yield( k ) }
+    self
+  end
+
+  def each_value
+    order.each { |k| yield( @hash[k] ) }
+    self
+  end
+
+  def each
+    order.each { |k| yield( k,@hash[k] ) }
+    self
+  end
+  alias each_pair each
+
+  def delete_if
+    order.clone.each { |k| delete k if yield(k,@hash[k]) }
+    self
+  end
+
+  def values
+    ary = []
+    order.each { |k| ary.push @hash[k] }
+    ary
+  end
+
+  def keys
+    order
+  end
+
+  def invert
+    hsh2 = self.class.new
+    order.each { |k| hsh2[@hash[k]] = k }
+    hsh2
+  end
+
+  def reject(&block)
+    self.dup.delete_if(&block)
+  end
+
+  def reject!( &block )
+    hsh2 = reject(&block)
+    self == hsh2 ? nil : hsh2
+  end
+
+  def replace(hsh2)
+    case hsh2
+    when Hash
+      @order = hsh2.keys
+      @hash  = hsh2
+    else
+      @order = hsh2.order
+      @hash  = hsh2.hash
+    end
+    reorder
+  end
+
+  def shift
+    key = order.first
+    key ? [key,delete(key)] : super
+  end
+
+  def unshift( k,v )
+    unless @hash.include?( k )
+      @order.unshift( k )
+      @hash.store( k,v )
+      true
+    else
+      false
+    end
+  end
+
+  def <<(kv)
+    push(*kv)
+  end
+
+  def push( k,v )
+    unless @hash.include?( k )
+      @order.push( k )
+      @hash.store( k,v )
+      true
+    else
+      false
+    end
+  end
+
+  def pop
+    key = order.last
+    key ? [key,delete(key)] : nil
+  end
+
+  def inspect
+    ary = []
+    each {|k,v| ary << k.inspect + "=>" + v.inspect}
+    '{' + ary.join(", ") + '}'
+  end
+
+  def dup
+    a = []
+    each{ |k,v| a << k; a << v }
+    self.class[*a]
+  end
+
+  def update( hsh2 )
+    hsh2.each { |k,v| self[k] = v }
+    reorder
+    self
+  end
+  alias :merge! update
+
+  def merge( hsh2 )
+    self.dup.update(hsh2)
+  end
+
+  def select
+    ary = []
+    each { |k,v| ary << [k,v] if yield k,v }
+    ary
+  end
+
+  def reverse!
+    @order.reverse!
+    self
+  end
+
+  def reverse
+    dup.reverse!
+  end
+
+  #
+  def first(x=nil)
+    return @hash[order.first] unless x
+    order.first(x).collect { |k| @hash[k] }
+  end
+
+  #
+  def last(x=nil)
+    return @hash[order.last] unless x
+    order.last(x).collect { |k| @hash[k] }
+  end
+
+  def length
+    @order.length
+  end
+  alias :size :length
+
+  def empty?
+    @hash.empty?
+  end
+
+  def has_key?(key)
+    @hash.has_key?(key)
+  end
+
+  def key?(key)
+    @hash.key?(key)
+  end
+
+  def to_a
+    ary = []
+    each { |k,v| ary << [k,v] }
+    ary
+  end
+
+  def to_s
+    self.to_a.to_s
+  end
+
+  def to_hash
+    @hash.dup
+  end
+
+  def to_h
+    @hash.dup
+  end
+end