facets 2.9.1 → 2.9.2

data/src/core/facets/hash/to_h.rb

@@ -0,0 +1 @@
+require 'facets/to_hash'

data/src/core/facets/hash/to_mod.rb

@@ -0,0 +1,33 @@
+class Hash
+
+  # Convert a hash into a module.
+  #
+  #   {:a=>1, :b=>2}.to_mod
+  #
+  # Can take a block accepting key, value pairs which will be
+  # evaluated in the context of the module.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   m = h.to_mod{ |k,v| module_function k }
+  #   m.a #=> 1
+  #   m.b #=> 2
+  #
+  # CREDIT: Jay Fields
+  #--
+  # TODO: Consider #to_obj?
+  #++
+
+  def to_mod(&block)
+    hash = self
+    Module.new do
+      hash.each do |key, value|
+        define_method key do
+          value #.to_object
+        end
+        instance_exec(key, value, &block) if block
+      end
+    end
+  end
+
+end
+

data/src/core/facets/hash/to_options.rb

@@ -0,0 +1 @@
+require 'facets/hash/symbolize_keys'

data/src/core/facets/hash/to_proc.rb

@@ -0,0 +1,39 @@
+class Hash
+
+  # Constructs a Proc object from a hash such that the parameter
+  # of the Proc is assigned the hash keys as attributes.
+  #
+  #   c = Class.new do
+  #     attr_accessor :a
+  #   end
+  #
+  #   h = {:a => 1}
+  #   o = c.new
+  #   h.to_proc.call(o)
+  #   o.a  #=> 1
+  #
+  # If +response+ is set to +true+, then assignment will only occur
+  # if receiver responds_to? the writer method.
+  #
+  # CREDIT: Trans
+
+  def to_proc(response=false)
+    if response
+      lambda do |o|
+        self.each do |k,v|
+          ke = "#{k}="
+          o.__send__(ke, v) if respond_to?(ke)
+        end
+      end
+    else
+      lambda do |o|
+        self.each do |k,v|
+          ke = "#{k}="
+          o.__send__(ke, v)
+        end
+      end
+    end
+  end
+
+end
+

data/src/core/facets/hash/to_struct.rb

@@ -0,0 +1,17 @@
+class Hash
+
+  # A method to convert a Hash into a Struct.
+  #
+  #   h = {:name=>"Dan","age"=>33,"rank"=>"SrA","grade"=>"E4"}
+  #   s = h.to_struct("Foo")
+  #
+  # TODO: Is this robust enough considerd hashes aren't ordered?
+  #
+  # CREDIT: Daniel Berger
+
+  def to_struct(struct_name)
+    Struct.new(struct_name,*keys).new(*values)
+  end
+
+end
+

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

@@ -0,0 +1,47 @@
+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", "C"=>{"X"=>"X"}}
+  #
+  #   g = h.traverse{ |k,v| [k.downcase, v] }
+  #
+  #   g  #=> {"a"=>"A", "b"=>"B", "c"=>{"x"=>"X"}}
+  #
+  # NOTE: Hash#traverse is the same as `recursive.graph` and
+  # might be deprecated in the future (if it ever works!)
+  #
+  # CREDIT: Trans
+
+  def traverse(&block)
+    inject({}) do |h,(k,v)|
+      if Hash === v
+        v = v.traverse(&block)
+      elsif v.respond_to?(:to_hash)
+        v = v.to_hash.traverse(&block)
+      end
+      nk, nv = block.call(k,v)
+      h[nk] = 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" }
+  #
+  # CREDIT: Trans
+
+  def traverse!(&block)
+    replace(traverse(&block))
+  end
+
+end
+

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

@@ -0,0 +1,6 @@
+# -- for backward compatibility. To be deprecated.
+require 'facets/hash/op_push'
+require 'facets/hash/update_each'
+require 'facets/hash/update_keys'
+require 'facets/hash/update_values'
+

data/src/core/facets/hash/update_each.rb

@@ -0,0 +1,18 @@
+class Hash
+
+  # Iterates through each pair and updates a the hash
+  # 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 do |k,v|
+     update(yield(k,v))
+    end
+    self
+  end
+
+end
+

data/src/core/facets/hash/update_keys.rb

@@ -0,0 +1,20 @@
+class Hash
+
+  # Iterate over hash updating just the keys.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   h.update_keys{ |k| "#{k}!" }
+  #   h  #=> { "a!"=>1, "b!"=>2 }
+  #
+  # CREDIT: Trans
+
+  def update_keys #:yield:
+    if block_given?
+      keys.each { |old_key| store(yield(old_key), delete(old_key)) }
+    else
+      to_enum(:update_keys)
+    end
+  end
+
+end
+

data/src/core/facets/hash/update_values.rb

