facets 3.1.0 → 3.2.1

data/lib/core/facets/file/read_binary.rb

@@ -1,18 +1,9 @@
 class File
 
-  # Read in a file as binary data.
-  #
-  # Assuming we had a binary file 'binary.dat'.
-  #
-  #   File.read_binary('binary.dat')
-  #
-  # CREDIT: George Moschovitis
-
+  # @deprecated Use File.binread instead (built-in since Ruby 1.9.3).
   def self.read_binary(fname)
-    open(fname, 'rb') do |f|
-      return f.read
-    end
+    warn "File.read_binary is deprecated. Use File.binread instead.", uplevel: 1
+    binread(fname)
   end
 
 end
-

data/lib/core/facets/file.rb

@@ -11,6 +11,6 @@ require_relative 'file/rootname.rb'
 require_relative 'file/sanitize.rb'
 require_relative 'file/split_all.rb'
 require_relative 'file/split_root.rb'
-require_relative 'file/write.rb'
+#require_relative 'file/write.rb'  # removed: now provided by Ruby
 require_relative 'file/writelines.rb'
 

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

@@ -1,12 +1,5 @@
 class Hash
 
-  # Returns a new hash less the given keys.
-  def except(*less_keys)
-    hash = dup
-    less_keys.each{ |k| hash.delete(k) }
-    hash
-  end
-
   # Replaces hash with new hash less the given keys.
   #
   #   h = {:a=>1, :b=>2, :c=>3}

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

@@ -1,18 +1,17 @@
 class Hash
 
-  # Similar to Hash#fetch but supports nested lookup and is `nil` safe.
+  # @deprecated Use Hash#dig instead (built-in since Ruby 2.3).
   #
-  #     {}.fetch_nested('anything','at','all')  #=> nil
+  # Similar to Hash#dig but supports a block for missing keys,
+  # like Hash#fetch does. Ruby's #dig does not support a block.
   #
-  #     h = {'hello'=>{'world'=>42}}
-  #     h.fetch_nested(*['hello','world'])  #=> 42
+  # TODO: Consider proposing block support for Hash#dig to Ruby core.
   #
-  # CREDIT: T. Yamada and Sean Mackesey
-
-  def fetch_nested(*keys)
+  def fetch_nested(*keys, &block)
+    warn "Hash#fetch_nested is deprecated. Use Hash#dig instead.", uplevel: 1
     begin
-      keys.reduce(self){|accum, k| accum.fetch(k)}
-	rescue (RUBY_VERSION<'1.9' ? IndexError : KeyError)
+      keys.reduce(self) { |accum, k| accum.fetch(k) }
+    rescue KeyError
       block_given? ? yield(*keys) : nil
     end
   end

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

@@ -1,4 +1,4 @@
-require 'facets/enumerable/mash'
+require 'facets/enumerable/graph'
 
 class Hash
 

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

@@ -40,13 +40,13 @@ class Hash
 
     if block
       hash = dup.clear
-      if block.arity.abs == 1
+      if block.arity == 2
         each_pair do |k, v|
-          hash[block[k]] = v     #hash[block[k] || k] = v
+          hash[block[k,v]] = v
         end
       else
         each_pair do |k, v|
-          hash[block[k,v]] = v   #hash[block[k,v] || k] = v
+          hash[block[k]] = v
         end
       end
     else

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

@@ -21,13 +21,13 @@ class Hash
 
     if block
       hash = dup.clear  # to keep default_proc
-      if block.arity.abs == 1
+      if block.arity == 2
         each_pair do |k, v|
-          hash[k] = block[v]     #hash[k] = block[v] || v
+          hash[k] = block[k,v]
         end
       else
         each_pair do |k, v|
-          hash[k] = block[k,v]   #hash[k] = block[k,v] || v
+          hash[k] = block[v]
         end
       end
     else

data/lib/core/facets/hash/{to_proc.rb → setter.rb}

@@ -1,7 +1,7 @@
 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 that assigns the hash's key-value pairs as
+  # attributes on a given object.
   #
   #   c = Class.new do
   #     attr_accessor :a
