facets 3.1.0 → 3.2.1

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.

data/lib/core/facets/matchdata.rb

@@ -1,3 +1,3 @@
-require_relative 'matchdata/match.rb'
+#require_relative 'matchdata/match.rb'  # removed: now provided by Ruby
 require_relative 'matchdata/matchset.rb'
 

data/lib/core/facets/module/alias_method_chain.rb

@@ -1,50 +1,12 @@
 class Module
 
-  # Encapsulates the common pattern of ...
+  # @deprecated Use Module#prepend instead (built-in since Ruby 2.0).
   #
-  #   alias_method :foo_without_feature, :foo
-  #   alias_method :foo, :foo_with_feature
+  # The alias_method_chain pattern has been superseded by Module#prepend,
+  # which provides a cleaner way to wrap methods.
   #
-  # With this, you simply do ...
-  #
-  #   alias_method_chain :foo, :feature
-  #
-  # For example
-  #
-  #   class AliasMethodChainExample
-  #     def foo 
-  #       "foo"
-  #     end
-  #
-  #     def foo_with_feature
-  #       "foo!"
-  #     end
-  #
-  #     alias_method_chain :foo, :feature
-  #   end
-  #
-  # And both aliases are set up for you.
-  #
-  #   example = AliasMethodChainExample.new
-  #   example.foo #=> "foo!"
-  #   example.foo_without_feature #=> "foo"
-  #
-  # Query and bang methods (foo?, foo!) keep the same punctuation ...
-  #
-  #   alias_method_chain :foo?, :feature
-  #
-  # is equivalent to ...
-  #
-  #   alias_method :foo_without_feature?, :foo?
-  #   alias_method :foo?, :foo_with_feature?
-  #
-  # so you can safely chain foo, foo?, and foo! with the same feature.
-  #
-  # CREDIT: Bitsweat, Rails Team
-
   def alias_method_chain(target, feature)
-    # Strip out punctuation on predicates or bang methods since
-    # e.g. target?_without_feature is not a valid method name.
+    warn "Module#alias_method_chain is deprecated. Use Module#prepend instead.", uplevel: 1
     aliased_target, punctuation = target.to_s.sub(/([?!=])$/, ''), $1
     yield(aliased_target, punctuation) if block_given?
 
@@ -64,4 +26,3 @@ class Module
   end
 
 end
-

data/lib/core/facets/module/attr_setter.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 class Module
 
   # Create an attribute method for both getting
@@ -19,7 +20,7 @@ class Module
   # CREDIT: Trans
 
   def attr_setter(*args)
-    code, made = '', []
+    code, made = [], []
     args.each do |a|
       code << %{
         def #{a}(*args)
@@ -28,7 +29,7 @@ class Module
       }
       made << "#{a}".to_sym
     end
-    module_eval code
+    module_eval code.join
     made
   end
 

data/lib/core/facets/module/can.rb

@@ -1,20 +1,9 @@
 class Module
 
-  # An alias for #extend.
-  #
-  #   module EgCan
-  #     def foo; "foo"; end
-  #   end
-  #
-  #   class EgCanClass
-  #     can EgCan
-  #   end
-  #
-  #   EgCanClass.foo  #=> 'foo'
-  #
-  # BTW, why is Forwardable an -able? It's not a mixin!
-
-  alias_method :can, :extend
+  # @deprecated Use Module#extend instead.
+  def can(*mods)
+    warn "Module#can is deprecated. Use Module#extend instead.", uplevel: 1
+    extend(*mods)
+  end
 
 end
-

data/lib/core/facets/module/class_extend.rb

@@ -42,7 +42,7 @@ class Module
   def class_extend(*mods, &block)
     class_extension = Module.new
 
-    class_extension.__send__(:include, *mods)
+    class_extension.__send__(:include, *mods) if mods.any?
     class_extension.module_eval(&block) if block_given?
 
     extend(class_extension)  # extend this module too
@@ -83,7 +83,7 @@ class Class
   #
   def class_extend(*mods, &block)
     class_extension = Module.new
-    class_extension.__send__(:include, *mods)
+    class_extension.__send__(:include, *mods) if mods.any?
     class_extension.module_eval(&block) if block
     extend(class_extension)
     class_extensions << class_extension

data/lib/core/facets/numeric.rb

@@ -1,8 +1,8 @@
 require_relative 'numeric/approx.rb'
 require_relative 'numeric/distance.rb'
 require_relative 'numeric/length.rb'
