facets 3.2.2 → 4.0.0

data/lib/core/facets/rails_bridge.rb

@@ -0,0 +1,27 @@
+module Facets
+
+  # Until 2027-09-30, `require 'facets'` still provides a few Rails-compatible
+  # methods that now live in lib/rails. Each is defined here as a stub that
+  # warns on first use, loads the real file (which replaces the stub), and
+  # retries the call. Requiring the file directly skips the stub and the
+  # warning. Methods that are already defined, e.g. by ActiveSupport, are
+  # left alone.
+  #
+  #   Facets.rails_bridge(Hash, 'facets/hash/slice', :slice!)
+  #
+  def self.rails_bridge(owner, file, *names)
+    names.each do |name|
+      next if owner.method_defined?(name)
+      owner.send(:define_method, name) do |*args, &block|
+        warn "#{owner}##{name} will no longer be loaded by `require 'facets'` after 2027-09-30. " \
+             "Add `require '#{file}'` to keep using it.", uplevel: 1
+        require file
+        if owner.instance_method(name).source_location&.first == __FILE__
+          raise NoMethodError, "#{file} did not define #{owner}##{name}"
+        end
+        __send__(name, *args, &block)
+      end
+    end
+  end
+
+end

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

@@ -52,8 +52,11 @@ class String
   #
   # @deprecated
   #   Use `#camelcase(:upper)` instead.
+  #   Scheduled for removal after 2027-09-30.
   #
   def upper_camelcase(*separators)
+    warn "String#upper_camelcase is deprecated. Use String#camelcase(:upper) instead. " \
+         "It will be removed after 2027-09-30.", uplevel: 1
     camelcase(:upper, *separators)
   end
 
@@ -64,8 +67,11 @@ class String
   #
   # @deprecated
   #   Use `#camelcase(:lower)` instead.
+  #   Scheduled for removal after 2027-09-30.
   #
   def lower_camelcase(*separators)
+    warn "String#lower_camelcase is deprecated. Use String#camelcase(:lower) instead. " \
+         "It will be removed after 2027-09-30.", uplevel: 1
     camelcase(:lower, *separators)
   end
 

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

@@ -82,8 +82,9 @@ class String
 
     score = 0.0
     matches.each{ |mm| score += mm.length }
-    self.length > str_in.length ? largest = self.length : largest = str_in.length
-    return score/(largest+1)
+    largest = [self.length, str_in.length].max
+    return 0.0 if largest.zero?   # e.g. an empty Symbol or Array
+    return score/largest
   end
 
 end

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

@@ -6,7 +6,7 @@ class Struct
   # This will eventually be deprecated in favor of #to_h.
 
   def attributes
-    warn "Struct#attributes is deprecated. Use Struct#to_h instead.", uplevel: 1
+    warn "Struct#attributes is deprecated. Use Struct#to_h instead. It will be removed after 2027-09-30.", uplevel: 1
     to_h
   end
 

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

@@ -4,9 +4,14 @@ class Time
 
     # To be able to keep Dates and Times interchangeable
     # on conversions.
-
+    #
+    # @deprecated Ruby defines Time#to_time once 'date' is loaded.
+    #   Scheduled for removal after 2027-09-30.
+    #
     def to_time
-      getlocal 
+      warn "Facets' Time#to_time is deprecated. Require 'date' for Ruby's own Time#to_time. " \
+           "It will be removed after 2027-09-30.", uplevel: 1
+      getlocal
     end
 
     # A method to keep Time, Date and DateTime instances interchangeable

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

@@ -14,8 +14,9 @@ class Time
   end
 
   # @deprecated Use Time#floor_to instead.
+  #   Scheduled for removal after 2027-09-30.
   def trunc(seconds)
-    warn "Time#trunc is deprecated. Use Time#floor_to instead.", uplevel: 1
+    warn "Time#trunc is deprecated. Use Time#floor_to instead. It will be removed after 2027-09-30.", uplevel: 1
     floor_to(seconds)
   end
 

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

@@ -19,7 +19,7 @@ class UnboundMethod
   # CREDIT: Trans
 
   def arguments
