facets 3.1.0 → 3.2.0

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/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/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

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

@@ -1,23 +1,15 @@
 module Kernel
 
-  # Require a pattern of files relatvie to the current file.
-  # This makes is easy to require an entire directory, for instance:
+  # Require a pattern of files relative to the current file.
+  # This makes it easy to require an entire directory, for instance:
   #
   #   require_all 'core_ext/*'
   #
-  # NOTE: This method used to allow glob-based requires from the $LOAD_PATH,
-  # but this was deprecated in favor of relative requiring only, as it is
-  # consider the typical usecase, and globbing from the $LOAD_PATH is a
-  # bit dangerous. Better options exist for globbing the $LOAD_PATH such as
-  # the +plugins+ gem.
 
   def require_all(pattern)
-    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
+    loc = caller_locations(1, 1).first
+    file = loc.absolute_path || loc.path
+    raise LoadError, "require_all is called in #{loc.label}" unless file
     glob = File.expand_path(pattern, File.dirname(file))
     Dir.glob(glob).each do |absolute|
       require absolute
@@ -26,12 +18,9 @@ module Kernel
 
   # Same as #require_all, but for #load.
   def load_all(pattern, 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
+    loc = caller_locations(1, 1).first
+    file = loc.absolute_path || loc.path
+    raise LoadError, "load_all is called in #{loc.label}" unless file
     glob = File.expand_path(pattern, File.dirname(file))
     Dir.glob(glob).each do |absolute|
       load absolute, safe
@@ -39,4 +28,3 @@ module Kernel
   end
 
 end
-

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

@@ -1,25 +1,9 @@
 module Kernel
 
-  # A Ruby-ized realization of the K combinator.
+  # @deprecated Use Kernel#tap instead (built-in since Ruby 1.9).
   #
-  #   book_class = Struct.new(:title, :author)
-  #
-  #   book = returning book_class.new do |book|
-  #     book.title = "Imperium"
-  #     book.author = "Ulick Varange"
-  #   end
-  #
-  #   book.class  #=> book_class
-  #
-  # Technically, #returning probably should force the return of
-  # the stated object irregardless of any return statements that
-  # might appear within it's block. This might differentiate
-  # #returning from #with, however it also would require
-  # implementation in Ruby itself.
-  #
-  # CREDIT: Mikael Brockman
-
-  def returning(obj=self) #:yield:
+  def returning(obj=self)
+    warn "Kernel#returning is deprecated. Use Kernel#tap instead.", uplevel: 1
     yield obj
     obj
   end

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

@@ -1,36 +1,3 @@
-require 'facets/functor'
-
-module Kernel
-
-  # The tap K-Combinator. This yields self -and- returns self.
-  #
-  #   'foo.yml'.tap{ |f| YAML.load(f) }  #=> 'foo.yml'
-  #
-  # Unlike Ruby's definition, this rendition can be used as a higher
-  # order message. This form allows a single call before returning
-  # the receiver.
-  #
-  #   YAML.tap.load_file('foo.yml').load_file('bar.yml')
-  #
-  # IMPORTANT: This is one of few core overrides in Facets.
-
-  def tap #:yield:
-    if block_given?
-      yield(self)
-      self
-    else
-      Functor.new{ |op,*a,&b| self.send(op, *a, &b); self }
-    end
-  end
-
-  # Old Definition:
-  #
-  #   def tap #:yield:
-  #     if block_given?
-  #       b.arity == 1 ? yield(self) : instance_eval(&b)
-  #     end
-  #     return self
-  #   end
-  #
-
-end
+# Facets no longer overrides Kernel#tap. Use Kernel#functor instead
+# for the block-less Functor form.
+require 'facets/kernel/functor'

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

@@ -0,0 +1,2 @@
+# @deprecated Use Kernel#functor instead.
+require 'facets/kernel/functor'

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

@@ -3,38 +3,36 @@ require 'facets/functor'
 module Kernel
 
   # Invokes the method identified by the symbol +method+, passing it any
-  # arguments  and/or the block specified, just like the regular Ruby
-  # <tt>Object#send</tt> does.
+  # arguments and/or the block specified.
   #
-  # *Unlike* that method however, a +NoMethodError+ exception will *not*
-  # be raised and +nil+ will be returned instead, if the receiving object
-  # is a +nil+ object or NilClass.
+  # Unlike regular send, a +NoMethodError+ exception will *not* be raised
+  # if the receiving object is +nil+ (see NilClass#try below).
   #
-  # For example, without try
+  # Compatible with ActiveSupport's #try, plus an additional Functor
+  # form when called with no arguments and no block.
   #
-  #   @example = Struct.new(:name).new("bob")
-  #
-  #   @example && @example.name
-  #
-  # or:
-  #
-  #   @example ? @example.name : nil
-  #
-  # But with try
-  #
-  #   @example.try(:name)  #=> "bob"
-  #
-  # or
-  #
-  #   @example.try.name    #=> "bob"
-  #
-  # It also accepts arguments and a block, for the method it is trying:
-  #
-  #   @people.try(:collect){ |p| p.name }
+  #   @example.try(:name)              #=> "bob"
+  #   @example.try { |o| o.name }     #=> "bob"  (ActiveSupport block form)
+  #   @example.try.name               #=> "bob"  (Facets Functor form)
   #
   def try(method=nil, *args, &block)
     if method
       __send__(method, *args, &block)
+    elsif block_given?
+      yield self
+    else
+      self
+    end
+  end
+
+  # Like #try, but raises NoMethodError if the method doesn't exist
+  # (unless receiver is nil). Compatible with ActiveSupport's #try!.
+  #
+  def try!(method=nil, *args, &block)
+    if method
+      public_send(method, *args, &block)
+    elsif block_given?
+      yield self
     else
       self
     end
@@ -46,13 +44,25 @@ end
 class NilClass
 
   # See Kernel#try.
-  def try(method=nil, *args)
+  def try(method=nil, *args, &block)
     if method
       nil
+    elsif block_given?
+      nil
     else
-      Functor.new{ nil }
+      Functor.new { nil }
     end
   end
 
-end
+  # See Kernel#try!.
+  def try!(method=nil, *args, &block)
+    if method
+      nil
+    elsif block_given?
+      nil
+    else
+      Functor.new { nil }
+    end
+  end
 
+end

data/lib/core/facets/kernel.rb

@@ -8,7 +8,6 @@ require_relative 'kernel/callstack.rb'
 require_relative 'kernel/call_stack.rb'
 require_relative 'kernel/case.rb'
 require_relative 'kernel/complete.rb'
-require_relative 'kernel/constant.rb'
 require_relative 'kernel/d.rb'
 require_relative 'kernel/deep_clone.rb'
 require_relative 'kernel/deep_copy.rb'
@@ -48,7 +47,6 @@ require_relative 'kernel/not_nil.rb'
 require_relative 'kernel/object_class.rb'
 require_relative 'kernel/object_hexid.rb'
 require_relative 'kernel/object_send.rb'
-require_relative 'kernel/p.rb'
 require_relative 'kernel/presence.rb'
 require_relative 'kernel/present.rb'
 require_relative 'kernel/qua_class.rb'
@@ -57,8 +55,8 @@ require_relative 'kernel/respond.rb'
 require_relative 'kernel/returning.rb'
 require_relative 'kernel/silence.rb'
 require_relative 'kernel/silence_warnings.rb'
-require_relative 'kernel/singleton_class.rb'
 require_relative 'kernel/super_method.rb'
+require_relative 'kernel/functor.rb'
 require_relative 'kernel/tap.rb'
 require_relative 'kernel/temporarily.rb'
 #require_relative 'kernel/trap_chain.rb'        # uncommon
@@ -70,7 +68,7 @@ require_relative 'kernel/writers.rb'
 #require_relative 'kernel/y.rb'                 # uncommon
 require_relative 'kernel/yes.rb'
 require_relative 'kernel/__class__.rb'
-require_relative 'kernel/__dir__.rb'
+#require_relative 'kernel/__dir__.rb'  # removed, use Ruby's built-in __dir__
 require_relative 'kernel/__get__.rb'
 require_relative 'kernel/__set__.rb'
 

data/lib/core/facets/lazy.rb

@@ -10,7 +10,7 @@
 #
 # Copyright (c) 2005 MenTaLguY <mental@rydia.net>
 #
-# Ruby License
+# Ruby License / BSD-2 License
 #
 # This module is free software. You may use, modify, and/or redistribute this
 # software under the same terms as Ruby.