facets 3.0.0 → 3.2.0

data/lib/core/facets/array/variance.rb

@@ -0,0 +1,20 @@
+require 'facets/array/average'
+
+class Array
+
+  # Calculate the variance of an array of numbers
+  #
+  # Examples
+  #
+  #   [].variance #=> nil
+  #   [1, 2, 3].variance #=> 0.6666666666666666
+  #   [96, 35, 72, 30, 75, 33, 68, 13, 49, 71].variance #=> 609.76
+  #   [36, -67, -17, 85, -46, -64, -23, -13, 89, -47].variance #=> 2989.0099999999993
+  #   [60.7829, 31.2622, 20.626, 78.8907, 61.5328].variance #=> 459.1941339495999
+  #
+  def variance
+    avg = average
+    map {|n| (n - avg) ** 2 }.average
+  end
+end
+

data/lib/core/facets/array.rb

@@ -1,5 +1,6 @@
 require_relative 'array/after.rb'
 #require_relative 'array/arrange.rb'            # too new
+require_relative 'array/average.rb'
 require_relative 'array/before.rb'
 require_relative 'array/collapse.rb'
 require_relative 'array/collisions.rb'

data/lib/core/facets/binding/caller.rb

@@ -8,16 +8,22 @@ class Binding
     eval("caller(#{skip})")
   end
 
+  # Returns the call stack, same format as Kernel#caller_locations()
+  #
+  def caller_locations( skip=0 )
+    eval("caller_locations(#{skip})")
+  end
+
   # Return the line number on which the binding was created.
   #
   def __LINE__
-    Kernel.eval("__LINE__", self)
+    self.source_location[1]
   end
 
   # Returns file name in which the binding was created.
   #
   def __FILE__
-    Kernel.eval("__FILE__", self)
+    self.source_location[0]
   end
 
   # Return the directory of the file in which the binding was created.

data/lib/core/facets/binding/op_get.rb

@@ -1,25 +1,21 @@
 class Binding
 
-  # Returns the value of some variable.
+  # Returns the value of a local variable.
   #
   #   a = 2
-  #   binding["a"]  #=> 2
+  #   binding[:a]  #=> 2
   #
-  def []( x )
-    eval( x.to_s )
+  def [](name)
+    local_variable_get(name.to_sym)
   end
 
   # Set the value of a local variable.
   #
-  #   binding["a"] = 4
+  #   binding[:a] = 4
   #   a  #=> 4
   #
-  # @deprecated No longer wortks in Ruby 1.9+.
-  #
-  # @see Binding#with for an alternative.
-  def []=( l, v )
-    eval( "lambda {|v| #{l} = v}").call( v )
+  def []=(name, value)
+    local_variable_set(name.to_sym, value)
   end
 
 end
-

data/lib/core/facets/binding/self.rb

@@ -1,15 +1,9 @@
 class Binding
 
-  # This is already defined by Rubinius:
-  #   Kernel.eval('Rubinius::VariableScope.current.self', self)
-  unless method_defined?(:self)
-
-    # Returns self of the binding's context.
-    def self
-      eval('self')
-    end
-
+  # @deprecated Use Binding#receiver instead (built-in since Ruby 2.6).
+  def self
+    warn "Binding#self is deprecated. Use Binding#receiver instead.", uplevel: 1
+    receiver
   end
 
 end
-

data/lib/core/facets/binding.rb

@@ -2,7 +2,6 @@ require_relative 'binding/caller.rb'
 require_relative 'binding/callstack.rb'
 require_relative 'binding/call_stack.rb'
 require_relative 'binding/defined.rb'
-#require_relative 'binding/local_variables.rb'  # uncommon
 require_relative 'binding/op.rb'
 require_relative 'binding/op_get.rb'
 require_relative 'binding/op_set.rb'

data/lib/core/facets/boolean.rb

@@ -86,7 +86,7 @@ class String
   #
   # All other strings return false.
   #
-  # Here are some exmamples.
+  # Here are some examples.
   #
   #   "true".to_b   #=> true
   #   "yes".to_b    #=> true

