facets 1.8.54 → 2.0.0

data/lib/core/facets/hash/traverse.rb

@@ -0,0 +1,81 @@
+# TITLE:
+#
+#   Hash Traversal Extensions
+#
+# SUMMARY:
+#
+#   Traversal extensions for Hash class.
+#
+# CREDITS:
+#
+#   - Thomas Sawyer
+
+#
+class Hash
+
+  # Returns a new hash created by traversing the hash and its subhashes,
+  # executing the given block on the key and value. The block should
+  # return a 2-element array of the form +[key, value]+.
+  #
+  #   h = { "A"=>"A", "B"=>"B" }
+  #   g = h.traverse { |k,v| [k.downcase, v] }
+  #   g  #=> { "a"=>"A", "b"=>"B" }
+  #
+  #--
+  # TODO Testing value to see if it is a Hash also catches subclasses of Hash.
+  #      This is probably not the right thing to do and should catch Hashes only (?)
+  #++
+  def traverse(&b)
+    inject({}) do |h,(k,v)|
+      v = ( Hash === v ? v.traverse(&b) : v )
+      nk, nv = b[k,v]
+      h[nk] = nv #( Hash === v ? v.traverse(base,&b) : nv )
+      h
+    end
+  end
+
+  # In place version of traverse, which traverses the hash and its
+  # subhashes, executing the given block on the key and value.
+  #
+  #   h = { "A"=>"A", "B"=>"B" }
+  #   h.traverse! { |k,v| [k.downcase, v] }
+  #   h  #=> { "a"=>"A", "b"=>"B" }
+  #
+  def traverse!(&b)
+    self.replace( self.traverse(&b) )
+  end
+
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+
+  require 'test/unit'
+
+  class TestHashTraverse < Test::Unit::TestCase
+
+    def test_traverse
+      h = { "A" => "x", "B" => "y" }
+      h2 = h.traverse { |k,v| [k.downcase, v.upcase] }
+      e = { "a" => "X", "b" => "Y" }
+      assert_not_equal( h, h2 )
+      assert_equal( e, h2 )
+    end
+
+    def test_traverse!
+      h = { "A" => "x", "B" => "y" }
+      h.traverse! { |k,v| [k.downcase, v.upcase] }
+      e = { "a" => "X", "b" => "Y" }
+      assert_equal( e, h )
+    end
+
+  end
+
+=end

data/lib/core/facets/hash/update.rb

@@ -0,0 +1,93 @@
+# TITLE:
+#
+#   Hash Update Extensions
+#
+# SUMMARY:
+#
+#   Update related extensions for Hash class.
+#
+# CREDITS:
+#
+#   - Thomas Sawyer
+
+#
+class Hash
+
+  # Same as #update_each, but deletes the key element first.
+  def replace_each  # :yield:
+    dup.each_pair{ |k,v| delete( k ); update( yield(k,v) ); }
+    self
+  end
+
+  # Iterates through each pair and updates a the hash
+  # in place. This is formally equivalent to #collate!
+  # But does not use #collate to accomplish the task.
+  # Hence #update_each is probably a bit faster.
+  #--
+  # Note that this may get some fine tuning as currently
+  # it expects the block to return a "mini-hash" pair.
+  #++
+
+  def update_each  # :yield:
+    dup.each_pair{ |k,v| update( yield(k,v) ); }
+    self
+  end
+
+  #
+
+  def update_keys #:yield:
+    each{ |k,v| delete(k) ; store(yield(k), v) }
+  end
+
+  #
+
+  def update_values #:yield:
+    each{ |k,v| store(k, yield(v)) }
+  end
+
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+
+  require 'test/unit'
+
+  class TestHashUpdate < Test::Unit::TestCase
+
+    def test_replace_each
+      a = { :a => 1, :b => 2, :c => 3 }
+      e = { :a => 2, :b => 3, :c => 4 }
+      a.replace_each{ |k,v| { k => v+1 } }
+      assert_equal( e, a )
+    end
+
+    def test_update_each
+      a = { :a => 1, :b => 2, :c => 3 }
+      e = { :a => 2, :b => 3, :c => 4 }
+      a.update_each{ |k,v| { k => v+1 } }
+      assert_equal( e, a )
+    end
+
+    def test_update_keys
+      h = { 'A' => 1, 'B' => 2 }
+      h.update_keys{ |k| k.downcase }
+      assert_equal( { 'a' => 1, 'b' => 2 }, h)
+    end
+
+    def test_update_values
+      h = { 1 => 'A', 2 => 'B' }
+      h.update_values{ |v| v.downcase }
+      assert_equal( { 1 => 'a', 2 => 'b' }, h )
+    end
+
+  end
+
+=end
+

