facets 3.2.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da62aa5e36dc4d4fbe19984071e7f4bf38acc53a7812c285a50a36b714115f23
-  data.tar.gz: 7244c28aff76e1073f723148e6a9e3006246a26cd59c047dab8a2d8f765a3e3d
+  metadata.gz: af1581fdee797dd22551c3257c73b76e2d0e5ee659ecb60690eee877672a5a00
+  data.tar.gz: 8693eedfa8dc78cfa8c47964cac6f2834996337dc00bbf0e9672c2b664bc2cea
 SHA512:
-  metadata.gz: acc7199da1618757142fede6aece2bdbc324a7d8d95525f4ff40a0ef1085484ec42d3727eb3adcd65be3eccfa210e599d1488dafde8640b04375947b6df96c7b
-  data.tar.gz: 0e561c34ccac85af4fa6b1ce7c28a2396d4326ff75917b6fde31c6618be7cdb46c959fec59454b1a6b4df5a2c3a6812cae72c68ce5bd0a96714afa1dc43bd344
+  metadata.gz: e4a41b846c6bf81d6103ec0fcac3f8b729f5ab324676ab7f2b25a4126bfe878ec36a7113d58b4a7c32c5d1748cd4a1a9ae4ebba80fa82e7226c83bc7d7220af1
+  data.tar.gz: 5c32bd85bdeb4336d5774689023e73d5c7e74ee86eff5003e5ef4da1644f10c6de5c897b6a0f268f09c7976055b28acaba10cf420b546380ae21c4d73508da86

data/CONTRIBUTING.md

@@ -18,14 +18,14 @@
   The Lemon unit tests are for testing a method in detail whereas the QED
   demos are for demonstrating usage.
 
-* Facets is divided into two parts, *core* and *standard* libraries.
-  Almost all of the core library can be loaded at once using `require 'facets'`
-  The standard library (also called the *more* library) must be required
-  per-script.
+* Facets groups libraries into `core`, `standard`, and `rails` areas.
+  Almost all core extensions can be loaded at once with `require 'facets'`.
+  Standard and rails extensions should be required by file.
 
-* Some core methods are included on a *trial* basis, and these are not
-  necessary loaded automatically with `require 'facets'`. These should be
-  documented as such in the method comments.
+* Some core methods are *uncommon* and are not loaded by `require 'facets'`.
+  Mark them with an `@uncommon` tag in the method comments, showing the
+  require line, and comment out their line in the aggregator file with
+  `# uncommon`.
 
 * Standard libraries that are not extensions of existing standard libraries
   do not have to be divvied up into individual method files. But note that
@@ -102,11 +102,40 @@ explanation if needed, including *when* and *why* the method could be useful.
 
 ## Testing
 