-    warn "UnboundMethod#arguments is deprecated. Use UnboundMethod#parameters instead.", uplevel: 1
+    warn "UnboundMethod#arguments is deprecated. Use UnboundMethod#parameters instead. It will be removed after 2027-09-30.", uplevel: 1
     ar = arity
     case ar <=> 0
     when 1

data/lib/core/facets/version.rb

@@ -1,3 +1,3 @@
 module Facets
-  VERSION = '3.2.2'
+  VERSION = '4.0.0'
 end

data/lib/rails/facets/hash/to_options.rb

@@ -0,0 +1,14 @@
+require 'facets/hash/symbolize_keys'
+
+class Hash
+
+  # Rails' name for #symbolize_keys.
+  #
+  #   {'a'=>1}.to_options  #=> {:a=>1}
+  #
+  alias_method :to_options,  :symbolize_keys
+
+  # Rails' name for #symbolize_keys!.
+  alias_method :to_options!, :symbolize_keys!
+
+end

data/lib/{core → rails}/facets/module/mattr.rb

@@ -19,13 +19,13 @@ class Module
   # @uncommon
   #   require 'facets/module/cattr'
   #
-  def cattr(*syms)
+  def cattr(*syms, &block)
     writers, readers = syms.flatten.partition{ |a| a.to_s =~ /=$/ }
     writers = writers.map{ |e| e.to_s.chomp('=').to_sym }
     ##readers.concat( writers ) # writers also get readers
 
-    cattr_reader(*readers)
-    cattr_writer(*writers)
+    cattr_reader(*readers, &block)
+    cattr_writer(*writers, &block)
 
     return readers + writers
   end
@@ -49,13 +49,13 @@ class Module
   # @uncommon
   #   require 'facets/module/cattr'
   #
-  def cattr_reader(*syms)
+  def cattr_reader(*syms, &block)
     syms.flatten.each do |sym|
-      module_eval(<<-EOS, __FILE__, __LINE__)
-        unless defined? @@#{sym}
-          @@#{sym} = nil
-        end
+      unless class_variable_defined?("@@#{sym}")
+        class_variable_set("@@#{sym}", block ? block.call : nil)
+      end
 
+      module_eval(<<-EOS, __FILE__, __LINE__)
         def self.#{sym}
           @@#{sym}
         end
@@ -91,13 +91,13 @@ class Module
   # @uncommon
   #   require 'facets/module/cattr'
   #
-  def cattr_writer(*syms)
+  def cattr_writer(*syms, &block)
     syms.flatten.each do |sym|
-      module_eval(<<-EOS, __FILE__, __LINE__)
-        unless defined? @@#{sym}
-          @@#{sym} = nil
-        end
+      unless class_variable_defined?("@@#{sym}")
+        class_variable_set("@@#{sym}", block ? block.call : nil)
+      end
 
+      module_eval(<<-EOS, __FILE__, __LINE__)
         def self.#{sym}=(obj)
           @@#{sym} = obj
         end
@@ -130,8 +130,8 @@ class Module
   # @uncommon
   #   require 'facets/module/cattr'
   #
-  def cattr_accessor(*syms)
-    cattr_reader(*syms) + cattr_writer(*syms)
+  def cattr_accessor(*syms, &block)
+    cattr_reader(*syms, &block) + cattr_writer(*syms)
   end
 
   # Creates a class-variable attribute that can
@@ -159,13 +159,13 @@ class Module
   # @uncommon
   #   require 'facets/module/mattr'
   #
-  def mattr(*syms)
+  def mattr(*syms, &block)
     writers, readers = syms.flatten.partition{ |a| a.to_s =~ /=$/ }
     writers = writers.collect{ |e| e.to_s.chomp('=').to_sym }
     ##readers.concat( writers ) # writers also get readers
 
-    mattr_writer( *writers )
-    mattr_reader( *readers )
+    mattr_writer( *writers, &block )
+    mattr_reader( *readers, &block )
 
     return readers + writers
   end
@@ -189,13 +189,13 @@ class Module
   # @uncommon
   #   require 'facets/module/mattr'
   #