@@ -9,20 +9,20 @@ class Hash
   #
   #   h = {:a => 1}
   #   o = c.new
-  #   h.to_proc.call(o)
+  #   h.setter.call(o)
   #   o.a  #=> 1
   #
-  # If +response+ is set to +true+, then assignment will only occur
-  # if receiver responds_to? the writer method.
+  # If +safe+ is set to +true+, then assignment will only occur
+  # if the receiver responds_to? the writer method.
   #
   # CREDIT: Trans
 
-  def to_proc(response=false)
-    if response
+  def setter(safe=false)
+    if safe
       lambda do |o|
         self.each do |k,v|
           ke = "#{k}="
-          o.__send__(ke, v) if respond_to?(ke)
+          o.__send__(ke, v) if o.respond_to?(ke)
         end
       end
     else
@@ -36,4 +36,3 @@ class Hash
   end
 
 end
-

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

@@ -1,25 +1,5 @@
 class Hash
 
-  # Returns a new hash with only the given keys.
-  #
-  #   h = {:a=>1, :b=>2, :c=>3}
-  #   h.slice(:a, :c)  #=> {:a=>1, :c=>3}
-  #   h.slice(:a, :d)  #=> {:a=>1}
-  #
-  def slice(*keep_keys)
-    if block_given?
-      each do |k, v|
-        keep_keys << k if yield(k, v)
-      end
-    end
-
-    hash = {}
-    keep_keys.each do |key|
-      hash[key] = fetch(key) if key?(key)
-    end
-    hash
-  end
-
   # Replaces hash with a new hash having only the given keys.
   # This return the hash of keys removed.
   #
@@ -29,12 +9,6 @@ class Hash
   #
   # Returns a Hash of the removed pairs.
   def slice!(*keep_keys)
-    if block_given?
-      each do |k, v|
-        keep_keys << k if yield(k, v)
-      end
-    end
-
     rejected = keys - keep_keys
     removed = {}
     rejected.each{ |k| removed[k] = delete(k) }

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

@@ -1,21 +1,14 @@
 class Hash
 
-  # Iterate over hash updating just the keys.
+  # @deprecated Use Hash#transform_keys! (Ruby 2.5+) or Hash#rekey! instead.
   #
-  #   h = {:a=>1, :b=>2}
-  #   h.update_keys{ |k| "#{k}!" }
-  #   h  #=> { "a!"=>1, "b!"=>2 }
-  #
-  # @author Trans
-  # @author Evgeniy Dolzhenko (bug fix)
-
-  def update_keys #:yield:
+  def update_keys(&block)
+    warn "Hash#update_keys is deprecated. Use Hash#transform_keys! or Hash#rekey! instead.", uplevel: 1
     if block_given?
-      keys.each { |old_key| store(yield(old_key), delete(old_key)) }
+      transform_keys!(&block)
     else
       to_enum(:update_keys)
     end
   end
 
 end
-

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

@@ -1,20 +1,14 @@
 class Hash
 
-  # Iterate over hash updating just the values.
+  # @deprecated Use Hash#transform_values! (Ruby 2.4+) or Hash#revalue! instead.
   #
-  #   h = {:a=>1, :b=>2}
-  #   h.update_values{ |v| v + 1 }
-  #   h  #=> { :a=>2, :b=>3 }
-  #
-  # CREDIT: Trans
-
-  def update_values #:yield:
+  def update_values(&block)
+    warn "Hash#update_values is deprecated. Use Hash#transform_values! or Hash#revalue! instead.", uplevel: 1
     if block_given?
-      each{ |k,v| store(k, yield(v)) }
+      transform_values!(&block)
     else
       to_enum(:update_values)
     end
   end
 
 end
-

data/lib/core/facets/hash.rb

@@ -40,7 +40,7 @@ require_relative 'hash/swap.rb'
 require_relative 'hash/symbolize_keys.rb'
 require_relative 'hash/to_mod.rb'
 require_relative 'hash/to_options.rb'
-require_relative 'hash/to_proc.rb'
+require_relative 'hash/setter.rb'
 require_relative 'hash/to_struct.rb'
 require_relative 'hash/traverse.rb'
 require_relative 'hash/update.rb'