-require_relative 'numeric/negative.rb'
-require_relative 'numeric/positive.rb'
+#require_relative 'numeric/negative.rb'  # removed: now provided by Ruby
+#require_relative 'numeric/positive.rb'  # removed: now provided by Ruby
 require_relative 'numeric/round_to.rb'
 require_relative 'numeric/spacing.rb'
 

data/lib/core/facets/object/dup.rb

@@ -1,20 +1,4 @@
 class Object
-  # Override this in a child class if it cannot be dup'ed.
-  #
-  #   obj1 = Object.new
-  #   obj2 = obj1.dup!
-  #   obj2.equal?(obj1)    #=> false
-  #
-  # CREDIT: Dan Kubb (extlib)
-  def dup!
-    dup
-  end
-
-  # Alternative name for #dup!
-  def try_dup
-    dup!
-  end
-
   # Can you safely call #dup on this object?
   #
   # Returns +false+ for +nil+, +false+, +true+, symbols, and numbers;
@@ -24,56 +8,26 @@ class Object
 end
 
 class NilClass
-  # Since NilClass is immutable it cannot be duplicated.
-  # For this reason #try_dup returns +self+.
-  #
-  #   nil.dup!  #=> nil
-  #
-  def dup!   ; self  ; end
   def dup?   ; false ; end
   def clone? ; false ; end
 end
 
 class FalseClass
-  # Since FalseClass is immutable it cannot be duplicated.
-  # For this reason #try_dup returns +self+.
-  #
-  #   false.dup!  #=> false
-  #
-  def dup!   ; self  ; end
   def dup?   ; false ; end
   def clone? ; false ; end
 end
 
 class TrueClass
-  # Since TrueClass is immutable it cannot be duplicated.
-  # For this reason #try_dup returns +self+.
-  #
-  #   true.dup!  #=> true
-  #
-  def dup!   ; self  ; end
   def dup?   ; false ; end
   def clone? ; false ; end
 end
 
 class Symbol
-  # Since Symbol is immutable it cannot be duplicated.
-  # For this reason #try_dup returns +self+.
-  #
-  #   :a.dup!  #=> :a
-  #
-  def dup!   ; self  ; end
   def dup?   ; false ; end
   def clone? ; false ; end
 end
 
 class Numeric
-  # Since Numeric is immutable it cannot be duplicated.
-  # For this reason #try_dup returns +self+.
-  #
-  #   1.dup!  #=> 1
-  #
-  def dup!   ; self  ; end
   def dup?   ; false ; end
   def clone? ; false ; end
 end

data/lib/core/facets/object.rb

@@ -1,7 +1,7 @@
 # TODO: Is there a good reason for these to be here instead of in Kernel module?
 require_relative 'object/clone.rb'
 require_relative 'object/dup.rb'
-require_relative 'object/itself.rb'
+#require_relative 'object/itself.rb'  # removed: now provided by Ruby
 require_relative 'object/object_state.rb'
-require_relative 'object/try_dup.rb'
+#require_relative 'object/try_dup.rb'  # removed
 

data/lib/core/facets/proc/bind.rb

@@ -1,5 +1,3 @@
-require 'facets/kernel/singleton_class'
-
 class Proc
 
   # Bind a Proc to an object returning a Method.

data/lib/core/facets/proc/compose.rb

@@ -1,42 +1,21 @@
 class Proc
 
-  # Returns a new proc that is the functional
-  # composition of two procs, in order.
-  #
-  #   a = lambda { |x| x + 4 }
-  #   b = lambda { |y| y / 2 }
-  #
-  #   a.compose(b).call(4)  #=> 6
-  #   b.compose(a).call(4)  #=> 4
-  #
-  # CREDIT: Dave
-
+  # @deprecated Use Proc#>> or Proc#<< instead (built-in since Ruby 2.6).
   def compose(g)
-    raise ArgumentError, "arity count mismatch" unless arity == g.arity
-    lambda{ |*a| self[ *g[*a] ] }
+    warn "Proc#compose is deprecated. Use Proc#<< instead (right-to-left composition).", uplevel: 1
+    self << g
   end
 
-  # Operator for Proc#compose and Integer#times_collect/of.
-  #
-  #   a = lambda { |x| x + 4 }
-  #   b = lambda { |y| y / 2 }
-  #
-  #   (a * b).call(4)  #=> 6
-  #   (b * a).call(4)  #=> 4
-  #
-  # CREDIT: Dave
-
+  # @deprecated Use Proc#>> or Proc#<< for composition (built-in since Ruby 2.6).
   def *(x)
-    if Integer===x
-      # collect times
+    warn "Proc#* is deprecated. Use Proc#<< for composition (right-to-left).", uplevel: 1
+    if Integer === x
       c = []
       x.times{|i| c << call(i)}
       c
     else