@@ -0,0 +1,20 @@
+class Hash
+
+  # Iterate over hash updating just the values.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   h.update_values{ |v| v + 1 }
+  #   h  #=> { :a=>2, :b=>3 }
+  #
+  # CREDIT: Trans
+
+  def update_values #:yield:
+    if block_given?
+      each{ |k,v| store(k, yield(v)) }
+    else
+      to_enum(:update_values)
+    end
+  end
+
+end
+

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

@@ -0,0 +1,76 @@
+class Hash
+
+  # 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: ...
+  #
+  #   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
+  #
+  # Here is a basic example:
+  #
+  #   h1 = { :a => 1, :b => [ 1 ], :c => { :x => 1 } }
+  #   h2 = { :a => 2, :b => [ 2 ], :c => { :x => 2 } }
+  #
+  #   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
+    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

data/src/core/facets/hash/zip.rb

@@ -0,0 +1,18 @@
+class Hash
+
+  # Creates a new hash from two separate arrays, a +keys+ array and
+  # a +values+ array.
+  #
+  #   Hash.zip(["a","b","c"], [1,2,3])
+  #   # => { "a"=>1, "b"=>2, "c"=>3 }
+  #
+  # CREDIT: Trans, Ara T. Howard
+
+  def self.zip(keys,values) # or some better name
+    h = {}
+    keys.size.times{ |i| h[ keys[i] ] = values[i] }
+    h
+  end
+
+end
+

data/src/core/facets/indexable.rb

@@ -0,0 +1,270 @@
+# = Indexable
+#
+# 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.
+#
+# NOTE: To test the folowing methods Indexable needs to be
+# included into Array and array must have #splice defined.
+#
+#   require 'facets/array/splice'
+#
+#   class ::Array
+#     include Indexable
+#   end
+# 
+# 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 an Array of the middle element(s) of an array.
+  # Even-sized arrays, not having an exact middle, return
+  # 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]
+  #
+  # A +birth+ can be give to widen the middle on either side.
+  #
+  #   [1,2,3,4,5].middle(1)   #=> [2,3,4]
+  #   [1,2,3,4,5,6].middle(1)   #=> [2,3,4,5]
+  #
+  # In contrast to #mid which utilizes an offset.
+  #
+  def middle(birth=0)
+    i = size / 2 - birth
+    if size % 2 == 0
+      slice(i - 1, 2 + (2 * birth))
+    else
+      slice(i, 1 + (2 * birth))
+    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]
+  #
+  #   [1,2,3,4,5].thru(2)  #=> [1,2,3]
+  #   [1,2,3,4,5].thru(4)  #=> [1,2,3,4,5]
+  #
+  def thru(from, to=nil)
+    from, to = 0, from unless to
+    to = size - 1 if to >= size
+    a = []
+    i = from
+    while i <= to
+      a << slice(i)
+      i += 1
+    end
+    a
+  end
+
+  # Returns last _n_ elements.
+  #
+  #   %w{W o r l d}.from(3)  #=> %w{l d}
+  #
+  def from(i)
+    return self if i >= size
+    slice(i, size - i) #slice(-n..-1)
+  end
+
+  ## DEPRECATED: use #thru instead
+  ## Returns first _n_ elements.
+  ##
+  ##   %w{H e l l o}.upto(3)  #=> %w{H e l l}
+  ##
+  ##def upto(n)
+  ##  slice(0, n.to_i+1)
+  ##end
+
+  # Returns first _n_ elements.
+  #
+  #   %w{H e l l o}.first(3)  #=> %w{H e l}
+  #
+  def first(n=1)
+    slice(0, n.to_i)
+  end
+
+  # Returns last _n_ elements.
+  #
+  #   %w{H e l l o}.last(3)  #=> %w{l l o}
+  #
+  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"
+  #   a           #=> ["x","y","z"]
+  #
+  def first=(x)
+    splice(0,x)
+  end
+
+  # Change the last element.
+  #
+  #   a = [1,2,5]
+  #   a.last = 3
+  #   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
+
+  # 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
+
+  # Returns the index of the first element equal to the
+  # given object or satisfying the block condition.
+  #
+  #   [1,2,3,4].index{ |e| e == 3 }  #=> 2
+  #   [1,2,3,4].index{ |e| e > 3 }   #=> 3
+  #
+  def index(obj=nil, &block)
+    if block_given?
+      size.times do |i|
+        return i if yield(slice(i))
+      end
+    else
+      size.times do |i|
+        return i if obj == slice(i)
+      end
+    end
+    nil
+  end
+
+  # to be deprecated
+  alias_method :index_of, :index
+
+  # 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..3)
+  #
+  def range(a=nil,z=-1)
+    if a
+      index(a)..index(z)
+    else
+      (0..(size-1))
+    end
+  end
+
+end
+