data/lib/core/facets/hash/weave.rb

@@ -0,0 +1,101 @@
+# TITLE:
+#
+#   Hash Weave Extension
+#
+# SUMMARY:
+#
+#   Weave is a very uniqe hash operator. I is designed
+#   to merge to complex hashes in according to sensible,
+#   regular pattern. The effect is akin to inheritance.
+#
+# CREDITS:
+#
+#   - Thomas Sawyer
+
+class Hash
+
+  # Weaves two hashes producing a new hash. The two hashes need
+  # to be compatible according to the following rules for each node:
+  #
+  #   <tt>
+  #   hash,   hash    => hash (recursive +)
+  #   hash,   array   => error
+  #   hash,   value   => error
+  #   array,  hash    => error
+  #   array,  array   => array + array
+  #   array,  value   => array << value
+  #   value,  hash    => error
+  #   value,  array   => array.unshift(valueB)
+  #   value1, value2  => value2
+  #   </tt>
+  #
+  # Example:
+  #
+  #   # to do
+  #
+  def weave(h)
+    raise ArgumentError, "Hash expected" unless h.kind_of?(Hash)
+    s = self.clone
+    h.each { |k,node|
+      node_is_hash = node.kind_of?(Hash)
+      node_is_array = node.kind_of?(Array)
+      if s.has_key?(k)
+        self_node_is_hash = s[k].kind_of?(Hash)
+        self_node_is_array = s[k].kind_of?(Array)
+        if self_node_is_hash
+          if node_is_hash
+            s[k] = s[k].weave(node)
+          elsif node_is_array
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          else
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          end
+        elsif self_node_is_array
+          if node_is_hash
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          elsif node_is_array
+            s[k] += node
+          else
+            s[k] << node
+          end
+        else
+          if node_is_hash
+            raise ArgumentError, 'Incompatible hash addition' #self[k] = node
+          elsif node_is_array
+            s[k].unshift( node )
+          else
+            s[k] = node
+          end
+        end
+      else
+        s[k] = node
+      end
+    }
+    s
+  end
+
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+
+  require 'test/unit'
+
+  class TestHashWeave < Test::Unit::TestCase
+
+    def test_weave
+      b = { :a=>1, :b=>[1,2,3], :c=>{ :x=>'X' } }
+      c = { :a=>2, :b=>[4,5,6], :c=>{ :x=>'A', :y => 'B' } }
+      r = { :a=>2, :b=>[1,2,3,4,5,6], :c=>{ :x => 'A', :y => 'B' } }
+      assert_equal( r, b.weave(c) )
+    end
+
+  end
+
+=end

data/lib/core/facets/indexable.rb