data/lib/core/facets/class/descendants.rb

@@ -1,5 +1,3 @@
-require 'facets/class/subclasses'
-
 class Class
 
   # List all descedents of this class.

data/lib/core/facets/class.rb

@@ -3,7 +3,7 @@ require_relative 'class/descendants.rb'
 require_relative 'class/methodize.rb'
 require_relative 'class/pathize.rb'
 #require_relative 'class/preallocate.rb'  # uncommon
-#require_relative 'class/singleton.rb'    # uncommon
-require_relative 'class/subclasses.rb'
+#require_relative 'class/singleton.rb'    # removed, use Ruby's singleton_class
+#require_relative 'class/subclasses.rb'   # removed, use Ruby's subclasses
 require_relative 'class/to_proc.rb'
 

data/lib/core/facets/comparable/bound.rb

@@ -1 +1,13 @@
-require 'facets/comparable/clip'
+module Comparable
+
+  # Alias for Comparable#clamp. Reads more naturally in some contexts.
+  #
+  #   4.bound(2, 7)  #=> 4
+  #   9.bound(2, 7)  #=> 7
+  #   1.bound(2, 7)  #=> 2
+  #
+  def bound(lower, upper=nil)
+    upper ? clamp(lower, upper) : clamp(lower..)
+  end
+
+end

data/lib/core/facets/comparable/clip.rb

@@ -1,38 +1,9 @@
 module Comparable
 
-  # Returns self if above the given lower bound, or
-  # within the given lower and upper bounds,
-  # otherwise returns the the bound of which the
-  # value falls outside.
-  #
-  #   4.clip(3)    #=> 4
-  #   4.clip(5)    #=> 5
-  #   4.clip(2,7)  #=> 4
-  #   9.clip(2,7)  #=> 7
-  #   1.clip(2,7)  #=> 2
-  #
-  # CREDIT Florian Gross, Trans
-
+  # @deprecated Use Comparable#clamp instead (built-in since Ruby 2.4).
   def clip(lower, upper=nil)
-    return lower if self < lower
-    return self unless upper
-    return upper if self > upper
-    return self
+    warn "Comparable#clip is deprecated. Use Comparable#clamp instead.", uplevel: 1
+    upper ? clamp(lower, upper) : clamp(lower..)
   end
 
-  # Returns self if above the given lower bound, or
-  # within the given lower and upper bounds,
-  # otherwise returns the the bound of which the
-  # value falls outside.
-  #
-  #   4.bound(3)    #=> 4
-  #   4.bound(5)    #=> 5
-  #   4.bound(2,7)  #=> 4
-  #   9.bound(2,7)  #=> 7
-  #   1.bound(2,7)  #=> 2
-  #
-  # CREDIT: Florian Gross
-
-  alias_method :bound, :clip
-
 end

data/lib/core/facets/denumerable.rb

@@ -1,6 +1,3 @@
-require 'facets/enumerator'
-#require 'facets/enumerable/take'
-
 # Classes which include Denumerable will get versions of map,
 # select, and so on, which return a Denumerator, so that they
 # work horizontally without creating intermediate arrays.

data/lib/core/facets/dir/find.rb

@@ -0,0 +1,20 @@
+require 'find'
+
+class Dir
+
+  # Recursively traverse a directory, yielding each file and directory path.
+  # Supports Find.prune to skip subtrees.
+  #
+  #   Dir.find('.') do |path|
+  #     puts path
+  #   end
+  #
+  # Returns an enumerator if no block is given.
+  #
+  # This is a convenience wrapper around Ruby's Find.find.
+
+  def self.find(*paths, ignore_error: true, &block)
+    Find.find(*paths, ignore_error: ignore_error, &block)
+  end
+
+end

data/lib/core/facets/dir/recurse.rb

@@ -1,35 +1,17 @@
+require 'facets/dir/find'
+
 class Dir
 