data/lib/core/facets/indexable.rb

@@ -199,19 +199,21 @@ module Indexable
     splice(-1)
   end
 
-  # A shorting of "ends at", returns the
-  # last index of the indexable object.
-  # Returns nil if there are no elements.
+  # A shortening of "ends at". Returns the
+  # last index of the indexable object,
+  # or nil if there are no elements.
   #
   #   [1,2,3,4,5].ends  #=> 4
   #
-  # This nearly equivalent to +size - 1+.
+  # This is nearly equivalent to +size - 1+.
   #
   def ends
     return nil if size == 0
     size - 1
   end
 
+  alias_method :last_index, :ends
+
   # Returns the positive ordinal index given
   # a cardinal position, 1 to n or -n to -1.
   #

data/lib/core/facets/kernel/as.rb

@@ -99,8 +99,8 @@ class As #:nodoc:
     private :cache
   end
 
-  # Privatize all methods except #binding an operators.
-  private(*instance_methods.select { |m| m !~ /(^__|^\W|^binding$)/ })
+  # Privatize all methods except #binding, #object_id and operators.
+  private(*instance_methods.select { |m| m !~ /(^__|^\W|^binding$|^object_id$)/ })
 
   def initialize(subject, ancestor)
     @subject = subject

data/lib/core/facets/kernel/callstack.rb

@@ -3,12 +3,7 @@ module Kernel
   alias_method :pp_callstack, :caller
   alias_method :pp_call_stack, :caller
 
-  # Parse a caller string and break it into its components,
-  # returning an array composed of:
-  #
-  # * file (String)
-  # * lineno (Integer)
-  # * method (Symbol)
+  # Returns the call stack as an array of [file, lineno, method] entries.
   #
   # For example, from irb
   #
@@ -16,27 +11,14 @@ module Kernel
   #
   # _produces_ ...
   #
-  #     [["(irb)", 2, :irb_binding],
-  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, :irb_binding],
-  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, nil]]
-  #
-  # Note: If the user decides to redefine caller() to output data
-  # in a different format, _prior_ to requiring this, then the
-  # results will be indeterminate.
+  #     [["(irb)", 2, :irb_binding], ...]
   #
   # CREDIT: Trans
 
   def callstack(level = 1)