@@ -0,0 +1,213 @@
+# TITLE:
+#
+#   Indexable
+#
+# DESCRIPTION:
+#
+#   Mixin that works off of #index, #slice, #splice and #size.
+#
+#   These methods work in harmony. Where #index returns a
+#   position of a given element, #slice returns elements
+#   for given positions. #splice is like #slice but replaces
+#   the given position with new values. This mehtod is not
+#   part of ruby core, but it generally just an alias for #[]=,
+#   just as #slice is an alias of #[]. #size of course simply
+#   returns the total length of the indexable object.
+#
+# AUTHORS:
+#
+#   CREDIT THomas Sawyer
+
+module Indexable
+
+  # Like #first but returns the first element
+  # in a new array.
+  #
+  #   [1,2,3].head  #=> [1]
+  #
+  def head
+    slice(0,1)
+  end
+
+  # Returns an array from second element to last element.
+  #
+  #   [1,2,3].tail  #=> [2,3]
+  #
+  def tail
+    slice(1,length-1)
+  end
+
+  # Like #last, returning the last element
+  # in an array.
+  #
+  #   [1,2,3].foot  #=> [3]
+  #
+  def foot
+    slice(-1,1)
+  end
+
+  # Returns an array of the first element upto,
+  # but not including, the last element.
+  #
+  #   [1,2,3].body  #=> [1,2]
+  #
+  #--
+  # Better name for this? (bulk, perhaps?)
+  #++
+  def body
+    slice(0,size-1)
+  end
+
+  # Returns the middle element of an array, or the element offset
+  # from middle if the parameter is given. Even-sized arrays,
+  # not having an exact middle, return the middle-right element.
+  #
+  #   [1,2,3,4,5].mid        #=> 3
+  #   [1,2,3,4,5,6].mid      #=> 4
+  #   [1,2,3,4,5,6].mid(-1)  #=> 3
+  #   [1,2,3,4,5,6].mid(-2)  #=> 2
+  #   [1,2,3,4,5,6].mid(1)   #=> 5
+  #
+  # In other words, If there are an even number of elements the
+  # higher-indexed of the two center elements is indexed as
+  # orgin (0).
+  def mid(offset=0)
+    slice((size / 2) + offset)
+  end
+
+  # Returns the middle element(s) of an array. Even-sized arrays,
+  # not having an exact middle, returns a two-element array
+  # of the two middle elements.
+  #
+  #   [1,2,3,4,5].middle        #=> 3
+  #   [1,2,3,4,5,6].middle      #=> [3,4]
+  #
+  # In contrast to #mid which utilizes an offset.
+  def middle
+    if size % 2 == 0
+     slice( (size / 2) - 1, 2 )
+     #[slice((size / 2) - 1, 1), slice(size / 2, 1)]
+    else
+      slice(size / 2)
+    end
+  end
+
+  # Fetch values from a start index thru an end index.
+  #
+  #   [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
+  #   [1,2,3,4,5].thru(2,4)  #=> [3,4,5]
+  #
+  def thru(from, to)
+    a = []
+    i = from
+    while i <= to
+      a << slice(i)
+      i += 1
+    end
+    a
+  end
+
+  # Returns first _n_ elements.
+  #
+  #   "Hello World".first(3)  #=> "Hel"
+  #
+  def first(n=1)
+    slice(0, n.to_i)
+  end
+
+  # Returns last _n_ elements.
+  #
+  #   "Hello World".last(3)  #=> "rld"
+  #
+  def last(n=1)
+    n = n.to_i
+    return self if n > size
+    slice(-n, n) #slice(-n..-1)
+  end
+
+  # Change the first element.
+  #
+  #   a = ["a","y","z"]
+  #   a.first = "x"
+  #   p a           #=> ["x","y","z"]
+  #
+  def first=(x)
+    splice(0,x)
+  end
+
+  # Change the last element.
+  #
+  #   a = [1,2,5]
+  #   a.last = 3
+  #   p a           #=> [1,2,3]
+  #
+  def last=(x)
+    splice(-1,x)
+  end
+
+  # Remove and return the first element.
+  #
+  def first!
+    splice(0)
+  end
+
+  # Remove and return the last element.
+  #
+  def last!
+    splice(-1)
+  end
+
+  # A shorting of "ends at", returns the
+  # last index of the indexable object.
+  # Returns nil if there are no elements.
+  #
+  #   [1,2,3,4,5].ends  #=> 4
+  #
+  # This nearly equivalent to +size - 1+.
+  def ends
+    return nil if size == 0
+    size - 1
+  end
+
+  # Returns the positive ordinal index given
+  # a cardinal position, 1 to n or -n to -1.
+  #
+  #   [1,2,3,4,5].pos(1)   #=> 0
+  #   [1,2,3,4,5].pos(-1)  #=> 4
+  #
+  def pos(i)
+    if i > 0
+      return i - 1
+    else
+      size + i
+    end
+  end
+
+  # TODO Remove Array#index_of when future Ruby adds block to #index.
+
+  # Allows block usage with index.
+
+  def index_of(obj=nil,&blk)
+    return index(obj) unless block_given?
+    i=0; i+=1 until yield(self[i])
+    return i
+  end
+
+  # TODO Maybe #range could use a little error catch code (todo).
+
+  # Returns the index range between two elements.
+  # If no elements are given, returns the range
+  # from first to last.
+  #
+  #   ['a','b','c','d'].range            #=> 0..3
+  #   ['a','b','c','d'].range('b','d')   #=> 1..2
+  #
+  def range(a=nil,z=nil)
+    if !a
+      0..(size-1)
+    else
+      index(a)..index(z)
+    end
+  end
+
+end