-* Methods in `lib/core/facets/{class}/{method}.rb` will be tested in `test/foo/{class}/test_{method}.rb`.
-* If `lib/core/facets/{class}/{method}.rb` consists only of a require statement, no test file is expected.
-* If `lib/core/facets/{class}/{method}.rb` consists only of a require and an alias, then `test/foo/{class}/{method}.rb`, only needs to test the existence of the alias and not the underlying code. But it's okay if the alias is tested further.
-* Methods in `lib/core/facets/{class}/{method}.rb` will be demoed in `demo/core/{class}/{method}.md`.
-* Require only files will have a full demo of it's method or methods. Code in a single file may be split into multiple demos, named after the method. This is to promote discoverability in the documentation.
-* Demos of aliases will have a simple demo, and a reference to the file it aliases
-
-
+The test suite uses four tools:
+
+* **RubyTest** provides the test runner interface; `rubytest-cli` supplies the
+  `ruby-test` command used by the Rake tasks.
+* **Lemon** defines the `test_case`, `method`, and `test` structure of the unit
+  tests.
+* **AE** provides assertions such as `.assert` and `expect`, used in both the
+  unit tests and the QED demos. It is installed as a Lemon dependency.
+* **QED** runs the executable examples in `demo/`. They show how a method is
+  intended to be used as well as checking its behavior.
+
+Install the development dependencies and run the same two suites as CI:
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake qed
+```
+
+For a focused unit test, set `TESTS` to a test file, for example:
+
+```sh
+TESTS=test/core/array/test_average.rb bundle exec rake test
+```
+
+The Rakefile also provides `test:core`, `test:standard`, `test:rails` and the
+corresponding `qed:*` tasks for each library area.
+
+* A core method in `lib/core/facets/{class}/{method}.rb` normally has a Lemon
+  test in `test/core/{class}/test_{method}.rb` and a QED demo in
+  `demo/core/{class}/{method}.md`. Standard and rails libraries use
+  their respective `test/` and `demo/` directories.
+* A file that only requires another file does not need its own unit test. A file
+  that also defines an alias can test the alias without repeating every test
+  for the underlying method.
+* Demos should show the behavior of each method. An alias can have a short demo
+  that points readers to the main method's demo.

data/HISTORY.md

@@ -1,5 +1,100 @@
 # Facets Release History
 
+## 4.0.0 / 2026-09-27
+
+A major release, because it changes behavior: `Kernel#try!` is now the
+lenient variant and `#try` is strict, `require 'facets'` no longer loads
+`Kernel#with`, and Rails-compatible methods move to the new `lib/rails`
+area (still loaded by `require 'facets'` with a warning until 2027-09-30).
+Every deprecation now names that same removal date.
+
+Changes:
+
+* Breaking
+
+  * `Kernel#try!` now returns `nil` when the receiver doesn't respond to the
+    method (or it is private), instead of raising `NoMethodError`. `#try`
+    stays strict. This is deliberately the opposite of ActiveSupport, which
+    since Rails 4.0 makes `#try` lenient and `#try!` strict. In Ruby the bang
+    marks the more dangerous method, and quietly ignoring a missing method is
+    the dangerous behavior. The docs no longer claim ActiveSupport
+    compatibility.
+  * `require 'facets'` no longer loads `Kernel#with`, since a global `with`
+    breaks other libraries' methods of that name, such as RSpec's
+    `receive(...).with` (#290). It is still available, deprecated, with
+    `require 'facets/kernel/with'`.
+  * `Kernel#try` no longer calls private methods. It now behaves exactly like
+    a normal call or `&.`, raising `NoMethodError` for them.
+
+* Enhancements
+
+  * New `lib/rails` library for Rails-compatible methods that Facets carries
+    but doesn't endorse as its own: `Hash#symbolize_keys`/`#stringify_keys`,
+    `Hash#to_options`, `Hash#slice!`, `Array#extract_options!`,
+    `Module#mattr_*`/`#cattr_*`, `File.atomic_write` and the `facets/date`
+    extensions. Require paths are unchanged (`require 'facets/hash/slice'`
+    still works), and `require 'facets'` still provides the same methods.
+
+* Deprecations
+
+  * `require 'facets'` will stop providing the lib/rails methods after
+    2027-09-30. Until then, the first call to one of them through
+    `require 'facets'` warns and names the file to require. Requiring that
+    file directly avoids the warning.
+  * `Kernel#returning`, `Module#alias_method_chain`, `Array#uniq_by!`,
+    `Enumerable#uniq_by`, `Kernel#silence_stream` and Facets' fallback
+    `Time#to_time` are scheduled for removal after 2027-09-30. Each warns
+    with its replacement and the removal date.
+  * Every existing deprecation now names a removal date, 2027-09-30, in its
+    `@deprecated` note and its warning. `String#upper_camelcase`/
+    `#lower_camelcase`, `Kernel#equate?`, `facets/kernel/tee` and
+    `Interval#each(n, d)` were deprecated in docs only (or "will be") and
+    now warn as well.
+  * `Kernel#with` is deprecated in favor of `instance_eval`, also for removal
+    after 2027-09-30. Rails 7.1's unrelated `Object#with` (which temporarily
+    sets attributes) was silently replaced by it when both were loaded.
+  * `Kernel#silence` now does the stream silencing itself; `silently`,
+    `silence_stderr` and `silence_stdout` use it and do not warn.
+
+* Bug Fixes
+
+  * `Hash#to_options` and `#to_options!` now exist. `facets/hash/to_options`
+    only loaded `symbolize_keys` and never defined the aliases.
+  * `Module#alias_module_function` now aliases the singleton method directly.
+    On JRuby, the singleton method `module_function` created turned private
+    when aliased again, which broke `URI.hash_to_query` under the test suite.
+  * `Dir.recurse` and `Dir.ls_r` once again return an Array that leaves out
+    the starting directory. Deprecating them in favor of `Dir.find` had
+    quietly changed both.
+  * `Enumerable::Argumentable#min` and `#max` now pass their arguments to
+    `#each`, as documented, rather than to Ruby's own `min(n)`/`max(n)`.
+  * `String#similarity` now divides the shared length by the longer string's
+    length, not length + 1, so 9 of 10 matching characters score 0.9 as its
+    docs said (it gave 0.818). Scores for non-identical strings rise slightly.
+  * `require 'facets'` no longer crashes on Ruby 4.1, which removed
+    `ObjectSpace._id2ref`. `ObjectSpace[]` is only defined where `_id2ref`
+    exists.
+  * `Kernel#silence` now supports `:verbose`/`:warnings` and `:debug`, as its
+    docs always said, instead of raising `NoMethodError`. They set `$VERBOSE`
+    to nil and `$DEBUG` to false within the block.
+
+* Internal
+
+  * Run the qed demos in CI.
+  * Remove leftover build files that nothing reads anymore: `MANIFEST`,
+    `Assembly` (Detroit), `.index`, `Indexfile` and `lib/core/facets.yml`.
+    The Rakefile takes its version from `Facets::VERSION` (`.index` still said
+    3.1.1), and `rake package` no longer needs the `mast` and `index` tools.
+  * The gemspec reads its version from `Facets::VERSION`, so the version now
+    lives in one place, `lib/core/facets/version.rb`.
+  * Fix the qed demos, which had 8 failures and 2 errors. Most were stale
+    expectations (`Array#from`, `#step`, `#arrange`, `String#similarity`)
+    and the date demo held pasted irb output.
+  * CONTRIBUTING.md explains the test stack (RubyTest, Lemon, AE and QED)
+    and the `@uncommon` convention.
+  * The `String#trim` demo no longer drops random cases, so the QED
+    assertion count is the same on every run.
+
 ## 3.2.2 / 2026-06-15
 
 Patch release with cross-version fixes surfaced by CI on Ruby 3.1–3.4.