-    call_str_array = pp_callstack(level)
-    stack = []
-    call_str_array.each{ |call_str|
-      file, lineno, method = call_str.split(':')
-      if method =~ /in `(.*)'/ then
-        method = $1.intern()
-      end
-      stack << [file, lineno.to_i, method]
-    }
-    stack
+    caller_locations(level).map do |loc|
+      [loc.path, loc.lineno, loc.label&.to_sym]
+    end
   end
 
   alias_method :call_stack, :callstack
@@ -53,4 +35,3 @@ class Binding
 
   alias_method :call_stack, :callstack
 end
-

data/lib/core/facets/kernel/eigenclass.rb

@@ -3,13 +3,13 @@ module Kernel
   # During this trying time when no one can get their
   # techie catchwords to stick to the refrigerator no
   # matter how hard they slap it with the enchanted
-  # magnetic spatula, it’s good to know that the
+  # magnetic spatula, it's good to know that the
   # contrived phrases really do fly, graceful and
   # unclasped and bearing north toward chilled shrimp.
-  # I know what my Hallowe’en pumpkin is going to say.
+  # I know what my Hallowe'en pumpkin is going to say.
   #
-  # NOTE: This method is not a common core extension and is not
-  # loaded automatically when using `require 'facets'`.
+  # @deprecated Use singleton_class or meta_class instead.
+  #   Kept in tribute to WhyTheLuckyStiff who coined the term.
   #
   # CREDIT: WhyTheLuckyStiff
   #
@@ -17,8 +17,8 @@ module Kernel
   #   require 'facets/kernel/eigenclass'
   #
   def eigenclass
-    (class << self; self; end)
+    warn "Kernel#eigenclass is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
+    singleton_class
   end
 
 end
-

data/lib/core/facets/kernel/extension.rb

@@ -1,12 +1,9 @@
 module Kernel
 
-  # TODO: Must reduce the number of singleton method methods.
-
-  # Don't say it!
-  #
+  # @deprecated Use singleton_class or meta_class instead.
   def extension
-    class << self; self; end
+    warn "Kernel#extension is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
+    singleton_class
   end
 
 end
-

data/lib/core/facets/kernel/functor.rb

@@ -0,0 +1,16 @@
+require 'facets/functor'
+
+module Kernel
+
+  # Returns a Functor that intercepts method calls, forwards
+  # them to self for side effects, and returns self. This is like
+  # a block-less version of #tap that allows method chaining.
+  #
+  #   YAML.functor.load_file('foo.yml').load_file('bar.yml')
+  #
+
+  def functor
+    Functor.new{ |op,*a,&b| self.send(op, *a, &b); self }
+  end
+
+end

data/lib/core/facets/kernel/instance_class.rb

@@ -1,26 +1,10 @@
 module Kernel
 
-  # Kernel extension prefixed by instance_ which provide
-  # internal (eg private) access to the object.
-  # Kernel extension using instance_ prefix which is beneficial
-  # to separation of metaprogramming from general programming.
-  # object_ methods, in contrast to the instance_ methods,
-  # do not access internal state.
-
-  # Easy access to an object qua class, otherwise known
-  # as the object's metaclass or singleton class. This
-  # implemnetation alwasy returns the class, even if a
-  # block is provided to eval against it...
-  #
-  #     It is what it is.
-  #     But I think I like this one best.
-  #
-  # CREDIT: Trans
-
+  # @deprecated Use singleton_class or meta_class instead.
   def instance_class(&block)
-    (class << self; self; end).module_eval(&block) if block
-    (class << self; self; end)
+    warn "Kernel#instance_class is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
+    singleton_class.module_eval(&block) if block
+    singleton_class
   end
 
 end
-

data/lib/core/facets/kernel/instance_send.rb

@@ -1,7 +1,9 @@
 module Kernel
 
-  # Private send.
-  alias_method :instance_send, :__send__
+  # @deprecated Use __send__ instead.
+  def instance_send(name, *args, &blk)
+    warn "Kernel#instance_send is deprecated. Use __send__ instead.", uplevel: 1
+    __send__(name, *args, &blk)
+  end
 
 end
-

data/lib/core/facets/kernel/load_relative.rb

@@ -1,25 +1,13 @@
 module Kernel
 
-  unless private_method_defined?(:load_relative)  # Will Ruby ever support out-of-the-box?
-
-    # Load file from same dir as calling script.
-    #
-    #   load_relative 'myscript'
-    #
-    # CREDIT: Paul Brannan, Pragmatic Programmers
-    #
-    def load_relative(relative_feature, safe=nil)
-      c = caller.first
-      fail "Can't parse #{c}" unless c.rindex(/:\d+(:in `.*')?$/)
-      file = $` # File.dirname(c)
-      if /\A\((.*)\)/ =~ file # eval, etc.
-        raise LoadError, "require_relative is called in #{$1}"
-      end
-      absolute = File.expand_path(relative_feature, File.dirname(file))
-      load absolute, safe
-    end
-
+  # @deprecated Use require_relative for requires; for load, use
+  #   an absolute path via File.expand_path.
+  def load_relative(relative_feature, safe=nil)
+    warn "Kernel#load_relative is deprecated.", uplevel: 1
+    loc = caller_locations(1, 1).first
+    file = loc.absolute_path || loc.path
+    absolute = File.expand_path(relative_feature, File.dirname(file))
+    load absolute, safe
   end
 
 end
-

data/lib/core/facets/kernel/memo.rb

@@ -1,35 +1,14 @@
-require 'facets/binding/eval'
-require 'facets/kernel/__method__'
-
 module Kernel
 
-  # Global memo cache.
-  $MEMO ||= {}
-
-  # Memoize a method.
-  # 
-  #   class MemoExample
-  #     attr_accessor :a
-  #     def m
-  #       memo{ @a }
-  #     end
-  #   end
-  #
-  #   ex = MemoExample.new
-  #
-  #   ex.a = 10
-  #   ex.m  #=> 10
-  #
-  #   ex.a = 20
-  #   ex.m  #=> 10
-  #
-  # NOTE: This method is not a common core extension and is not
-  # loaded automatically when using <code>require 'facets'</code>.
+  # @deprecated Use Module#memoize instead, which provides proper
+  #   per-object memoization without a global variable.
   #
   # @uncommon
   #   require 'facets/kernel/memo'
   #
   def memo(*args, &block)
+    warn "Kernel#memo is deprecated. Use Module#memoize instead.", uplevel: 1
+    $MEMO ||= {}
     if args.empty?
       args = block.binding.eval('[self, __method__]')
     end
@@ -41,4 +20,3 @@ module Kernel
   end
 
 end
-

data/lib/core/facets/kernel/meta_class.rb

@@ -1,17 +1,21 @@
 module Kernel
 
-  # Easy access to an object's "special" class, otherwise known as it's
-  # singleton class, eigenclass, adhoc class or object-qua-class.
-  # 
+  # Easy access to an object's singleton class, with optional block eval.
+  #
+  #   obj.meta_class  #=> #<Class:obj>
+  #   obj.meta_class { def foo; end }
+  #
+  # This is a concise alternative to Ruby's `singleton_class` that also
+  # accepts a block for class_eval.
+  #
   def meta_class(&block)
     if block_given?
-      (class << self; self; end).class_eval(&block)
+      singleton_class.class_eval(&block)
     else
-      (class << self; self; end)
+      singleton_class
     end
   end
 
-  # The non-underscored form of #meta_class if faily common.
   alias_method :metaclass, :meta_class
 
 end

data/lib/core/facets/kernel/object_class.rb

@@ -1,10 +1,9 @@
 module Kernel
 
-  # Defines object_classas an alias of class.
-  # This is an alternative to __class__, akin to
-  # #object_id.
-
-  alias_method :object_class, :class
+  # @deprecated Use __class__ instead.
+  def object_class
+    warn "Kernel#object_class is deprecated. Use __class__ instead.", uplevel: 1
+    self.class
+  end
 
 end
-

data/lib/core/facets/kernel/object_send.rb

@@ -1,30 +1,9 @@
 module Kernel
 
-  # Send only to public methods.
-  #
-  #   class SendExample
-  #     private
-  #     def foo; end
-  #   end
-  #
-  #   obj = SendExample.new
-  #
-  #   expect NoMethodError do
-  #     obj.object_send(:foo)
-  #   end
-  #
-  # DEPRECATED: Use #public_send instead.
-
-  alias object_send public_send rescue nil
-
-  #def object_send(name, *args, &blk)
-  #  #instance_eval "self.#{name}(*args)"
-  #  if respond_to?(name)
-  #    __send__(name, *args, &blk)
-  #  else
-  #    __send__(:method_missing, name, *args, &blk)
-  #  end
-  #end
+  # @deprecated Use public_send instead (built-in since Ruby 1.9.2).
+  def object_send(name, *args, &blk)
+    warn "Kernel#object_send is deprecated. Use public_send instead.", uplevel: 1
+    public_send(name, *args, &blk)
+  end
 
 end
-

data/lib/core/facets/kernel/qua_class.rb

@@ -1,31 +1,15 @@
 module Kernel
 
-  # Easy access to an object qua class, otherwise known as the object's
-  # singleton class. #qua_class can also take a block.
-  #
-  #   string = "Hello World"
-  #
-  #   string.qua_class do
-  #     def important
-  #        self + "!"
-  #     end
-  #   end
-  #
-  #   string.important  #=> "Hello World!"
-  #
-  # Yes, another one.
-  #
-  # CREDIT: Trans
-
+  # @deprecated Use singleton_class or meta_class instead.
   def qua_class(&block)
+    warn "Kernel#qua_class is deprecated. Use singleton_class or meta_class instead.", uplevel: 1
     if block_given?
-      (class << self; self; end).class_eval(&block)
+      singleton_class.class_eval(&block)
     else
-      (class << self; self; end)
+      singleton_class
     end
   end
 
-  # The +qua_class+ method can also be written +quaclass+.
   alias_method :quaclass, :qua_class
 
 end