-  # Recursively scan a directory and pass each file to the given block.
-  #
-  #   Dir.recurse('.') do |path|
-  #     # ...
-  #   end
-  #
-  # CREDIT: George Moschovitis
-  #
-  # TODO: If fully compatible, reimplement as alias of Find.find,
-  # or just copy and paste Find.find code here if it looks more robust.
-  #
+  # @deprecated Use Dir.find or Find.find instead.
   def self.recurse(path='.', &block)
-    list = []
-    stoplist = ['.', '..']
-    Dir.foreach(path) do |f|
-      next if stoplist.include?(f)
-      filename = (path == '.' ? f : path + '/' + f)
-      list << filename
-      block.call(filename) if block
-      if FileTest.directory?(filename) and not FileTest.symlink?(filename)
-        list.concat(Dir.recurse(filename, &block))
-      end
-    end
-    list
+    warn "Dir.recurse is deprecated. Use Dir.find or Find.find instead.", uplevel: 1
+    Dir.find(path, &block)
   end
 
-  # Same as Dir#recurse.
+  # @deprecated Use Dir.find or Find.find instead.
   def self.ls_r(path='.', &block)
-    recurse(path, &block)
+    warn "Dir.ls_r is deprecated. Use Dir.find or Find.find instead.", uplevel: 1
+    Dir.find(path, &block)
   end
 
 end
-

data/lib/core/facets/enumerable/cluster.rb

@@ -1,10 +1,12 @@
 module Enumerable
 
-  # Clusters together adjacent elements into a list of 
-  # sub-arrays.
+  # Clusters together adjacent elements into a list of sub-arrays.
   #
-  # >> [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
-  # => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
+  #     [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
+  #     => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
+  #
+  #     ["dog", "duck", "cat", "dude"].cluster{ |x| x[0] }
+  #     => [["dog", "duck"], ["cat"], ["dude"]]
   #
   # @author Oleg K
 

data/lib/core/facets/enumerable/compact_map.rb

@@ -15,18 +15,8 @@ module Enumerable
   # does almost the same thing and enum.map{}.compact works too.
 
   def compact_map(&block)
-    y = []
-    if block_given?
-      each do |*a|
-        r = yield(*a)
-        y << r unless r.nil?
-      end
-    else
-      each do |r|
-        y << r unless r.nil?
-      end
-    end
-    y
+    warn "Enumerable#compact_map is deprecated. Use Enumerable#filter_map instead.", uplevel: 1
+    filter_map(&block)
   end
 
   #

data/lib/core/facets/enumerable/defer.rb

@@ -27,19 +27,8 @@ module Enumerable
   # to output each result and discard it.
   #
   def defer(&blk)
-    if block_given?
-      Denumerator.new do |output|
-        each do |*input|
-          yield(output, *input)
-        end
-      end
-    else
-      Denumerator.new do |output|
-        each do |*input|
-          output.yield(*input)
-        end
-      end
-    end
+    warn "Enumerable#defer is deprecated. Use Enumerable#lazy instead.", uplevel: 1
+    lazy
   end
 
 end

data/lib/core/facets/enumerable/each_by.rb

@@ -1,5 +1,3 @@
-require 'facets/enumerator'
-
 module Enumerable
 
   # Iterate through slices. If slice +steps+ is not

data/lib/core/facets/enumerable/frequency.rb

@@ -16,8 +16,8 @@ module Enumerable
   #++
 
   def frequency
-    p = Hash.new(0); each{ |v| p[v] += 1 }; p
-
+    warn "Enumerable#frequency is deprecated. Use Enumerable#tally instead.", uplevel: 1
+    tally
   end
 
 end

data/lib/core/facets/enumerable/hashify.rb

@@ -4,13 +4,13 @@ require 'facets/enumerable/value_by'
 
 module Enumerable
 
-  # The hashify methods is a higher-order message used to 
+  # The hashify methods is a higher-order message used to
   # convert an enumerable object into a hash. Converting an
   # enumerable object into a hash is not a one-to-one conversion,
   # for this reason #hashify is used to provide variant approches
   # for the conversion most suited to the use case at hand.
   # Here are some (but not a complete set of) examples.