-  def mattr_reader( *syms )
+  def mattr_reader( *syms, &block )
     syms.flatten.each do |sym|
-      module_eval(<<-EOS, __FILE__, __LINE__)
-        unless defined? @@#{sym}
-          @@#{sym} = nil
-        end
+      unless class_variable_defined?("@@#{sym}")
+        class_variable_set("@@#{sym}", block ? block.call : nil)
+      end
 
+      module_eval(<<-EOS, __FILE__, __LINE__)
         def self.#{sym}
           @@#{sym}
         end
@@ -232,13 +232,13 @@ class Module
   # @uncommon
   #   require 'facets/module/mattr'
   #
-  def mattr_writer(*syms)
+  def mattr_writer(*syms, &block)
     syms.flatten.each do |sym|
-      module_eval(<<-EOS, __FILE__, __LINE__)
-        unless defined? @@#{sym}
-          @@#{sym} = nil
-        end
+      unless class_variable_defined?("@@#{sym}")
+        class_variable_set("@@#{sym}", block ? block.call : nil)
+      end
 
+      module_eval(<<-EOS, __FILE__, __LINE__)
         def self.#{sym}=(obj)
           @@#{sym} = obj
         end
@@ -272,8 +272,8 @@ class Module
   # @uncommon
   #   require 'facets/module/mattr'
   #
-  def mattr_accessor(*syms)
-    mattr_reader(*syms) + mattr_writer(*syms)
+  def mattr_accessor(*syms, &block)
+    mattr_reader(*syms, &block) + mattr_writer(*syms)
   end
 
 end

data/lib/standard/facets/cloneable.rb

@@ -1,6 +1,7 @@
 # @deprecated Use deep_dup/deep_clone instead, or define your own
 #   initialize_copy method.
-warn "facets/cloneable is deprecated. Use deep_dup/deep_clone instead.", uplevel: 1
+#   Scheduled for removal after 2027-09-30.
+warn "facets/cloneable is deprecated. Use deep_dup/deep_clone instead. It will be removed after 2027-09-30.", uplevel: 1
 
 module Cloneable
 

data/lib/standard/facets/continuation.rb

@@ -1,2 +1,3 @@
 # @deprecated callcc is obsolete in Ruby. Use Fiber instead.
-warn "facets/continuation is deprecated. callcc is obsolete; use Fiber instead.", uplevel: 1
+#   Scheduled for removal after 2027-09-30.
+warn "facets/continuation is deprecated. callcc is obsolete; use Fiber instead. It will be removed after 2027-09-30.", uplevel: 1

data/lib/standard/facets/enumargs.rb

@@ -54,8 +54,8 @@ module Enumerable
         # this branch is used when the method has a variable number of arguments
         #   resulting in an arity of -1.  Right now this is bugged as it does
         #   not pass the argument to the each, and always passes the argument
