facets 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 04425cff670267fec297484f50e19edbb8a22fc8
-  data.tar.gz: 19b9480ec202b072704267dc8760209cb6648338
+SHA256:
+  metadata.gz: cc5a3121c6c373b29fdc3e515820f8e547d8b8a2fbfd0dde05cec51640960fa5
+  data.tar.gz: 2440d6fd114506decc8993153077c4bf98c5e6f372cbc2922ee253103d9c1c0e
 SHA512:
-  metadata.gz: e36beb518158636837793bcab25e5c004cfd904d8e78f865099ff5b904ee562f04078d3d6ff5e10a7ab02b225de49d3ba51365fdc3538d50725855b0a5830baf
-  data.tar.gz: 13b826e5a84e8c7b91562c2df850eb16972a843dc6f6546f7f0aaf34a548d9db2c3d27935ea39a98573700d65cfe3bbdac183f8df2cdb1b66b68ee4faa9d8e54
+  metadata.gz: 67499b78df8f8b5b1a005d10b029d7f0278d7b6d9db5207c458df59433cf3d9362bcd8b4a60dbb5b31eb003b1b814fe1509800224746e5b71bbc5c1796349dbe
+  data.tar.gz: 8270894f6568a4d5b9b654a293e5c385230dc48032e0c711d24aa544ba0b48b379856874b4805cd476256e570272ebad0ebe76a71b4f519be8e6fa7470f81590