-      # compose procs
-      lambda{|*a| self[x[*a]]}
+      self << x
     end
   end
 
 end
-

data/lib/core/facets/proc/to_method.rb

@@ -1,5 +1,4 @@
 require 'facets/proc/bind'
-require 'facets/kernel/singleton_class'
 
 class Proc
 

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

@@ -1,6 +1,13 @@
 class Proc
 
-  # Use a Proc as an observable.
+  # Alias for #call, allowing a Proc to be used as an Observer.
+  #
+  # Ruby's Observable module (now the `observer` gem, removed from
+  # stdlib in Ruby 3.2) calls #update on observers. This alias
+  # lets a Proc serve as an observer directly.
+  #
+  # TODO: Consider submitting a PR to the observer gem to include
+  # this extension there instead.
   #
   # CREDIT: Tim Pease
 

data/lib/core/facets/process.rb

@@ -1,2 +1,2 @@
-require_relative 'process/daemon.rb'
+#require_relative 'process/daemon.rb'  # removed: now provided by Ruby
 

data/lib/core/facets/range/intersection.rb

@@ -0,0 +1,42 @@
+class Range
+
+  # Returns the intersection of two or more ranges — the region they
+  # all share. Returns nil if the ranges do not overlap.
+  #
+  # Works with any comparable type: integers, floats, dates, strings, etc.
+  #
+  # Examples
+  #
+  #     Range.intersection(1..10, 5..15)         #=> 5..10
+  #     Range.intersection(1..5, 3..7, 4..9)     #=> 4..5
+  #     Range.intersection(1..3, 5..7)            #=> nil
+  #     Range.intersection(1.0..5.0, 2.5..4.5)   #=> 2.5..4.5
+  #
+  # Also available as an instance method:
+  #
+  #     (1..10).intersection(5..15)              #=> 5..10
+  #
+  # CREDIT: Trans
+
+  def self.intersection(*ranges)
+    return nil if ranges.empty?
+    ranges.reduce do |result, r|
+      return nil unless result.overlap?(r)
+      new_first = result.first > r.first ? result.first : r.first
+      new_last  = result.last  < r.last  ? result.last  : r.last
+      new_first..new_last
+    end
+  end
+
+  # Returns the intersection of this range with one or more other ranges.
+  # Returns nil if the ranges do not overlap.
+  #
+  #     (1..10).intersection(5..15)        #=> 5..10
+  #     (1..10).intersection(5..15, 8..20) #=> 8..10
+  #     (1..3).intersection(5..7)          #=> nil
+  #
+  def intersection(*others)
+    Range.intersection(self, *others)
+  end
+
+end

data/lib/core/facets/range/nudge.rb

@@ -10,16 +10,14 @@ class Range
   #
   # CREDIT: Codeindulgence
 
-  def nudge(options_or_number = 1)
-    if options_or_number.instance_of? Fixnum
-      {:min => options_or_number, :max => options_or_number}
-      min = options_or_number
-      max = options_or_number
+  def nudge(value = 1, min: nil, max: nil)
+    if min or max
+      min ||= 0
+      max ||= 0
     else
-      min = options_or_number[:min].to_i
-      max = options_or_number[:max].to_i
+      min = max = value
     end
-
+    
     if exclude_end?
       (self.min + min)...((self.max + 1) + max)
     else

data/lib/core/facets/range.rb

@@ -1,5 +1,5 @@
 require_relative 'range/combine.rb'
-require_relative 'range/overlap.rb'
+#require_relative 'range/intersection.rb' # too new
 #require_relative 'range/quantile.rb'     # uncommon
 #require_relative 'range/op_add.rb'       # too new
 #require_relative 'range/op_sub.rb'       # too new

data/lib/core/facets/string/ascii_only.rb

@@ -21,7 +21,7 @@ class String
       :replace                     => alt,       # Use a blank for those replacements
       :UNIVERSAL_NEWLINE_DECORATOR => true       # Always break lines with \n
     }
-    self.encode(Encoding.find('ASCII'), encoding_options)
+    self.encode(Encoding.find('ASCII'), **encoding_options)
   end
 
   # Modify string keeping only ASCII characters.
@@ -46,7 +46,7 @@ class String
       :replace                     => alt,       # Use a blank for those replacements
       :UNIVERSAL_NEWLINE_DECORATOR => true       # Always break lines with \n
     }
-    self.encode!(Encoding.find('ASCII'), encoding_options)
+    self.encode!(Encoding.find('ASCII'), **encoding_options)
   end
 
 end