facets 2.1.3 → 2.2.0

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

@@ -1,16 +1,3 @@
-# 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,
@@ -21,10 +8,14 @@ class Hash
   #   g = h.traverse { |k,v| [k.downcase, v] }
   #   g  #=> { "a"=>"A", "b"=>"B" }
   #
+  #
+  #   CREDIT: Trans
+  #
   #--
   # 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 )
@@ -41,41 +32,10 @@ class Hash
   #   h.traverse! { |k,v| [k.downcase, v] }
   #   h  #=> { "a"=>"A", "b"=>"B" }
   #
+  #   CREDIT: Trans
+
   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

@@ -1,93 +1,53 @@
-# 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.
+  #
+  #   CREDIT: Trans
+
   def replace_each  # :yield:
-    dup.each_pair{ |k,v| delete( k ); update( yield(k,v) ); }
+    dup.each do |k,v|
+      delete(k)
+      update(yield(k,v))
+    end
     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.
-  #++
+  # in place. This is formally equivalent to #mash!
+  # But does not use #mash to accomplish the task.
+  # Hence #update_each is probably a touch faster.
+  #
+  #  CREDIT: Trans
 
   def update_each  # :yield:
-    dup.each_pair{ |k,v| update( yield(k,v) ); }
+    dup.each do |k,v|
+     update(yield(k,v))
+    end
     self
   end
 
+  # Iterate over hash updating kust the keys.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   h.update_keys{ |k,v| "#{k}#{v}" }
+  #   h  #=> { "a1"=>2, "b2"=>3 }
   #
+  #  CREDIT: Trans
 
   def update_keys #:yield:
     each{ |k,v| delete(k) ; store(yield(k), v) }
   end
 
+  # Iterate over hash updating just the values.
   #
+  #   h = {:a=>1, :b=>2}
+  #   h.update_values{ |k,v| v+1 }
+  #   h  #=> { a:=>2, :b=>3 }
+  #
+  #  CREDIT: Trans
 
   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

@@ -1,21 +1,12 @@
-# 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:
+  # 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.
+  #
+  # Two hashes are weaved together to produce a new hash.
+  # The two hashes need to be compatible according to the
+  # following rules for each node:
   #
   #   <tt>
   #   hash,   hash    => hash (recursive +)
@@ -29,10 +20,23 @@ class Hash
   #   value1, value2  => value2
   #   </tt>
   #
-  # Example:
+  # Here is a basic example:
+  #
+  #   h1 = { :a => 1, :b => [ 1 ], :c => { :x => 1 } }
+  #   => {:b=>[1], :c=>{:x=>1}, :a=>1}
+  #
+  #   h2 = { :a => 2, :b => [ 2 ], :c => { :x => 2 } }
+  #   => {:b=>[2], :c=>{:x=>2}, :a=>2}
   #
-  #   # to do
+  #   h1.weave(h2)
+  #   => {:b=>[1, 2], :c=>{:x=>2}, :a=>2}
   #
+  # Weave follows the most expected pattern of unifying two complex
+  # hashes. It is especially useful for implementing overridable
+  # configuration schemes.
+  #
+  #   CREDIT: Thomas Sawyer
+
   def weave(h)
     raise ArgumentError, "Hash expected" unless h.kind_of?(Hash)
     s = self.clone
@@ -75,27 +79,3 @@ class Hash
   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

@@ -16,7 +16,19 @@
 #
 # AUTHORS:
 #
-#   CREDIT THomas Sawyer
+#   - Thomas Sawyer
+
+# Indexable is a mixin that provides index based methods,
+# working soley with four methods: #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.
 
 module Indexable
 
@@ -24,7 +36,7 @@ module Indexable
   # in a new array.
   #
   #   [1,2,3].head  #=> [1]
-  #
+
   def head
     slice(0,1)
   end
@@ -32,7 +44,7 @@ module Indexable
   # Returns an array from second element to last element.
   #
   #   [1,2,3].tail  #=> [2,3]
-  #
+
   def tail
     slice(1,length-1)
   end
@@ -41,7 +53,7 @@ module Indexable
   # in an array.
   #
   #   [1,2,3].foot  #=> [3]
-  #
+
   def foot
     slice(-1,1)
   end
@@ -54,6 +66,7 @@ module Indexable
   #--
   # Better name for this? (bulk, perhaps?)
   #++
+
   def body
     slice(0,size-1)
   end
@@ -71,6 +84,7 @@ module Indexable
   # 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
@@ -83,6 +97,7 @@ module Indexable
   #   [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 )
@@ -96,7 +111,7 @@ module Indexable
   #
   #   [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
@@ -110,7 +125,7 @@ module Indexable
   # Returns first _n_ elements.
   #
   #   "Hello World".first(3)  #=> "Hel"
-  #
+
   def first(n=1)
     slice(0, n.to_i)
   end
@@ -118,7 +133,7 @@ module Indexable
   # Returns last _n_ elements.
   #
   #   "Hello World".last(3)  #=> "rld"
-  #
+
   def last(n=1)
     n = n.to_i
     return self if n > size
@@ -130,7 +145,7 @@ module Indexable
   #   a = ["a","y","z"]
   #   a.first = "x"
   #   p a           #=> ["x","y","z"]
-  #
+
   def first=(x)
     splice(0,x)
   end
@@ -140,19 +155,27 @@ module Indexable
   #   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.
   #
+  #   a = [1,2,3]
+  #   a.first!      #=> 1
+  #   a             #=> [2,3]
+
   def first!
     splice(0)
   end
 
   # Remove and return the last element.
   #
+  #   a = [1,2,3]
+  #   a.last!       #=> 3
+  #   a             #=> [1,2]
+
   def last!
     splice(-1)
   end
@@ -164,6 +187,7 @@ module Indexable
   #   [1,2,3,4,5].ends  #=> 4
   #
   # This nearly equivalent to +size - 1+.
+
   def ends
     return nil if size == 0
     size - 1
@@ -174,7 +198,7 @@ module Indexable
   #
   #   [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
@@ -183,9 +207,13 @@ module Indexable
     end
   end
 
-  # TODO Remove Array#index_of when future Ruby adds block to #index.
-
-  # Allows block usage with index.
+  # Returns the index of the first element to satisfy the block
+  # condition. This is simply #index with a block.
+  #
+  #   [1,2,3,4].index_of { |e| e == 3 }  #=> 2
+  #   [1,2,3,4].index_of { |e| e > 3 }   #=> 3
+  #
+  # TODO: Remove Array#index_of when Ruby 1.9 adds block to #index.
 
   def index_of(obj=nil,&blk)
     return index(obj) unless block_given?
@@ -201,7 +229,7 @@ module Indexable
   #
   #   ['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)