-  # 
+  #
   # If the enumerable is a collection of perfect pairs, like that
   # which Hash#to_a generates, then #assoc can be used.
   #
@@ -23,13 +23,13 @@ module Enumerable
   #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
   #   a.hashify.concat  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
   #
-  # If the array contians objects other then arrays then
+  # If the array contains objects other then arrays then
   # the #splat method might do the trick.
   #
   #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
-  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
+  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }
   #
-  # Also, the particular dispatch can be left up the Hashify 
+  # Also, the particular dispatch can be left up the Hashify
   # using the #auto method. See Hashify#auto for details on this.
   #
   # TODO: This method takes arguments only for the sake of the old
@@ -64,11 +64,9 @@ module Enumerable
     #
     #   a = [:a,1,:b,2,:c]
     #   a.to_h_splat  #=> { :a=>1, :b=>2, :c=>nil }
-    #
-    # TODO: Can this be done without #size?
     def splat
-      a = @enum.dup
-      a << nil if a.size % 2 == 1
+      a = @enum.to_a
+      a << nil if a.size.odd?
       Hash[*a]
     end
 
@@ -78,48 +76,46 @@ module Enumerable
     #
     #   a = [:a,1,[:b,2,:c]]
     #   a.to_h_flat  #=> { :a=>1, :b=>2, :c=>nil }
-    #
-    # TODO: Need to do this without #size.
     def flat
-      a = @enum.flatten
-      a << nil if a.size % 2 == 1
+      a = @enum.to_a.flatten
+      a << nil if a.size.odd?
       Hash[*a]
     end
 
-    # When a mixed or multi-element accociative array
+    # When a mixed or multi-element associative array
     # is used, the result is as follows:
     #
     #   a = [ [:a,1,2], [:b,2], [:c], :d ]
     #   a.hashify.assoc  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
     #
     # If the first entry of any subelements are the same, then
-    # the value will be set to the last occuring value.
+    # the value will be set to the last occurring value.
     #
     #   a = [ :x, [:x], [:x,1,2], [:x,3], [:x,4] ]
     #   a.hashify.assoc  #=> { :x=>[4] }
     #
     def associate
       h = {}
-      each do |k,*v| 
+      each do |k,*v|
         h[k] = v
       end
       h
     end
 
     # Alias for #associate.
-    alias :assoc, :associate
+    alias :assoc :associate
 
     # Like associate but does force values into an array.
     #
     def merge
       h = {}
-      each do |k,v| 
+      each do |k,v|
         h[k] = v
       end
       h
     end
 
-    # When a mixed or multi-element accociative array
+    # When a mixed or multi-element associative array
     # is used, the result is as follows:
     #
     #   a = [ [:a,1,2], [:b,2], [:c], :d ]
@@ -129,11 +125,11 @@ module Enumerable
     # the values will be merged using #concat.
     #
     #   a = [ [:a,1,2], [:a,3], [:a,4], [:a], :a ]
-    #   a.hasify.concat  #=> { :a=>[1,2,3,4] }
+    #   a.hashify.concat  #=> { :a=>[1,2,3,4] }
     #
     def concat
       h = {}
-      each do |k,*v| 
+      each do |k,*v|
         h[k] ||= []
         h[k].concat(v)
       end
@@ -141,7 +137,7 @@ module Enumerable
     end
 
     # Older name for #concat.
-    alias :multi, :concat
+    alias :multi :concat
 
     # Convert enumerable object to Hash using index as keys.
     #
@@ -158,11 +154,11 @@ module Enumerable
     # Converts enumerable object into a hash. Converting an array
     # into a hash is not a one-to-one conversion, for this
     # reason #auto examines the enumerable being converted
-    # and then dispatches the conversion to the most sutiable
-    # specialized function. There are three possiblities for this.
+    # and then dispatches the conversion to the most suitable
+    # specialized function. There are three possibilities for this.
     #
     # If the enumerable is a collection of perfect pairs, like that
-    # which Hash#to_a generates, then conversion is handled by 
+    # which Hash#to_a generates, then conversion is handled by
     # #flat.
     #
     #   a = [ [:a,1], [:b,2] ]
