facets 2.8.4 → 2.9.0.pre.1

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

@@ -1,12 +1,16 @@
 class Hash
 
-  # In-place version of Hash#select.  The opposite of the built-in
-  # Hash#reject!.
-  #
-  # CREDIT: Gavin Sinclair, Noah Gibbs
+  unless method_defined?(:select!)
+
+    # In-place version of Hash#select.  The opposite of the built-in
+    # Hash#reject!.
+    #
+    # CREDIT: Gavin Sinclair, Noah Gibbs
+
+    def select!
+      reject! { |k,v| not yield(k,v) }
+    end
 
-  def select!
-    reject! { |k,v| not yield(k,v) }
   end
 
 end

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

@@ -1,32 +1,31 @@
-require "facets/hash/except"
-
 class Hash
 
-  unless defined?(::ActiveSupport)  # ActiveSupport
-
-    # Returns a new hash with only the given keys.
-
-    def slice(*keep_keys)
-      h = {}
-      keep_keys.each do |key|
-        h[key] = fetch(key)
-      end
-      h
-    end
-
-    # Replaces hash with a new hash having only the given keys.
-    # This return the hash of keys removed.
-    #
-    #   h = {:a=>1, :b=>2}
-    #   h.slice!(:a)  #=> {:a=>1}
-    #   h             #=> {:b=>2}
-    #
-    def slice!(*keep_keys)
-      removed = except(*keep_keys)
-      replace(slice(*keep_keys))
-      removed
+  # Returns a new hash with only the given keys.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   h.slice(:a)  #=> {:a=>1}
+  #
+  def slice(*keep_keys)
+    hash = {}
+    keep_keys.each do |key|
+      hash[key] = fetch(key)
     end
+    hash
+  end
 
+  # Replaces hash with a new hash having only the given keys.
+  # This return the hash of keys removed.
+  #
+  #   h = {:a=>1, :b=>2}
+  #   h.slice!(:a)  #=> {:b=>2}
+  #   h             #=> {:a=>1}
+  #
+  # Returns a Hash of the removed pairs.
+  def slice!(*keep_keys)
+    rejected = keys - keep_keys
+    removed = {}
+    rejected.each{ |k| removed[k] = delete(k) }
+    removed
   end
 
 end

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

@@ -1,93 +1,91 @@
-require 'facets/hash/rekey'
-
 class Hash
 
-  # NOTE: These are in disfavor, but are provided
-  # because of their prevalence with Rails users.
+  # NOTE: These are provided because of their prevalence with Rails users.
   # We strongly encourage using #rekey instead.
 
-  unless defined?(::ActiveSupport)
-
-    # Converts all keys in the Hash to Symbols, returning a new Hash.
-    # With a +filter+, limits conversion to only a certain selection of keys.
-    #
-    #   foo = { :name=>'Gavin', 'wife'=>:Lisa }
-    #   foo.symbolize_keys    #=>  { :name=>"Gavin", :wife=>:Lisa }
-    #   foo.inspect           #=>  { "name" =>"Gavin", "wife"=>:Lisa }
-    #
-    # This method is considered archaic. Use #rekey instead.
 
-    def symbolize_keys(&filter)
-      if filter
-        rekey{ |k| filter[k] ? k.to_sym : nil }
-      else
-        rekey{ |k| k.to_sym }
-      end
-    end
+  # Return a new hash with all keys converted to symbols. With a +select+ block,
+  # limits conversion to only a certain selection of keys.
+  #
+  #   foo = { :name=>'Gavin', 'wife'=>:Lisa }
+  #   foo.symbolize_keys    #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #   foo                   #=>  { :name =>"Gavin", "wife"=>:Lisa }
+  #
+  # If the key does not respond to #to_sym, then #to_s will be used first.
+  #
+  # For a more versatile method, see #rekey instead.
 
-    # Synonym for Hash#symbolize_keys, but modifies the receiver in place and returns it.
-    # With a +filter+ parameter, limits conversion to only a certain selection of keys.
-    #
-    #   foo = { 'name'=>'Gavin', 'wife'=>:Lisa }
-    #   foo.symbolize_keys!    #=>  { :name=>"Gavin", :wife=>:Lisa }
-    #   foo.inspect            #=>  { :name=>"Gavin", :wife=>:Lisa }
-    #
-    # This method is considered archaic. Use #rekey instead.
+  def symbolize_keys(&select)
+    dup.symbolize_keys!(&select)
+  end
 