data/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# CONTRIBUTING TO FACETS
+
+## General Rules
+
+* Facets methods must have no external dependencies. (The only possible
+  exception to this is if the functor gets spun-off as a separate gem along
+  with related methods, but for now that hasn't happened.)
+
+* Each method must be in it's own file of the same name. If the method ends
+  with `=` or `?` just leave it off the file name.
+
+* On rare occasion two or more methods can be very tightly related. In these
+  cases the methods can all go in a single file under the name of the method
+  considered most significant. Usually files for the other methods should
+  still be created that simply require the main file.
+
+* Methods must be tested both via a Lemon unit test and as a QED demo.
+  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.
+
+* 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.
+
+* Standard libraries that are not extensions of existing standard libraries
+  do not have to be divvied up into individual method files. But note that
+  full classes and/or modules are less likely to make it into Facets, as
+  these sorts of additions to Facets are only for very basic sorts of things.
+  Otherwise they'd deserve their own gem.
+
+* When submitting new methods for consideration, it is best if each method
+  (or *tightly related* set of methods) is in it's own pull request. If you
+  have only one method to submit then a simple  commit will do the trick. If
+  you have more than one it best to use separate branches. Let me emphasizes
+  this point because it makes it *much more likely* that your pull request
+  will be merged. If you submit a bunch of methods in a single pull request,
+  it is very likely that it will not be merged even if methods you submitted
+  are accepted!!!
+
+* Don't be discouraged when you get feedback about a method that isn't
+  all sunshine and roses. Facets has been around long enough now that
+  it needs to maintain a certain degree of quality control, and that means
+  serious discernment about what goes into the library. That includes
+  having in depth discussions the merits of methods, even about the best
+  name for a method --even if the functionality has been accepted the name
+  may not.
+
+
+## Versioning
+
+Facets tries to follow a semantic versioning system, but with a slightly
+differt scheme than most projects. For Facets the version number represents:
+
+    gestault.major.minor
+
+Techinically there can be a fouth `build` number, but we never use it for
+releases.
+
+
+## Commit Tags
+
+When making a commit, it is helpful to add a *commit tag* to the end of the
+first line of commit message. Commit tags are single words wrapped in colons.
+
+* If the commit is only a documentation change, then and `:doc:`.
+* If it is only a change to tests then add `:test:`.
+* If the change only effects project build or config files then add `:admin:`.
+* If the change fixes a bug that was reported via the issue system be sure
+  to reference the issue number in the message using `#` and add a `:bug:` tag.
+* For actual code changes, if the change is *very minor* and not something
+  anyone would notice, you can use `:tweak:`, if you want. 
+* If the change would require a minor version change than use `:minor:`.
+* But if a change is a significant change to the API, and thus will require
+  a major version change, then end the message with `:major:`.
+
+These are all rules of thumb, and no one expects them to be applied perfectly.
+
+
+## Documentation
+
+Facets started when the only choice for API documentation was RDoc. So originally
+that's how methods were documented. Since then both YARD and Tomdoc have come
+along. And some of these documentation styles have crept into a number of
+methods. So right now, things are a bit messy. But going forward it looks like we
+are going to settle on Tomdoc as the official documentation style (but using
+the tomparse gem's extensions). Using Tomdoc will give us reasonable
+interoperability with both RDoc and YARD, both of which now have support for
+Tomdoc (albeit support is not 100% the same, but hopefully it's close enough).
+
+Officially we publish documentation via rubydoc.info, which is the YARD server,
+and via the Facets website in Shomen JSON format.
+
+When writing documentation for a method it is best to give a simple summary
+explanation, followed by some basic examples. Follow that up with deeper
+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
+
+

data/HISTORY.md

@@ -1,5 +1,180 @@
 # Facets Release History
 
+## 3.2.0 / 2026-04-01
+
+Modernization release targeting Ruby 3.1+. Cleans up long-standing
+compatibility issues and incorporates community contributions.
+
+Changes:
+
+* New Features
+
+  * Add `Crypt3` module — pure Ruby crypt(3) implementation (from rubyworks/crypt3).
+    Supports md5, sha1, sha256, sha384, sha512, rmd160.
+  * Add `Array#to_ranges` to convert arrays to ranges. (PR#265)
+  * Add `Array#remove` and `Array#remove!` for count-respecting subtraction. (PR#293)
+  * Add `Array#indexes` / `Array#index_all` to find all matching indexes. (PR#294)
+  * Add `String#dashcase` for kebab-case conversion. (PR#297)
+  * Add `Binding#caller_locations`.
+  * Add `Range.intersection` and `Range#intersection` for finding the shared
+    region of multiple ranges. Works with any comparable type.
+  * Add `Kernel#functor` — block-less method chaining via Functor, replaces `tap` override.
+  * Rename `Hash#to_proc` to `Hash#setter` (avoids clash with Ruby 2.3's `Hash#to_proc`
+    which does key lookup; Facets' version does attribute assignment).
+  * Consolidate `Array#arrange` and `Array#to_ranges`; `to_ranges` is now primary,
+    `arrange` and `rangify` are aliases. Now handles mixed ranges and values.
+  * Fix `Array#step` to start at index 0 (was n-1); add optional offset parameter.
+
+* Improved Features
+
+  * Adapt `Module#attr_setter` to frozen-string-literal. (PR#287)
+  * Update `Binding#__LINE__` and `__FILE__` to use `source_location`.
+  * Replace `URI.escape`/`URI.unescape` with `CGI.escape`/`CGI.unescape`.
+  * Rewrite `Kernel#callstack`, `#require_all`, `#load_all` to use `caller_locations`
+    instead of parsing caller strings with regex.
+  * Switch CI from Travis to GitHub Actions.
+  * Make `String#underscore` ActiveSupport-compatible (converts `::` to `/`).
+    Use `String#snakecase` for pure case conversion without namespace handling.
+  * Make `Kernel#try` ActiveSupport-compatible (supports block form and `try!`).
+    Facets' Tee/Functor form retained as extra feature.
+
+* Bug Fixes
+
+  * Fix `Math.gini_coefficient` referencing `self` instead of `array` parameter. (PR#302)
+  * Fix typo in `Array#after` doc. (PR#283)
+  * Fix typo in `String#to_b` doc. (PR#306)
+
+* Removals
+
+  * Remove `Array#**` (`op_pow`) alias for `product` (use `Array#product` directly).
+  * Deprecate `Array#occurrence` (use `Enumerable#tally` instead, adopted by Ruby in 2.7).
+  * Deprecate `Array#uniq_by!` (use `Array#uniq!(&block)` instead, adopted by Ruby in 1.9.2).
+  * Deprecate `Array#nonuniq` / `nonuniq!` (use `Array#duplicates` / `duplicates!` instead).
+  * Add `Array#duplicates!` (in-place version of `duplicates`).
+  * Remove `Kernel#tap` override. Use `Kernel#tee` for the block-less Functor form.
+  * Remove `Enumerable#filter` (conflicts with Ruby's built-in `filter` since 2.6).
+    Use `each_with_object` instead, with block arguments reversed:
+    `collection.each_with_object([]) { |el, out| out << el if cond }`.
+  * Remove Ruby 1.8 compatibility code from `enumerator.rb`.
+  * Remove `taint`/`tainted?` references (removed from Ruby in 3.2).
+  * Remove `Enumerable#sum` (adopted by Ruby in 2.4).
+    For non-numeric cases (e.g. `[[1],[2],[3]]`), use `reduce(:+)` instead.
+  * Remove `String#crypt` override (Ruby deprecated `crypt` in 3.2; use `bcrypt` gem instead).
+  * Remove `MatchData#match` (adopted by Ruby in 3.1).
+  * Remove `Range#overlap?` (adopted by Ruby in 3.3).
+  * Remove `Kernel#__DIR__` (adopted by Ruby as `__dir__` in 2.0).
+  * Remove `Kernel#instance_exec` (adopted by Ruby in 1.9).
+  * Remove `Kernel#singleton_class` (adopted by Ruby in 1.9).
+  * Remove `Kernel#p` override (Ruby's `p` returns its arguments since 1.9).
+  * Remove `Method#curry` (adopted by Ruby in 2.2).
+  * Remove `Array#to_h` (adopted by Ruby in 2.1).
+  * Remove `Array#intersection` (clashes with Ruby 2.7's `Array#intersection`).
+    Consider `Range.intersection` class method as future replacement.
+  * Remove `Hash#except` (adopted by Ruby in 3.0); `except!` and `remove!` retained.
+  * Remove `Hash#slice` (adopted by Ruby in 2.5); `slice!` retained.
+    Block form removed from both; use `slice(...).select { ... }` instead.
+  * Remove `Class#singleton_class?` (adopted by Ruby in 3.2).
+  * Remove `Class#subclasses` (adopted by Ruby in 3.1).
+  * Remove `Symbol#succ` (adopted by Ruby in 1.9).
+  * Remove `File.write` (adopted by Ruby in 1.9).
+  * Remove `Process.daemon` (adopted by Ruby in 1.9).
+  * Remove `Dir#each_child` (adopted by Ruby in 2.6).
+    Note: Ruby's version does not support the custom ignore argument.
+    Use `Dir.each_child('/path').reject { |f| ignore.include?(f) }` instead.
+  * Remove `Numeric#positive?` and `Numeric#negative?` (adopted by Ruby in 2.3).
+  * Remove `Object#itself` (adopted by Ruby in 2.6).
+  * Deprecate `Array#standard_deviation` (use `Array#stddev` or `Array#sd`).
+  * Deprecate `Struct#attributes` (use `Struct#to_h`, adopted by Ruby in 2.0).
+  * Deprecate `UnboundMethod#arguments` (use `UnboundMethod#parameters`, adopted by Ruby in 2.0).
+  * Remove `Object#dup!` and `Object#try_dup` (plain `dup` works on all objects since Ruby 2.4).
+  * Remove `Exception#set_message` (broken — did not actually change the message).
+  * Deprecate `Exception#error_print` (use `Exception#full_message`, adopted by Ruby in 2.5).
+  * Deprecate `Comparable#clip` (use `Comparable#clamp`, adopted by Ruby in 2.4).
+  * Redefine `Comparable#bound` as alias for `clamp`.
+  * Add `Dir.find` as convenience wrapper around Ruby's `Find.find`.
+  * Deprecate `Dir.recurse` / `Dir.ls_r` (use `Dir.find` or `Find.find` instead).
+  * Deprecate `Proc#compose` and `Proc#*` (use `Proc#<<` for right-to-left composition, Ruby 2.6+).
+  * Deprecate `Hash#update_keys` (use `Hash#transform_keys!` or `Hash#rekey!`).
+  * Deprecate `Hash#update_values` (use `Hash#transform_values!` or `Hash#revalue!`).
+  * Deprecate `Hash#fetch_nested` (use `Hash#dig`, adopted by Ruby in 2.3).
+  * Deprecate `Enumerable#compact_map` (use `Enumerable#filter_map`, adopted by Ruby in 2.7).
+  * Deprecate `Enumerable#defer` (use `Enumerable#lazy`, adopted by Ruby in 2.0).
+  * Deprecate `Enumerable#frequency` (use `Enumerable#tally`, adopted by Ruby in 2.7).
+  * Deprecate `Enumerable#hinge` (use `Enumerable#each_with_object`, note: block args reversed).
+  * Deprecate `Enumerable#map_with_index` (use `Enumerable#map.with_index`).
+  * Deprecate `Enumerable#mash` (use `Enumerable#graph` instead).
+  * Deprecate `Enumerable#uniq_by` (use `Enumerable#uniq(&block)`, Ruby 1.9.2+).
+  * Redefine `String#lchomp` / `#lchomp!` as aliases for `delete_prefix` / `delete_prefix!`.
+  * Rename `Time#trunc` to `Time#floor_to` (parallels `Time#round_to`; avoids confusion
+    with Ruby's `Time#floor` which takes sub-second digit precision). `trunc` deprecated.
+  * Fix `Binding#[]` and `#[]=` to use `local_variable_get`/`local_variable_set`
+    (broken since Ruby 1.9; now works again).
+  * Deprecate `Binding#self` (use `Binding#receiver`, adopted by Ruby in 2.6).
+  * Deprecate `Module#alias_method_chain` (use `Module#prepend`, Ruby 2.0+).
+  * Deprecate `Module#can` (use `Module#extend`).
+  * Deprecate `File.null` (use `File::NULL` constant, Ruby 1.9.3+).
+  * Deprecate `File.read_binary` (use `File.binread`, Ruby 1.9.3+).
+  * Deprecate `Kernel#eigenclass` (use `singleton_class` or `meta_class`; kept in tribute to _why).
+  * Deprecate `Kernel#extension`, `#instance_class`, `#qua_class`, `#object_class`
+    (use `singleton_class` or `meta_class`).
+  * Deprecate `Kernel#object_send` (use `public_send`), `#instance_send` (use `__send__`).
+  * Deprecate `Kernel#load_relative` (use `require_relative`).
+  * Deprecate `Kernel#returning` (use `Kernel#tap`).
+  * Deprecate `Kernel#memo` (use `Module#memoize`; global `$MEMO` is problematic).
+  * Update `Kernel#meta_class` to delegate to `singleton_class` internally.
+  * Fix dead requires for removed `kernel/singleton_class` in Proc and Kernel.
+  * Remove misplaced `applique/file_helpers` from core (test infrastructure).
+  * Remove OpenStruct extensions now built into Ruby (`to_h`, `each`, `[]`, `[]=`).
+  * Fix OpenStruct#initialize to not use removed `new_ostruct_member`.
+  * Add OpenStruct#merge (non-destructive version).
+  * Remove deprecated OpenStruct methods (`instance_delegate`, `ostruct_update`, etc.).
+  * Deprecate `cloneable.rb` (use `deep_dup`/`deep_clone` instead).
+  * Deprecate `continuation.rb` (callcc is obsolete; use Fiber).
+  * Deprecate `getoptlong.rb` (bundled gem heading for removal; use OptionParser).
+  * Deprecate `load_monitor.rb` (monkey-patches require/load globally).
+  * Clean up `random.rb`: remove Array#shuffle/shuffle! (Ruby built-in),
+    add Array#sample! (destructive sample), deprecate at_rand/pick (use sample).
+  * Fix Pathname#glob to wrap Ruby's built-in, adding symbol flag support.
+  * Remove Pathname#empty? (built into Ruby).
+  * Deprecate Pathname.null (use Pathname.new(File::NULL)).
+  * Fix `Math.kldivergence` (was broken — referenced `self` instead of array parameter).
+  * Drop unused `test_files` directive from gemspec. (PR#301)
+
+
+## 3.1.0 / 2016-05-10
+
+More or less a minor release, but there are some backward incompatabilites
+such as `Hash#except!` which no longer returns the rejected entries (use
+`Hash#remove!` for old behavior).
+
+Special thanks to Scott Parrish for all his help getting Facets in tip-top
+shape.
+
+Changes:
+
+* New Features
+
+  * Add `Hash#remove!` for old `except!` behavior.
+  * Add `Array#standard_deviation`.
+  * Add `Array#variance`.
+  * Add `Array#average`.
+  * Add `Numeric#delimit`.
+
+* Improved Features
+
+  * Change `Hash#except!` to not return rejected entries.
+  * Improve definition of Character Set in `String.random`.
+  * Add one to denominator of `String#similarity` score.
+  * Enhanced download methods.
+  * Improvements on compatability with ActiveSupport.
+  * Enumerable#from and #thru return empty set when index is out of bounds.
+
+* Bug Fixes
+
+  * Fix `Enumerable#key_by`.
+  * Fix `Enumerable#sum` to take initial value.
+
+
 ## 3.0.0 / 2014-11-11
 
 This major release has been a long time in coming --too long in fact. As with
@@ -21,8 +196,10 @@ Changes:
   * Add Dir.lookup method
   * Add Enumerator::Lazy#squeeze
   * Add Hash#fetch_nested
+  * Add Hash#deep_rekey and Hash#deep_rekey!
   * Add Kernel#instance_extract
   * Add Math#EC for Euler's constant
+  * Add Module#alias_class_method
   * Add Pathname#chdir
   * Add Pathname#readline
   * Add Proc.wrap (may become `Kernel#Proc()`)
@@ -34,6 +211,7 @@ Changes:
 * Improved Features
 
   * Enumerable#sum argument is initial value.
+  * Generalize Enumerable#sum to duck-type on `#+`.
   * Hash#collate can take multiple arguments.
   * Hash#collate no longer flattens automatically.
   * Time#past? and #future? use Time.current.
@@ -43,6 +221,7 @@ Changes:
 
   * Rename Object#replace to Object#instance_replace.
   * Rename Range#to_r to Range#to_rng, since #to_r is now for Rational.  
+  * Rename Kernel#eigen to #meta.
 
 * Bug Fixes