facets 3.1.0 → 3.2.0

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

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

@@ -1,5 +1,3 @@
-require "facets/enumerator"
-
 class String
 
   # Returns an Enumerator for iterating over each

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

@@ -0,0 +1,21 @@
+class String
+
+  # Dashcase a string such that camelcase, underscores and spaces are
+  # replaced by dashes. This is similar to {#underscore},
+  # but with dashes instead of underscores.
+  #
+  #   "DashCase".dashcase         #=> "dash-case"
+  #   "Dash-Case".dashcase        #=> "dash-case"
+  #   "Dash Case".dashcase        #=> "dash-case"
+  #   "Dash  -  Case".dashcase    #=> "dash-case"
+
+  def dashcase
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr('_', '-').
+    gsub(/\s/, '-').
+    gsub(/__+/, '-').
+    downcase
+  end
+
+end

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

@@ -1,6 +1,6 @@
 class String
 
-  # Left chomp.
+  # Left chomp. Alias for #delete_prefix.
   #
   #   "help".lchomp("h")  #=> "elp"
   #   "help".lchomp("k")  #=> "help"
@@ -8,26 +8,19 @@ class String
   # CREDIT: Trans
 
   def lchomp(match)
-    if index(match) == 0
-      self[match.size..-1]
-    else
-      self.dup
-    end
+    delete_prefix(match)
   end
 
-  # In-place left chomp.
+  # In-place left chomp. Alias for #delete_prefix!.
   #
-  #   "help".lchomp("h")  #=> "elp"
-  #   "help".lchomp("k")  #=> "help"
+  #   s = "help"
+  #   s.lchomp!("h")  #=> "elp"
+  #   s                #=> "elp"
   #
   # CREDIT: Trans
 
   def lchomp!(match)
-    if index(match) == 0
-      self[0...match.size] = ''
-      self
-    end
+    delete_prefix!(match)
   end
 
 end
-

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

@@ -1,5 +1,3 @@
-require "facets/enumerator"
-
 class String
 
   # Returns an Enumerator for iterating over each

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

@@ -9,11 +9,11 @@ class String
   #   "Snake Case".snakecase        #=> "snake_case"
   #   "Snake  -  Case".snakecase    #=> "snake_case"
   #
-  # Note, this method no longer converts `::` to `/`, in that case
-  # use the {#pathize} method instead.
+  # Note, unlike #underscore this does not convert `::` to `/`.
+  # Use {#pathize} for that, or use {#underscore} for ActiveSupport
+  # compatible behavior.
 
   def snakecase
-    #gsub(/::/, '/').
     gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
     gsub(/([a-z\d])([A-Z])/,'\1_\2').
     tr('-', '_').
@@ -22,10 +22,17 @@ class String
     downcase
   end
 
+  # Like #snakecase but also converts '::' to '/' for
+  # namespace-to-path conversion. This is compatible with
+  # ActiveSupport's #underscore.
   #
-  alias_method :underscore, :snakecase
+  #   "SnakeCase".underscore        #=> "snake_case"
+  #   "Foo::Bar".underscore         #=> "foo/bar"
+  #
+  def underscore
+    gsub(/::/, '/').snakecase
+  end
 
   # TODO: Add *separators to #snakecase, like camelcase.
 
 end
-

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

@@ -7,6 +7,18 @@ class String
   def words
     self.split(/\s+/)
   end
-
+  
+  # Returns an array of words in the commonly-understood sense (not including punctuation).
+  # This takes into account international punctuation characters as well as English ones.
+  # 
+  #     'Slowly, grudgingly he said: "This has to stop."'.words
+  #      => ["Slowly", "grudgingly", "he", "said", "This", "has", "to", "stop"]
+  def words_without_punctuation
+    s = self.dup
+    s.gsub!(/[.?¿¡…!,:：;—"。？！、‘“”„«»〈〉《》，\/\[\]]/, ' ')
+    s.gsub!('- ', ' ')
+    s.squeeze!(" ")
+    s.strip.split(" ")
+  end  
 end
 

data/lib/core/facets/string.rb

@@ -3,7 +3,6 @@ require_relative 'string/align.rb'
 require_relative 'string/bracket.rb'
 require_relative 'string/camelcase.rb'
 require_relative 'string/capitalized.rb'
-require_relative 'string/characters.rb'
 require_relative 'string/cleanlines.rb'
 require_relative 'string/cleave.rb'
 require_relative 'string/cmp.rb'

data/lib/core/facets/struct/attributes.rb

@@ -6,9 +6,8 @@ class Struct
   # This will eventually be deprecated in favor of #to_h.
 
   def attributes
-    h = {}
-    each_pair { |k,v| h[k] = v }
-    h
+    warn "Struct#attributes is deprecated. Use Struct#to_h instead.", uplevel: 1
+    to_h
   end
 
 end

data/lib/core/facets/time/trunc.rb

@@ -1,15 +1,22 @@
 class Time
 
-  # Truncate time at give range (in seconds).
+  # Truncate time to a given interval in seconds.
+  # Unlike Ruby's Time#floor which takes sub-second digit precision,
+  # this takes an interval in seconds.
   #
   #   t = Time.now
-  #   t = t.trunc(60*60)
+  #   t = t.floor_to(60*60)
   #   t.min #=> 0
   #   t.sec #=> 0
   #
-  def trunc(amount)
-    self - (self.to_i % amount)
+  def floor_to(seconds)
+    self - (self.to_i % seconds)
   end
 
-end
+  # @deprecated Use Time#floor_to instead.
+  def trunc(seconds)
+    warn "Time#trunc is deprecated. Use Time#floor_to instead.", uplevel: 1
+    floor_to(seconds)
+  end
 
+end

data/lib/core/facets/unboundmethod/arguments.rb

@@ -19,6 +19,7 @@ class UnboundMethod
   # CREDIT: Trans
 
   def arguments
+    warn "UnboundMethod#arguments is deprecated. Use UnboundMethod#parameters instead.", uplevel: 1
     ar = arity
     case ar <=> 0
     when 1

data/lib/core/facets/version.rb

@@ -1,19 +1,3 @@
 module Facets
-  #
-  def self.index
-    @index ||= (
-      require 'yaml'
-      YAML.load(File.new(File.dirname(__FILE__) + '/facets.yml'))
-    )
-  end
-
-  #
-  def self.const_missing(name)
-    key = name.to_s.downcase
-    index[key] || super(name)
-  end
-
-  # deprecate
-  VERSION = '3.0.0'
+  VERSION = '3.2.0'
 end
-

data/lib/core/facets.rb

@@ -8,7 +8,6 @@ require 'facets/comparable.rb'
 require 'facets/denumerable.rb'
 require 'facets/dir.rb'
 require 'facets/enumerable.rb'
-require 'facets/enumerator.rb'
 require 'facets/exception.rb'
 require 'facets/file.rb'
 require 'facets/filetest.rb'

data/lib/standard/facets/argvector.rb

@@ -29,7 +29,7 @@
 #
 # Copyright (c) 2006 Thomas Sawyer
 #
-# 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.