-    def symbolize_keys!(&filter)
-      if filter
-        rekey!{ |k| filter[k] ? k.to_sym : nil }
-      else
-        rekey!{ |k| k.to_sym }
+  # Destructively convert all keys to symbols. This is the same as
+  # Hash#symbolize_keys, but modifies the receiver in place and returns it.
+  # With a +select+ block, limits conversion to only selected keys.
+  #
+  #   foo = { 'name'=>'Gavin', 'wife'=>:Lisa }
+  #   foo.symbolize_keys!    #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #   foo                    #=>  { :name=>"Gavin", :wife=>:Lisa }
+  #
+  # If the key does not respond to #to_sym, then #to_s will be used first.
+  #
+  # For a more versatile method, see #rekey instead.
+
+  def symbolize_keys!(&select)
+    if select
+      keys.each do |key|
+        if select[key]
+          new_key = (key.to_sym rescue key.to_s.to_sym)
+          self[new_key] = delete(key)
+        end
+      end       
+    else
+      keys.each do |key|
+        new_key = (key.to_sym rescue key.to_s.to_sym)
+        self[new_key] = delete(key)
       end
     end
+    self
+  end
 
-    # Converts all keys in the Hash to Strings, returning a new Hash.
-    # With a +filter+ parameter, limits conversion to only a certain selection of keys.
-    #
-    #   foo = { :name=>'Gavin', :wife=>:Lisa }
-    #   foo.stringify_keys    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #   foo.inspect           #=>  { :name =>"Gavin", :wife=>:Lisa }
-    #
-    # This method is considered archaic. Use #rekey instead.
+  # Return a new hash with all keys converted to strings. Converts all keys
+  # in the Hash to Strings, returning a new Hash. With a +select+ block,
+  # limits conversion to only a certain selection of keys.
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.stringify_keys    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo                   #=>  { :name =>"Gavin", :wife=>:Lisa }
+  #
+  # This method is considered archaic. Use #rekey instead.
+
+  def stringify_keys(&select)
+    dup.stringify_keys!(&select)
+  end
 
-    def stringify_keys(&filter)
-      if filter
-        rekey{ |k| filter[k] ? k.to_s : nil }
-      else
-        rekey{ |k| k.to_s }
+  # Destructively convert all keys to strings. This is the same as
+  # Hash#stringify_keys, but modifies the receiver in place and
+  # returns it. With a +select+ block, limits conversion to only
+  # certain keys.
+  #
+  #   foo = { :name=>'Gavin', :wife=>:Lisa }
+  #   foo.stringify_keys!    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #   foo                    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
+  #
+  # This method is considered archaic. Use #rekey instead.
+
+  def stringify_keys!(&select)
+    if select
+      keys.each do |key|
+        if select[key]
+          self[key.to_s] = delete(key)
+        end
       end
-    end
-
-    #alias_method(:keys_to_s, :stringify_keys)
-
-    # Synonym for Hash#stringify_keys, but modifies the receiver in place and returns it.
-    # With a +filter+ parameter, limits conversion to only a certain selection of keys.
-    #
-    #   foo = { :name=>'Gavin', :wife=>:Lisa }
-    #   foo.stringify_keys!    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #   foo.inspect            #=>  { "name"=>"Gavin", "wife"=>:Lisa }
-    #
-    # This method is considered archaic. Use #rekey instead.
-
-    def stringify_keys!(&filter)
-      if filter
-        rekey!{ |k| filter[k] ? k.to_s : nil }
-      else
-        rekey!{ |k| k.to_s }
+    else
+      keys.each do |key|
+        self[key.to_s] = delete(key)
       end
     end
-
-    alias_method( :to_options, :symbolize_keys )
-    alias_method( :to_options!, :symbolize_keys! )
-
-    # These were the original names used by Facets but
-    # have been deprecated in favor of the Railisms.
-    #alias_method( :keys_to_sym, :symbolize_keys )
-    #alias_method( :keys_to_s, :stringify_keys)
-    #alias_method( :keys_to_sym!, :symbolize_keys! )
-    #alias_method( :keys_to_s!, :stringify_keys!)
-
+    self
   end
 
 end

data/lib/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/lib/core/facets/hash/to_proc.rb

@@ -1,18 +1,19 @@
 class Hash
 
-  # Constructs a Proc object from a hash such that
-  # the parameter of the Proc is assigned the hash
-  # keys as attributes.
+  # Constructs a Proc object from a hash such that the parameter
+  # of the Proc is assigned the hash keys as attributes.
   #