@@ -174,14 +170,14 @@ module Enumerable
     #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
     #   a.hashify.auto  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
     #
-    # If it contians objects other then arrays then the #splat method
+    # If it contains objects other then arrays then the #splat method
     # is called.
     #
     #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
-    #   a.hashify.auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
+    #   a.hashify.auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }
     #
     # Be aware this is not as efficient as using the underlying methods
-    # directly becuase it must perform an initial iteration over the
+    # directly because it must perform an initial iteration over the
     # enumerable to determine its contents.
 
     def auto(&block)
@@ -206,18 +202,18 @@ module Enumerable
     end
 
     # Alias for `#auto`.
-    alias :automatic, :auto
+    alias :automatic :auto
 
   private
 
     #
     def each(&b)
-      @enum.each(&b) 
+      @enum.each(&b)
     end
 
     #
     def each_with_index(&b)
-      @enum.each_with_index(&b) 
+      @enum.each_with_index(&b)
     end
 
   end

data/lib/core/facets/enumerable/hinge.rb

@@ -9,10 +9,9 @@ module Enumerable
   #
   # TODO: Enumerable#hinge will get a new name.
   #
-  def hinge(init={})
-    h = init
-    each{ |v| yield(h,v) }
-    h
+  def hinge(init={}, &block)
+    warn "Enumerable#hinge is deprecated. Use Enumerable#each_with_object instead (note: block args are reversed).", uplevel: 1
+    each_with_object(init) { |e, obj| block.call(obj, e) }
   end
 
 end

data/lib/core/facets/enumerable/map_with_index.rb

@@ -7,12 +7,9 @@ module Enumerable
   #
   # CREDIT: Gavin Sinclair
 
-  def map_with_index
-    r = []
-    each_with_index do |e, i|
-      r << yield(e, i)
-    end
-    r
+  def map_with_index(&block)
+    warn "Enumerable#map_with_index is deprecated. Use Enumerable#map.with_index instead.", uplevel: 1
+    map.with_index(&block)
   end
 
   # Alias for map_with_index.

data/lib/core/facets/enumerable/mash.rb

@@ -1,34 +1,11 @@
-module Enumerable
+require 'facets/enumerable/graph'
 
-  # Like `#map`/`#collect`, but generates a Hash. The block is expected
-  # to return two values: the key and the value for the new hash.
-  #
-  #   numbers  = (1..3)
-  #   squares  = numbers.mash{ |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }
-  #   sq_roots = numbers.mash{ |n| [n*n, n] }   # { 1=>1, 4=>2, 9=>3 }
-  #
-  # CREDIT: Andrew Dudzik (adudzik), Trans
+module Enumerable
 
+  # @deprecated Use Enumerable#graph instead.
   def mash(&yld)
-    if yld
-      h = {}
-      each do |*kv|
-        r = yld[*kv]
-        case r
-        when Hash
-          nk, nv = *r.to_a[0]
-        when Range
-          nk, nv = r.first, r.last
-        else
-          nk, nv = *r
-        end
-        h[nk] = nv
-      end
-      h
-    else
-      Enumerator.new(self,:graph)
-    end
+    warn "Enumerable#mash is deprecated. Use Enumerable#graph instead.", uplevel: 1
+    graph(&yld)
   end
 
 end
-

data/lib/core/facets/enumerable/uniq_by.rb

@@ -1,13 +1,9 @@
 module Enumerable
 
-  # Like #uniq, but determines uniqueness based on a given block.
-  #
-  #   (-5..5).to_a.uniq_by {|i| i*i }
-  #   #=> [-5, -4, -3, -2, -1, 0]
-  #
-  def uniq_by #:yield:
-    h = {}; inject([]) {|a,x| h[yield(x)] ||= a << x}
+  # @deprecated Use Enumerable#uniq with a block instead (Ruby 1.9.2+).
+  def uniq_by(&block)
+    warn "Enumerable#uniq_by is deprecated. Use Enumerable#uniq(&block) instead.", uplevel: 1
+    uniq(&block)
   end
 
 end
-