-        #   to the method.  This makes methods like .min amdn .max to act
-        #   in an unexpected manner.
+        #   to the method. #min and #max are defined explicitly below for
+        #   this reason.
         class_eval %{
           def #{m}( *args, &yld )
             enum_for(:each).#{m}( *args, &yld )
@@ -76,6 +76,18 @@ module Enumerable
       enum_for(:each, *args).to_a
     end
 
+    # Support for #min and #max. Ruby's own versions take an optional
+    # count, so the generic wrapper would pass the argument to them
+    # instead of to #each.
+    #
+    def min(*args, &yld)
+      enum_for(:each, *args).min(&yld)
+    end
+
+    def max(*args, &yld)
+      enum_for(:each, *args).max(&yld)
+    end
+
     # Make exception for #find (a negative arity method) to accept
     # keyword argument.
     #

data/lib/standard/facets/getoptlong.rb

@@ -1,3 +1,4 @@
 # @deprecated GetoptLong is a bundled gem heading for removal.
 #   Consider using OptionParser or a modern CLI library instead.
-warn "facets/getoptlong is deprecated. Consider OptionParser instead.", uplevel: 1
+#   Scheduled for removal after 2027-09-30.
+warn "facets/getoptlong is deprecated. Consider OptionParser instead. It will be removed after 2027-09-30.", uplevel: 1

data/lib/standard/facets/interval.rb

@@ -189,11 +189,12 @@ class Interval
   #   1..5.each(2) { |e| ... }     #=> 1 3 5
   #   1..5.each(1,2) { |e| ... }   #=> 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 5.0
   #
-  # @todo Deprecate arguments and simplify each definition accordingly.
+  # @deprecated The +n+ and +d+ arguments. Use +interval.step(n,d).each+ instead.
+  #   Scheduled for removal after 2027-09-30.
   def each(n=nil, d=nil)  # :yield:
     if n
-      warn "FACETS: `interval.each(n,d){...}` will be deprecated.\n" +
-           "Use `interval.step(n,d).each{...}` instead."
+      warn "Interval#each(n, d) is deprecated. Use interval.step(n, d).each instead. " \
+           "It will be removed after 2027-09-30.", uplevel: 1
     else
       n = 1
     end

data/lib/standard/facets/load_monitor.rb

@@ -1,2 +1,3 @@
 # @deprecated Monkey-patching require/load globally is dangerous.
-warn "facets/load_monitor is deprecated. It monkey-patches require/load globally.", uplevel: 1
+#   Scheduled for removal after 2027-09-30.
+warn "facets/load_monitor is deprecated. It monkey-patches require/load globally. It will be removed after 2027-09-30.", uplevel: 1

data/lib/standard/facets/pathname/null.rb

@@ -1,8 +1,9 @@
 class Pathname
 
   # @deprecated Use Pathname.new(File::NULL) instead.
+  #   Scheduled for removal after 2027-09-30.
   def self.null
-    warn "Pathname.null is deprecated. Use Pathname.new(File::NULL) instead.", uplevel: 1
+    warn "Pathname.null is deprecated. Use Pathname.new(File::NULL) instead. It will be removed after 2027-09-30.", uplevel: 1
     new(File::NULL)
   end
 

data/lib/standard/facets/random.rb

@@ -117,26 +117,30 @@ class Random
     end
 
     # @deprecated Use Array#sample instead.
+    #   Scheduled for removal after 2027-09-30.
     def at_rand
-      warn "Array#at_rand is deprecated. Use Array#sample instead.", uplevel: 1
+      warn "Array#at_rand is deprecated. Use Array#sample instead. It will be removed after 2027-09-30.", uplevel: 1
       sample
     end
 
     # @deprecated Use Array#sample! instead.
+    #   Scheduled for removal after 2027-09-30.
     def at_rand!
-      warn "Array#at_rand! is deprecated. Use Array#sample! instead.", uplevel: 1
+      warn "Array#at_rand! is deprecated. Use Array#sample! instead. It will be removed after 2027-09-30.", uplevel: 1
       sample!
     end
 
     # @deprecated Use Array#sample instead.
+    #   Scheduled for removal after 2027-09-30.
     def pick(n=nil)
-      warn "Array#pick is deprecated. Use Array#sample instead.", uplevel: 1
+      warn "Array#pick is deprecated. Use Array#sample instead. It will be removed after 2027-09-30.", uplevel: 1
       n ? sample(n) : sample
     end
 
     # @deprecated Use Array#sample! instead.
+    #   Scheduled for removal after 2027-09-30.
     def pick!(n=nil)
-      warn "Array#pick! is deprecated. Use Array#sample! instead.", uplevel: 1
+      warn "Array#pick! is deprecated. Use Array#sample! instead. It will be removed after 2027-09-30.", uplevel: 1
       sample!(n)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: facets
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Thomas Sawyer
@@ -46,7 +46,6 @@ files:
 - lib/core/facets/array/each_pair.rb
 - lib/core/facets/array/each_value.rb
 - lib/core/facets/array/entropy.rb
-- lib/core/facets/array/extract_options.rb
 - lib/core/facets/array/first.rb
 - lib/core/facets/array/from.rb
 - lib/core/facets/array/indexable.rb
@@ -98,9 +97,7 @@ files:
 - lib/core/facets/binding/self.rb
 - lib/core/facets/binding/with.rb
 - lib/core/facets/boolean.rb
-- lib/core/facets/cattr.rb
 - lib/core/facets/class.rb
-- lib/core/facets/class/cattr.rb
 - lib/core/facets/class/descendants.rb
 - lib/core/facets/class/hierarchically.rb
 - lib/core/facets/class/methodize.rb
@@ -179,7 +176,6 @@ files:
 - lib/core/facets/file/append.rb
 - lib/core/facets/file/atomic_id.rb
 - lib/core/facets/file/atomic_open.rb
-- lib/core/facets/file/atomic_write.rb
 - lib/core/facets/file/common_path.rb
 - lib/core/facets/file/create.rb
 - lib/core/facets/file/ext.rb
@@ -243,13 +239,9 @@ files:
 - lib/core/facets/hash/revalue.rb
 - lib/core/facets/hash/reverse_merge.rb
 - lib/core/facets/hash/setter.rb
-- lib/core/facets/hash/slice.rb
-- lib/core/facets/hash/stringify_keys.rb
 - lib/core/facets/hash/subset.rb
 - lib/core/facets/hash/swap.rb
-- lib/core/facets/hash/symbolize_keys.rb
 - lib/core/facets/hash/to_mod.rb
-- lib/core/facets/hash/to_options.rb
 - lib/core/facets/hash/to_struct.rb
 - lib/core/facets/hash/traverse.rb
 - lib/core/facets/hash/update.rb
@@ -369,7 +361,6 @@ files:
 - lib/core/facets/module/attr_validator.rb
 - lib/core/facets/module/basename.rb
 - lib/core/facets/module/can.rb
-- lib/core/facets/module/cattr.rb
 - lib/core/facets/module/class.rb
 - lib/core/facets/module/class_accessor.rb
 - lib/core/facets/module/class_def.rb
@@ -392,7 +383,6 @@ files:
 - lib/core/facets/module/is.rb
 - lib/core/facets/module/lastname.rb
 - lib/core/facets/module/let.rb
-- lib/core/facets/module/mattr.rb
 - lib/core/facets/module/memoize.rb
 - lib/core/facets/module/method_clash.rb
 - lib/core/facets/module/method_space.rb
@@ -445,6 +435,7 @@ files:
 - lib/core/facets/proc/update.rb
 - lib/core/facets/proc/wrap.rb
 - lib/core/facets/process.rb
+- lib/core/facets/rails_bridge.rb
 - lib/core/facets/range.rb
 - lib/core/facets/range/combine.rb
 - lib/core/facets/range/intersection.rb
@@ -574,6 +565,17 @@ files:
 - lib/core/facets/unboundmethod.rb
 - lib/core/facets/unboundmethod/arguments.rb
 - lib/core/facets/version.rb
+- lib/rails/facets/array/extract_options.rb
+- lib/rails/facets/cattr.rb
+- lib/rails/facets/class/cattr.rb
+- lib/rails/facets/date.rb
+- lib/rails/facets/file/atomic_write.rb
+- lib/rails/facets/hash/slice.rb
+- lib/rails/facets/hash/stringify_keys.rb
+- lib/rails/facets/hash/symbolize_keys.rb
+- lib/rails/facets/hash/to_options.rb
+- lib/rails/facets/module/cattr.rb
+- lib/rails/facets/module/mattr.rb
 - lib/standard/facets/against.rb
 - lib/standard/facets/argvector.rb
 - lib/standard/facets/binding/block_exec.rb
@@ -585,7 +587,6 @@ files:
 - lib/standard/facets/cloneable.rb
 - lib/standard/facets/continuation.rb
 - lib/standard/facets/crypt3.rb
-- lib/standard/facets/date.rb
 - lib/standard/facets/date/cmp.rb
 - lib/standard/facets/digest.rb
 - lib/standard/facets/digest/salted_digest.rb
@@ -740,6 +741,7 @@ rdoc_options: []
 require_paths:
 - lib/core
 - lib/standard
+- lib/rails
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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

@@ -1 +0,0 @@
-require 'facets/hash/symbolize_keys'