-  #   h = { :a => 1 }
-  #   p = h.to_proc
-  #   o = OpenStruct.new
-  #   p.call(o)
+  #   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.
+  # If +response+ is set to +true+, then assignment will only occur
+  # if receiver responds_to? the writer method.
   #
   # CREDIT: Trans
 

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

@@ -4,14 +4,14 @@ class Hash
   # 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", {"X"=>"X"}}
+  #   h = {"A"=>"A", "B"=>"B", "C"=>{"X"=>"X"}}
   #
   #   g = h.traverse{ |k,v| [k.downcase, v] }
   #
-  #   g  #=> {"a"=>"A", "b"=>"B", {"x"=>"X"}}
+  #   g  #=> {"a"=>"A", "b"=>"B", "c"=>{"x"=>"X"}}
   #
-  # NOTE: Hash#traverse is the same as <code>recursive.graph</code> and
-  # will likely be deprecated in the future because of it.
+  # NOTE: Hash#traverse is the same as `recursive.graph` and
+  # might be deprecated in the future (if it ever works!)
   #
   # CREDIT: Trans
 

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

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

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

@@ -3,8 +3,8 @@ 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 }
+  #   h.update_values{ |v| v + 1 }
+  #   h  #=> { :a=>2, :b=>3 }
   #
   # CREDIT: Trans
 

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

@@ -6,9 +6,8 @@ class Hash
   #
   # 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:
+  # following rules for each node: ...
   #
-  #   <tt>
   #   hash,   hash    => hash (recursive +)
   #   hash,   array   => error
   #   hash,   value   => error
@@ -18,18 +17,14 @@ class Hash
   #   value,  hash    => error
   #   value,  array   => array.unshift(valueB)
   #   value1, value2  => value2
-  #   </tt>
   #
   # 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}
   #
   #   h1.weave(h2)
-  #   => {:b=>[1, 2], :c=>{:x=>2}, :a=>2}
+  #   #=> {: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

data/lib/core/facets/indexable.rb

@@ -7,30 +7,22 @@
 # 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 method is not
+# 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
-#
-# * Thomas Sawyer
-
-
-# = Indexable
-#
-# Indexable is a mixin that provides index based methods,
-# working soley with four methods: #index, #slice, #splice
-# and #size.
+# NOTE: To test the folowing methods Indexable needs to be
+# included into Array and array must have #splice defined.
 #
-# 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.
+#   require 'facets/array/splice'
 #
+#   class ::Array
+#     include Indexable
+#   end
+# 
+# CREDIT: Thomas Sawyer
+
 module Indexable
 
   # Like #first but returns the first element
@@ -90,21 +82,26 @@ module Indexable
     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.
+  # 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].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
+  def middle(birth=0)
+    i = size / 2 - birth
     if size % 2 == 0
-     slice( (size / 2) - 1, 2 )
-     #[slice((size / 2) - 1, 1), slice(size / 2, 1)]
+      slice(i - 1, 2 + (2 * birth))
     else
-      slice(size / 2)
+      slice(i, 1 + (2 * birth))
     end
   end
 
@@ -113,7 +110,12 @@ 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)
+  #   [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
@@ -123,9 +125,27 @@ module Indexable
     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.
   #
-  #   "Hello World".first(3)  #=> "Hel"
+  #   %w{H e l l o}.first(3)  #=> %w{H e l}
   #
   def first(n=1)
     slice(0, n.to_i)
@@ -133,7 +153,7 @@ module Indexable
 
   # Returns last _n_ elements.
   #
-  #   "Hello World".last(3)  #=> "rld"
+  #   %w{H e l l o}.last(3)  #=> %w{l l o}
   #
   def last(n=1)
     n = n.to_i
@@ -145,7 +165,7 @@ module Indexable
   #
   #   a = ["a","y","z"]
   #   a.first = "x"
-  #   p a           #=> ["x","y","z"]
+  #   a           #=> ["x","y","z"]
   #
   def first=(x)
     splice(0,x)
@@ -155,7 +175,7 @@ module Indexable
   #
   #   a = [1,2,5]
   #   a.last = 3
-  #   p a           #=> [1,2,3]
+  #   a           #=> [1,2,3]
 
   def last=(x)
     splice(-1,x)
@@ -232,18 +252,17 @@ module Indexable
 
   # 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.
+  # 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
+  #   ['a','b','c','d'].range            #=> (0..3)
+  #   ['a','b','c','d'].range('b','d')   #=> (1..3)
   #
-  def range(a=nil,z=nil)
-    if !a
-      0..(size-1)
-    else
+  def range(a=nil,z=-1)
+    if a
       index(a)..index(z)
+    else
+      (0..(size-1))
     end
   end