@@ -64,6 +159,10 @@ Changes:
 Modernization release targeting Ruby 3.1+. Cleans up long-standing
 compatibility issues and incorporates community contributions.
 
+**Note:** This release removed methods and raised the minimum Ruby version
+to 3.1, so it should have been released as 4.0.0. Treat the 3.2 series as a
+major upgrade from 3.1, and review the Removals below before upgrading.
+
 Changes:
 
 * New Features

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Ruby Facets
-Copyright (c) 2005, Thomas Sawyer
+Copyright (c) 2004, Thomas Sawyer
 All rights reserved.
 
 (BSD-2 LICENSE)

data/README.md

@@ -1,253 +1,84 @@
-# Ruby Facets
+# Ruby Facets <img src="docs/assets/images/cherries.svg" alt="cherries" width="34" height="34">
 
 [![Gem Version](https://badge.fury.io/rb/facets.svg)](https://rubygems.org/gems/facets)
 [![CI](https://github.com/rubyworks/facets/actions/workflows/ci.yml/badge.svg)](https://github.com/rubyworks/facets/actions/workflows/ci.yml)
 
+**More of Ruby, one method at a time.** Facets is a collection of extensions to Ruby's core classes and standard library, plus a few small, reusable classes and modules. Most methods live in their own files, so you can load one extension, a class's extensions, or the core collection.
 
-*"ALL YOUR BASE ARE BELONG TO RUBY"*
+Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **3.2.2**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
 
+## Install
 
-## Introduction
+```sh
+gem install facets
+```
 
-Ruby Facets is the premier collection of general purpose method
-extensions and standard additions for the Ruby programming language.
+With Bundler, add this to your Gemfile:
 
-Facets houses the largest single collection of methods available for
-extending the core capabilities of Ruby's built-in classes and modules.
-This collection of extension methods are unique by virtue of their atomicity.
-The methods are stored in individual files so that each can be required
-independently. This gives developers the potential for much finer control over
-which extra methods to bring into their code.
+```ruby
+gem 'facets', require: false
+```
 
-In addition Facets provides a collection of extensions to Ruby standard library
-plus a small collection of add-on classes and modules. Together these
-libraries constitute an reliable source of reusable components, suitable
-to a wide variety of usecases.
+`require: false` lets you choose which extensions to load. Omit it if you want Bundler to load the core collection automatically.
 
+## Choose how much to load
 
-## Resources
+### One method
 
-* Homepage: https://rubyworks.github.io/facets
-* Report Bugs: https://github.com/rubyworks/facets/issues
-* Wiki Pages: https://github.com/rubyworks/facets/wiki
-* Source Code: https://github.com/rubyworks/facets
+```ruby
+require 'facets/array/to_ranges'
 
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
+```
 
-## Documentation
-
-Facets has special documentation needs due to its extensive breadth.
-The documentation generated when installing via RubyGems, or the YARD
-docs provided by rubydoc.info can be somewhat unwieldy because it
-combines all of Facets in one large set. When using these resources,
-it is important to remain aware of the source location of particular
-methods.
-
-For better organized online documentation, generated to separate core
-extensions from standard libraries, see the [Learn Facets](https://rubyworks.github.io/facets/learn.html) page on the website for links to available documentation.
-
-
-## Installation
-
-### Bundler
-
-If you are using Bundler with your project, add the facets gem to the project's
-Gemfile. Unless you want all of facets loaded be sure to add the `:require => false`
-option.
-
-    gem "facets", require: false
-
-### RubyGems
-
-The easiest way to install is via RubyGems.
-
-    $ gem install facets
-
-### Requirements
-
-Facets 3.2+ requires Ruby 3.1 or higher.
-
-
-## Mission
-
-Facets holds to the notion that the more we can *reasonably* integrate into
-a common foundation, directed toward general needs, the better that foundation
-will be able to serve the community. There are a number of advantages here:
-
-* Better Code-reuse
-* Collaborative Improvements
-* Greater Name Consistency
-* One-stop Shop and Installation
-
-
-## Usage
-
-### CORE Library
-
-At the heart of Ruby Facets is the CORE extensions library. CORE provides
-a sizable collection of generally useful methods, along with a few supporting
-classes, that extend the functionality of Ruby's core classes and modules.
-
-With the exception of a few *uncommon* extensions, CORE contains anything that
-will load automatically when issuing:
-
-    require 'facets'
-
-This loads all the CORE functionality at once. If you plan to use more then a
-handful of Facets core methods it is recommended that you require the library in
-this way. However, you can also "cherry pick" the CORE library as you prefer.
-And for uncommon extensions this must be done. The general require statement for
-a core extension library is:
-
-    require 'facets/<class|module>/<method>'
-
-For example:
-
-    require 'facets/time/stamp'
-
-Most "atoms" contain only one method, but exceptions occur when methods
-are closely tied together.
+### One class's core extensions
 
-You can load per-class or per-module groups of core methods by requiring the
-class or module by name. For example"
+```ruby
+require 'facets/string'
 
-    require 'facets/time'
+'Ruby Facets'.snakecase
+#=> "ruby_facets"
+```
 
-Will require all the core Time method extensions.
+### The core collection
 
-Note that some methods that were part of CORE in 1.8 and earlier are now part
-of MORE libraries. A good example is 'random.rb'. There were separated because
-they had more specialized use cases, where as CORE extensions are intended as
-general purpose.
+```ruby
+require 'facets'
 
-#### Method File Names
+[1, 2, 3].average
+#=> 2.0
+```
 
-Operator method redirect files are stored using English names. For instance 
-`Proc#*` is `proc/op_mul`.
+`require 'facets'` loads the broadly useful **core** extensions: roughly 860 methods from 448 files, adding about 35 ms of load time and 2 MB of memory (Ruby 3.3, Linux). Some specialized core extensions are opt-in; require their method file directly. To load Facets extensions to a Ruby standard library, require that library through Facets:
 
-For reference, here is the chart.
+```ruby
+require 'facets/ostruct'
+```
 
-     +@   => op_plus
-     -@   => op_minus
-     +    => op_add
-     -    => op_sub
-     **   => op_pow
-     *    => op_mul
-     /    => op_div
-     %    => op_mod
-     ~    => op_tilde
-     <=>  => op_cmp
-     <<   => op_lshift
-     >>   => op_rshift
-     <    => op_lt
-     >    => op_gt
-     ===  => op_case
-     ==   => op_equal
-     =~   => op_apply
-     <=   => op_lt_eq
-     >=   => op_gt_eq
-     |    => op_or
-     &    => op_and
-     ^    => op_xor
-     []=  => op_store
-     []   => op_fetch
+This loads `ostruct` and Facets' OpenStruct extensions. On Ruby 3.5+, declare the `ostruct` gem separately because it is no longer a default gem.
 
-Facets simply takes the '*' and translates it into a string acceptable to all
-file systems. Also, if a method ends in '=', '?' or '!' it is simply removed.
-
-
-### MORE Library (aka Standard Library)
-
-On top of the extensive CORE library, Facets provides extensions for Ruby's
-standard library, as well as a small collection of additional modules and
-classes to supplement it.
-
-Use this library like you would any other 3rd party library.
-The only difference between Facet's Standard library and other libraries
-is the lack of any enclosing `Facets::` namespace.
-
-When using Facets extended versions of Ruby's standard libraries,
-the libraries have to loaded individually. However you do not need
-to load Ruby's library first, as the Facets' library will do that
-automatically.
-
-For example, normally one load Ruby's OpenStruct class via:
-
-    require 'ostruct'
-
-To load 'ostruct.rb' plus Facets extensions for it simply use:
-
-    require 'facets/ostruct'
+## Documentation
 
-For details pertaining to the functionality of each feature,
-please see the API documentation.
+- [Getting started and loading guide](https://rubyworks.github.io/facets/learn.html)
+- [Generated API documentation on RubyDoc.info](https://www.rubydoc.info/gems/facets) (check the displayed version)
+- [Release history](HISTORY.md)
 
+The split between `lib/core`, `lib/standard` and `lib/rails` is visible in API source paths. This helps you tell whether a method is loaded by `require 'facets'` or needs an explicit require. The `lib/rails` area, new in 4.0.0, holds Rails-compatible helpers; see the release history for details.
 
 ## Contribute
 
-This project thrives on contribution!
-
-If you have any extension methods, classes or modules that you think have
-very general applicability and would like to see them included in
-this project, don't hesitate to submit. Also, if you have better versions
-of any thing already included or simply have a patch, they are more than
-welcome. We want Ruby Facets to be of the highest quality.
-
-
-## Development
-
-Facets uses the [Lemon](https://rubyworks.github.io/lemon) testing framework
-to handle unit testing, while [QED](https://rubyworks.github.io/qed) specifications
-provide tested documentation. Run the test suite with [Rake](https://ruby.github.io/rake/):
-
-    $ rake test
-
-Continuous integration runs on GitHub Actions (see `.github/workflows/ci.yml`).
-
-
-## Authors
-
-Much of this collection was written and/or inspired by a variety of great Ruby
-developers. Fortunately nearly all utilized works were copyrighted under the same
-open licenses, the Ruby License or the more liberal BSD and MIT licenses. In the
-one or two exceptions the copyright notice has been included with the source code.
-We have since received permission from the various authors to normalize the licensing
-to a single license. For this purpose we have chosen the BSD 2 Clause License.
-This is the license Ruby itself now uses, so it seemed the most appropriate choice.
-It is also almost identical to the MIT license. Any code file not specifically labeled
-otherwise shall fall under the this license (which is BSD 2-clause).
-
-In all cases, every effort has been made to give credit where credit is due.
-You will find these acknowledgments embedded in the source code. You can see
-them in "CREDIT:" and/or "@author" lines. 
-Also see the [Contributors page](https://github.com/rubyworks/facets/wiki/Contributors)
-on the Wiki for a list of all contributing Rubyists. If anyone is missing from
-the list, please let us know so we can correct. Thanks.
-
-This collection was put together by, and much of it written by [trans](https://github.com/trans).
-If need be, he can be reached via email at transfire at gmail.com.
-
-
-## License
-
-The collection PER COLLECTION is licensed as follows:
-
-    Ruby Facets
-    Copyright (c) 2005 Rubyworks
-
-    Distributed under the terms of the BSD-2 License (same as Ruby license).
-
-The BSD 2 Clause License is a simple open source license. The complete text of the
-license accompany this document (see the enclosed LICENSE file).
-
-Acknowledgments and Copyrights for particular snippets of borrowed code
-are given in their respective source. At this point, all licensing has been normalized
-for all included code. Original authors have given permission for inclusion of their
-code under such license, with appropriate credit citations.
+Issues and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for the library's method organization, demos, and test conventions. The test suite runs with:
 
+```sh
+bundle install
+bundle exec rake test
+```
 
-## "ALL YOUR BASE ARE BELONG TO RUBY!"
+[Source](https://github.com/rubyworks/facets) · [Issues](https://github.com/rubyworks/facets/issues) · [Website](https://rubyworks.github.io/facets/)
 
-Ruby Facets, Copyright (c) 2005 Rubyworks
+## License and credits
 
-Do you Ruby? (https://ruby-lang.org)
+Facets is distributed under the [BSD 2-Clause License](LICENSE.txt). Thomas Sawyer started the project, and many Rubyists have contributed code, ideas, tests, and documentation. Individual files record additional credits where applicable.
 
+*All your base are belong to Ruby.*

data/lib/core/facets/array/nonuniq.rb

@@ -11,14 +11,14 @@ class Array
   # CREDIT: Martin DeMello
 
   def nonuniq
-    warn "Array#nonuniq is deprecated. Use Array#duplicates instead.", uplevel: 1
+    warn "Array#nonuniq is deprecated. Use Array#duplicates instead. It will be removed after 2027-09-30.", uplevel: 1
     duplicates
   end
 
   # Same as `#nonuniq` but acts in place.
 
   def nonuniq!
-    warn "Array#nonuniq! is deprecated. Use Array#duplicates instead.", uplevel: 1
+    warn "Array#nonuniq! is deprecated. Use Array#duplicates instead. It will be removed after 2027-09-30.", uplevel: 1
     self.replace(duplicates)
   end
 

data/lib/core/facets/array/standard_deviation.rb

@@ -20,7 +20,7 @@ class Array
   alias sd stddev
 
   def standard_deviation
-    warn "Array#standard_deviation is deprecated. Use Array#stddev or Array#sd instead.", uplevel: 1
+    warn "Array#standard_deviation is deprecated. Use Array#stddev or Array#sd instead. It will be removed after 2027-09-30.", uplevel: 1
     stddev
   end
 end

data/lib/core/facets/array/uniq_by.rb

@@ -15,8 +15,12 @@ class Array
   #
   # Returns [Array] of unique elements.
   #
+  # @deprecated Use Array#uniq! with a block instead (Ruby 1.9.2+).
+  #   Scheduled for removal after 2027-09-30.
+  #
   def uniq_by!(&block) #:yield:
-    warn "Array#uniq_by! is deprecated. Use Array#uniq!(&block) instead.", uplevel: 1
+    warn "Array#uniq_by! is deprecated. Use Array#uniq!(&block) instead. " \
+         "It will be removed after 2027-09-30.", uplevel: 1
     uniq!(&block)
   end
 

data/lib/core/facets/array.rb

@@ -15,7 +15,6 @@ require_relative 'array/duplicates.rb'
 require_relative 'array/each_pair.rb'
 require_relative 'array/each_value.rb'
 require_relative 'array/entropy.rb'
-require_relative 'array/extract_options.rb'
 require_relative 'array/from.rb'
 require_relative 'array/indexable.rb'
 #require_relative 'array/intersection.rb'       # too new
@@ -47,3 +46,8 @@ require_relative 'array/thru.rb'
 require_relative 'array/traverse.rb'
 require_relative 'array/uniq_by.rb'
 
+
+# Rails-compatible methods from lib/rails; see facets/rails_bridge.
+require_relative 'rails_bridge.rb'
+Facets.rails_bridge(Array, 'facets/array/extract_options', :extract_options!)
+Facets.rails_bridge(Hash, 'facets/array/extract_options', :extractable_options?)

data/lib/core/facets/binding/self.rb

@@ -1,8 +1,9 @@
 class Binding
 
   # @deprecated Use Binding#receiver instead (built-in since Ruby 2.6).
+  #   Scheduled for removal after 2027-09-30.
   def self
-    warn "Binding#self is deprecated. Use Binding#receiver instead.", uplevel: 1
+    warn "Binding#self is deprecated. Use Binding#receiver instead. It will be removed after 2027-09-30.", uplevel: 1
     receiver
   end
 

data/lib/core/facets/comparable/clip.rb

@@ -1,8 +1,9 @@
 module Comparable
 
   # @deprecated Use Comparable#clamp instead (built-in since Ruby 2.4).
+  #   Scheduled for removal after 2027-09-30.
   def clip(lower, upper=nil)
-    warn "Comparable#clip is deprecated. Use Comparable#clamp instead.", uplevel: 1
+    warn "Comparable#clip is deprecated. Use Comparable#clamp instead. It will be removed after 2027-09-30.", uplevel: 1
     upper ? clamp(lower, upper) : clamp(lower..)
   end
 

data/lib/core/facets/dir/recurse.rb

@@ -2,16 +2,29 @@ require 'facets/dir/find'
 
 class Dir
 
+  # Recursively list every entry below +path+ (not +path+ itself),
+  # yielding each one to the block if given.
+  #
   # @deprecated Use Dir.find or Find.find instead.
+  #   Scheduled for removal after 2027-09-30.
   def self.recurse(path='.', &block)
-    warn "Dir.recurse is deprecated. Use Dir.find or Find.find instead.", uplevel: 1
-    Dir.find(path, &block)
+    warn "Dir.recurse is deprecated. Use Dir.find or Find.find instead. It will be removed after 2027-09-30.", uplevel: 1
+    recurse_entries(path, &block)
   end
 
   # @deprecated Use Dir.find or Find.find instead.
+  #   Scheduled for removal after 2027-09-30.
   def self.ls_r(path='.', &block)
-    warn "Dir.ls_r is deprecated. Use Dir.find or Find.find instead.", uplevel: 1
-    Dir.find(path, &block)
+    warn "Dir.ls_r is deprecated. Use Dir.find or Find.find instead. It will be removed after 2027-09-30.", uplevel: 1
+    recurse_entries(path, &block)
   end
 
+  # Dir.find yields +path+ first; the old #recurse did not include it.
+  def self.recurse_entries(path, &block)
+    list = Dir.find(path).drop(1)
+    list.each(&block) if block
+    list
+  end
+  private_class_method :recurse_entries
+
 end

data/lib/core/facets/enumerable/compact_map.rb

@@ -15,7 +15,7 @@ module Enumerable
   # does almost the same thing and enum.map{}.compact works too.
 
   def compact_map(&block)
-    warn "Enumerable#compact_map is deprecated. Use Enumerable#filter_map instead.", uplevel: 1
+    warn "Enumerable#compact_map is deprecated. Use Enumerable#filter_map instead. It will be removed after 2027-09-30.", uplevel: 1
     filter_map(&block)
   end
 

data/lib/core/facets/enumerable/defer.rb

@@ -27,7 +27,7 @@ module Enumerable
   # to output each result and discard it.
   #
   def defer(&blk)
-    warn "Enumerable#defer is deprecated. Use Enumerable#lazy instead.", uplevel: 1
+    warn "Enumerable#defer is deprecated. Use Enumerable#lazy instead. It will be removed after 2027-09-30.", uplevel: 1
     lazy
   end
 

data/lib/core/facets/enumerable/frequency.rb

@@ -16,7 +16,7 @@ module Enumerable
   #++
 
   def frequency
-    warn "Enumerable#frequency is deprecated. Use Enumerable#tally instead.", uplevel: 1
+    warn "Enumerable#frequency is deprecated. Use Enumerable#tally instead. It will be removed after 2027-09-30.", uplevel: 1
     tally
   end