facets 4.0.1 → 4.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +10 -0
- data/HISTORY.md +222 -0
- data/README.md +2 -2
- data/lib/core/facets/array/commonality.rb +1 -1
- data/lib/core/facets/array/delete_first.rb +6 -5
- data/lib/core/facets/array/divide.rb +1 -1
- data/lib/core/facets/array/from_base.rb +68 -0
- data/lib/core/facets/array/indexes.rb +1 -1
- data/lib/core/facets/array/occur.rb +1 -1
- data/lib/core/facets/array/split.rb +16 -9
- data/lib/core/facets/array/split_at.rb +3 -3
- data/lib/core/facets/array.rb +1 -0
- data/lib/core/facets/boolean.rb +2 -2
- data/lib/core/facets/class/descendants.rb +26 -12
- data/lib/core/facets/dir/ascend.rb +1 -2
- data/lib/core/facets/dir/multiglob.rb +4 -9
- data/lib/core/facets/enumerable/apply.rb +3 -3
- data/lib/core/facets/enumerable/cluster.rb +2 -2
- data/lib/core/facets/enumerable/defer.rb +4 -1
- data/lib/core/facets/enumerable/hashify.rb +5 -5
- data/lib/core/facets/enumerable/with_position.rb +2 -2
- data/lib/core/facets/enumerator/fx.rb +11 -11
- data/lib/core/facets/essentials.rb +2 -2
- data/lib/core/facets/file/atomic_open.rb +1 -1
- data/lib/core/facets/file/rewrite.rb +4 -4
- data/lib/core/facets/hash/count.rb +19 -8
- data/lib/core/facets/hash/deep_merge.rb +25 -20
- data/lib/core/facets/hash/deep_rekey.rb +1 -1
- data/lib/core/facets/hash/except.rb +1 -1
- data/lib/core/facets/hash/op_mul.rb +2 -0
- data/lib/core/facets/hash/op_push.rb +7 -7
- data/lib/core/facets/hash/rekey.rb +7 -7
- data/lib/core/facets/hash/weave.rb +1 -1
- data/lib/core/facets/integer/ordinal.rb +18 -13
- data/lib/core/facets/integer/to_base.rb +115 -0
- data/lib/core/facets/integer.rb +1 -0
- data/lib/core/facets/kernel/ask.rb +3 -3
- data/lib/core/facets/kernel/blank.rb +13 -8
- data/lib/core/facets/kernel/callstack.rb +2 -2
- data/lib/core/facets/kernel/d.rb +3 -3
- data/lib/core/facets/kernel/demo.rb +2 -2
- data/lib/core/facets/kernel/extend.rb +20 -4
- data/lib/core/facets/kernel/functor.rb +1 -1
- data/lib/core/facets/kernel/instance_assign.rb +2 -3
- data/lib/core/facets/kernel/instance_replace.rb +2 -2
- data/lib/core/facets/kernel/maybe.rb +1 -1
- data/lib/core/facets/kernel/meta_class.rb +2 -1
- data/lib/core/facets/kernel/meta_def.rb +3 -3
- data/lib/core/facets/kernel/object_hexid.rb +2 -7
- data/lib/core/facets/kernel/try.rb +3 -1
- data/lib/core/facets/module/attr_class_accessor.rb +2 -2
- data/lib/core/facets/module/class_accessor.rb +2 -2
- data/lib/core/facets/module/instance_method.rb +2 -2
- data/lib/core/facets/module/is.rb +1 -1
- data/lib/core/facets/numeric/delimit.rb +1 -1
- data/lib/core/facets/proc/wrap.rb +1 -1
- data/lib/core/facets/range/op_sub.rb +2 -2
- data/lib/core/facets/range/overlap.rb +32 -1
- data/lib/core/facets/range/within.rb +1 -1
- data/lib/core/facets/regexp/op_or.rb +1 -1
- data/lib/core/facets/string/align.rb +4 -4
- data/lib/core/facets/string/ascii_only.rb +2 -2
- data/lib/core/facets/string/dashcase.rb +1 -1
- data/lib/core/facets/string/file.rb +1 -1
- data/lib/core/facets/string/from_base.rb +85 -0
- data/lib/core/facets/string/indent.rb +35 -23
- data/lib/core/facets/string/margin.rb +18 -4
- data/lib/core/facets/string/mask.rb +264 -0
- data/lib/core/facets/string/natcmp.rb +1 -1
- data/lib/core/facets/string/random.rb +1 -1
- data/lib/core/facets/string/remove.rb +13 -8
- data/lib/core/facets/string/rotate.rb +1 -1
- data/lib/core/facets/string/similarity.rb +2 -2
- data/lib/core/facets/string/squish.rb +5 -3
- data/lib/core/facets/string/trim.rb +1 -1
- data/lib/core/facets/string/unfold.rb +1 -1
- data/lib/core/facets/string/word_wrap.rb +1 -1
- data/lib/core/facets/string/words.rb +2 -2
- data/lib/core/facets/string.rb +3 -0
- data/lib/core/facets/symbol/call.rb +0 -9
- data/lib/core/facets/time/change.rb +51 -29
- data/lib/core/facets/time/future.rb +6 -2
- data/lib/core/facets/time/stamp.rb +1 -1
- data/lib/core/facets/time/to_time.rb +3 -7
- data/lib/core/facets/version.rb +1 -1
- data/lib/rails/facets/file/atomic_write.rb +1 -1
- data/lib/standard/facets/crypt3.rb +4 -2
- data/lib/standard/facets/digest/salted_digest.rb +6 -2
- data/lib/standard/facets/fileutils/ln_r.rb +7 -56
- data/lib/standard/facets/mirror.rb +276 -0
- data/lib/standard/facets/ostruct/initialize.rb +7 -6
- data/lib/standard/facets/ostruct.rb +3 -3
- data/lib/standard/facets/paramix.rb +150 -0
- data/lib/standard/facets/pathname/glob.rb +11 -7
- data/lib/standard/facets/shellwords.rb +53 -5
- data/lib/standard/facets/zlib.rb +5 -9
- metadata +7 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a5a0fe1f15e51a1eb910a6c2725ec6a40a03e34250401a1211bb7b5f2c0fb5e5
|
|
4
|
+
data.tar.gz: 45b61435e8159919b01bf88bc37a4ebe8330c1743b7a8d544763299f798957dc
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5bef39a334f530b1fea26901da7975267cb7e764c2763798130d09cb457187d2c6e935261a83527673e37d510bc66869a264dc4b459e81c9d0e6519d26715ac0
|
|
7
|
+
data.tar.gz: eb3591e5256eea3e91c82a8a074830cdc7c4b415fdd13ac40da475192a8e76a93d9157c0445e0abd1595b88f26abff9a8aee541e77cf6155cc88ca0123f966d5
|
data/CONTRIBUTING.md
CHANGED
|
@@ -27,6 +27,16 @@
|
|
|
27
27
|
require line, and comment out their line in the aggregator file with
|
|
28
28
|
`# uncommon`.
|
|
29
29
|
|
|
30
|
+
* Facets must not change what Ruby's own methods do, in the core or the
|
|
31
|
+
standard library. A Facets method with the same name as one of Ruby's is
|
|
32
|
+
allowed only if it is compatible, giving Ruby's result for everything
|
|
33
|
+
Ruby's version accepts (or differing only where Ruby's gives no useful
|
|
34
|
+
answer, such as raising or returning nil), and it adds something useful.
|
|
35
|
+
Otherwise Facets gets out of Ruby's way, and the Facets version is either
|
|
36
|
+
dropped or kept under a new name. Never redefine a method just to copy
|
|
37
|
+
Ruby's. If Ruby later adds a method Facets already has, the same rule
|
|
38
|
+
applies.
|
|
39
|
+
|
|
30
40
|
* Standard libraries that are not extensions of existing standard libraries
|
|
31
41
|
do not have to be divvied up into individual method files. But note that
|
|
32
42
|
full classes and/or modules are less likely to make it into Facets, as
|
data/HISTORY.md
CHANGED
|
@@ -1,5 +1,227 @@
|
|
|
1
1
|
# Facets Release History
|
|
2
2
|
|
|
3
|
+
## 4.2.0 / 2026-11-17
|
|
4
|
+
|
|
5
|
+
This release brings back four libraries that began in Facets and were
|
|
6
|
+
later kept as gems of their own: number bases (Radix), object
|
|
7
|
+
introspection (Instance, now `Mirror`), parametric mixins (Paramix) and
|
|
8
|
+
string masks (Strmask). The number bases load with `require 'facets'`;
|
|
9
|
+
the other three are loaded on request.
|
|
10
|
+
|
|
11
|
+
Changes:
|
|
12
|
+
|
|
13
|
+
* Additions
|
|
14
|
+
|
|
15
|
+
* `Integer#to_base` and `String#from_base` convert to and from any base
|
|
16
|
+
from 2 to 62, or with your own digits: `255.to_base(62)` is `"47"`,
|
|
17
|
+
and `"47".from_base(62)` is 255. Ruby's `to_s` and `to_i` stop at
|
|
18
|
+
base 36; up to there, `to_base` gives the same result as `to_s`, and
|
|
19
|
+
`from_base` the same as `to_i` for valid input. Unlike `to_i`,
|
|
20
|
+
`from_base` raises `ArgumentError` for a character that isn't a digit.
|
|
21
|
+
In base 256 the digits are bytes: `256.to_base(256)` is `"\x01\x00"`,
|
|
22
|
+
a binary string, and `from_base(256)` reads a string's bytes.
|
|
23
|
+
* Given an array, `to_base` gives an array, with no limit on the base.
|
|
24
|
+
An array holding a number is the base, and the result is the digit
|
|
25
|
+
values: `1000.to_base([100])` is `[10, 0]`. Any other array is the
|
|
26
|
+
digits, which can be any objects: `5.to_base([:zero, :one])` is
|
|
27
|
+
`[:one, :zero, :one]`.
|
|
28
|
+
* `Array#from_base` turns such an array back into a number, given the
|
|
29
|
+
same base: `[10, 0].from_base([100])` is 1000, and
|
|
30
|
+
`[1, 0].from_base(256)` is 256. All three load with
|
|
31
|
+
`require 'facets'`, and are based on the Radix gem.
|
|
32
|
+
* `String#margin` takes a `:flush` option, which gives every line the
|
|
33
|
+
same margin and doesn't keep their relative indentation:
|
|
34
|
+
`"abc\n xyz".margin(2, flush: true)` is `" abc\n xyz"`. This is
|
|
35
|
+
what `String#tab`, removed in 3.1.0, used to do; `String#tabto` is
|
|
36
|
+
`margin(n, lead: true)`.
|
|
37
|
+
* `Mirror`, loaded with `require 'facets/mirror'`, looks at an object
|
|
38
|
+
from the outside: `obj.mirror.to_h` gives its instance variables as a
|
|
39
|
+
hash, and the mirror also gets and sets them, and gives the object's
|
|
40
|
+
class and methods. It calls Ruby's own reflection methods, so it gives
|
|
41
|
+
the true answers even for an object that redefines `class` or
|
|
42
|
+
`instance_variables`, or a `BasicObject` that has neither. The class
|
|
43
|
+
is `Kernel::Mirror`, so an application's own `Mirror` class takes
|
|
44
|
+
precedence instead of clashing. Based on the Instance gem.
|
|
45
|
+
* `Paramix`, loaded with `require 'facets/paramix'`, makes a module
|
|
46
|
+
take parameters where it is included or extended:
|
|
47
|
+
`include Greeter[:name => 'x']`. A module that includes `Paramix`
|
|
48
|
+
has a `parameterized` block, which is given the parameters and
|
|
49
|
+
defines the methods that depend on them. Paramix was part of Facets
|
|
50
|
+
until 2.7.0, then the Paramix gem, where the module to include was
|
|
51
|
+
`Paramix::Parametric`; that name still works.
|
|
52
|
+
* `String::Mask` and `String#mask`, loaded with
|
|
53
|
+
`require 'facets/string/mask'`, treat a string as a mask with empty
|
|
54
|
+
slots and combine masks character by character:
|
|
55
|
+
`("abc..123".mask('.') + "ab..789.").to_s` is `"abc.7893"`, and `-`,
|
|
56
|
+
`*`, `&` and `^` work likewise. This was Facets' `string/mask` until
|
|
57
|
+
2.7.0, then the Strmask gem. Compared with the gem: masks of
|
|
58
|
+
different lengths can be combined, a mask can be made without an
|
|
59
|
+
empty-slot character, equal masks are the same hash key, `apply`
|
|
60
|
+
works, only methods a string has are passed on to it, and a mask is
|
|
61
|
+
equal only to another mask (compare `mask.to_s` with a string).
|
|
62
|
+
|
|
63
|
+
* Bug fixes
|
|
64
|
+
|
|
65
|
+
* `String#dashcase` now squeezes runs of dashes, as its docs say:
|
|
66
|
+
`"Dash - Case".dashcase` is `"dash-case"`, not `"dash-----case"`.
|
|
67
|
+
* `Dir.multiglob` ignored `:recurse => true`. It now gives the same
|
|
68
|
+
result as `Dir.multiglob_r`, and no longer changes the options hash
|
|
69
|
+
it is given.
|
|
70
|
+
* `Array#delete_first` now returns the block's result when the item
|
|
71
|
+
isn't found, as its docs say and as `Array#delete` does.
|
|
72
|
+
* `Crypt3.generate_salt`, and so the salt `Crypt3.crypt` makes when
|
|
73
|
+
given none, now comes from `SecureRandom`. It came from `rand`, which
|
|
74
|
+
isn't a cryptographic source.
|
|
75
|
+
|
|
76
|
+
* Documentation
|
|
77
|
+
|
|
78
|
+
* The examples in the doc comments run again, with `rake qed:code`,
|
|
79
|
+
and CI now runs them. Many had gone stale: wrong results, renamed
|
|
80
|
+
methods, and output that depended on the local time zone. Those that
|
|
81
|
+
can't run, such as interactive prompts and random output, are now
|
|
82
|
+
marked as sample text. Six `@uncommon` tags named files that don't
|
|
83
|
+
exist; a test now checks those paths.
|
|
84
|
+
|
|
85
|
+
## 4.1.0 / 2026-11-08
|
|
86
|
+
|
|
87
|
+
Facets and ActiveSupport define many of the same methods, and whichever
|
|
88
|
+
loads last replaces the other's. This release makes a set of those methods
|
|
89
|
+
behave the same in both libraries, so it no longer matters which one wins.
|
|
90
|
+
Facets now matches ActiveSupport 8.1 in these cases, which fixes bugs in
|
|
91
|
+
Rails apps that load Facets, and adds the extra options ActiveSupport's
|
|
92
|
+
versions take.
|
|
93
|
+
|
|
94
|
+
It also stops Facets from changing what Ruby's own methods do. Under a new
|
|
95
|
+
rule, now in CONTRIBUTING.md, a Facets method may share a name with one of
|
|
96
|
+
Ruby's only if it gives Ruby's results and adds something useful. Otherwise
|
|
97
|
+
Facets gets out of Ruby's way.
|
|
98
|
+
|
|
99
|
+
Changes:
|
|
100
|
+
|
|
101
|
+
* Bug Fixes
|
|
102
|
+
|
|
103
|
+
* `Hash#count`, loaded by `require 'facets'`, gives Ruby's own answers
|
|
104
|
+
again. Facets' version counted values rather than key-value pairs, which
|
|
105
|
+
changed Ruby's answer for every library in the program:
|
|
106
|
+
`{a: 1}.count([:a, 1])` returned 0. To count values, use
|
|
107
|
+
`hash.values.count(value)`. Until 2027-09-30, `Hash#count` warns when
|
|
108
|
+
given an argument that can't be a key-value pair, which is how Facets'
|
|
109
|
+
version was called.
|
|
110
|
+
* `Array#shelljoin` from `facets/shellwords` is Ruby's own again. Facets'
|
|
111
|
+
version flattened nested arrays and turned hashes into options, so a
|
|
112
|
+
value meant as one argument could become several. A web request's
|
|
113
|
+
parameter can be an array (`?term[]=&term[]=/home`), and with it
|
|
114
|
+
`['grep', '-r', '--', term, 'public/'].shelljoin` gave
|
|
115
|
+
`grep -r -- '' /home public/`, which prints every file under `/home`.
|
|
116
|
+
Ruby's escapes each element as one argument. To turn hashes into
|
|
117
|
+
options, use `array.shellwords.shelljoin`. Until 2027-09-30,
|
|
118
|
+
`Array#shelljoin` warns when the array has a hash or an array in it.
|
|
119
|
+
* `Hash#shellwords`, and so `Hash#shelljoin` and `Array#shellwords`, no
|
|
120
|
+
longer put quote characters around values. Once the words were escaped
|
|
121
|
+
with `shelljoin`, the quotes became part of the value:
|
|
122
|
+
`{name: 'jim'}.shelljoin` passed `"jim"`, quotes included. Each flag and
|
|
123
|
+
its value is now one plain word, `--name=jim`.
|
|
124
|
+
* `require 'facets'` loads `String#trim`. When `String#margin` was renamed
|
|
125
|
+
to `#trim` in 3.0, the new file was never added to the core aggregator,
|
|
126
|
+
so `trim` worked only with its own require.
|
|
127
|
+
* `Enumerable#defer` with a block works again. Since 3.2 deprecated it,
|
|
128
|
+
`defer` ignored its block, so
|
|
129
|
+
`(1..10).defer { |out, i| out << i if i.even? }.first(5)` returned
|
|
130
|
+
`[1, 2, 3, 4, 5]` instead of `[2, 4, 6, 8, 10]`. It is still
|
|
131
|
+
deprecated; the block form is `Enumerator::Lazy.new(enum) { ... }`.
|
|
132
|
+
* `Range#overlap?` on Ruby 3.1 and 3.2, where Ruby has no version of its
|
|
133
|
+
own, gives the same answers as Ruby's. Facets' version said an empty
|
|
134
|
+
range like `3...3` overlapped any range containing 3, raised RangeError
|
|
135
|
+
for `(3..).overlap?(..5)`, and raised NoMethodError rather than
|
|
136
|
+
TypeError for a non-Range argument. It now follows Ruby's algorithm.
|
|
137
|
+
* `Time.current` uses ActiveSupport's `Time.zone` when it is set. Before,
|
|
138
|
+
when Facets loaded after ActiveSupport, `Time.current` ignored the Rails
|
|
139
|
+
app's time zone and returned the system's local time.
|
|
140
|
+
* `Time#change` keeps the time's UTC offset or time zone. Before, a time
|
|
141
|
+
such as `15:30 +09:00` changed to the system's local time zone. It also
|
|
142
|
+
keeps fractions of a microsecond.
|
|
143
|
+
* Facets' deprecated `Time#to_time`, used only when `date` isn't loaded,
|
|
144
|
+
returns `self`, as Ruby's own does. Before, it converted to local time.
|
|
145
|
+
* `String#blank?` and `String#squish` treat Unicode whitespace, such as a
|
|
146
|
+
non-breaking space, as whitespace. `String#blank?` also works for strings
|
|
147
|
+
in encodings such as UTF-16.
|
|
148
|
+
* `Class#descendants` no longer raises `ArgumentError` when ActiveSupport
|
|
149
|
+
is loaded. Calling it with a number of generations still does, because
|
|
150
|
+
ActiveSupport wraps the method in one that takes no argument.
|
|
151
|
+
* `Integer#ordinal` and `#ordinalize` give `"-1st"` for -1, not `"-1th"`.
|
|
152
|
+
* `String#unindent` with no argument removes only the least indented
|
|
153
|
+
line's indentation from each line. Before, it removed more from the more
|
|
154
|
+
indented lines, so its own example, `"ohaie\n wurld"`, came out as
|
|
155
|
+
`"ohaie\nwurld"`. It also raised `NoMethodError` for an empty string.
|
|
156
|
+
* `String#indent` with a negative number and an indent string of more than
|
|
157
|
+
one character removes only whole copies of that string.
|
|
158
|
+
* `require 'facets/fileutils/ln_r'` replaced Ruby's `FileUtils.link_entry`
|
|
159
|
+
and an internal method it uses with old copies, so Ruby's own
|
|
160
|
+
`FileUtils.cp_lr` raised `NameError`. `FileUtils.ln_r` now uses Ruby's
|
|
161
|
+
`link_entry`, and the file requires `fileutils` itself.
|
|
162
|
+
* `Pathname#glob` from `facets/pathname/glob` ignored a block; it now gives
|
|
163
|
+
the block each match, as Ruby's does. With symbol flags, such as
|
|
164
|
+
`:dotmatch`, it now uses Ruby's glob too, so it works in a directory
|
|
165
|
+
whose name has glob characters such as `[`, and returns paths in the
|
|
166
|
+
same form as it does without them. The file requires `pathname` itself.
|
|
167
|
+
* `Kernel#extend` with no arguments and no block raises `ArgumentError`,
|
|
168
|
+
as Ruby's does; before, it returned the object. `ruby -w` no longer warns
|
|
169
|
+
that `extend` was redefined.
|
|
170
|
+
* `require 'facets/digest'` raised `LoadError`, because it required a file
|
|
171
|
+
that had moved. `#salted_digest`'s automatic salt now comes from
|
|
172
|
+
`SecureRandom` instead of `rand`.
|
|
173
|
+
* `facets/zlib` no longer defines its own copies of Ruby's `Zlib.inflate`
|
|
174
|
+
and `Zlib.deflate`. It now requires `zlib` and `stringio` itself;
|
|
175
|
+
before, `Zlib.compress` raised `NameError` unless they were already
|
|
176
|
+
loaded.
|
|
177
|
+
* `OpenStruct#initialize` from `facets/ostruct` calls Ruby's own
|
|
178
|
+
`initialize` for the hash, instead of a copy of it, and `ruby -w` no
|
|
179
|
+
longer warns that it was redefined.
|
|
180
|
+
|
|
181
|
+
* Additions
|
|
182
|
+
|
|
183
|
+
* `Time#change` takes `nsec:` and `offset:`.
|
|
184
|
+
* `String#remove` and `#remove!` take several patterns.
|
|
185
|
+
* `Hash#deep_merge` and `#deep_merge!` take a block, as `Hash#merge` does,
|
|
186
|
+
to decide the value of a key both hashes have.
|
|
187
|
+
* `Array#split` takes a block instead of a pattern, and splits on `nil`
|
|
188
|
+
when given neither.
|
|
189
|
+
* `String#indent` and `#indent!` take a third argument; when true, empty
|
|
190
|
+
lines are indented too.
|
|
191
|
+
|
|
192
|
+
* Deprecations
|
|
193
|
+
|
|
194
|
+
* `Kernel#extend` with a block, which Facets has added since 2.8.0, now
|
|
195
|
+
warns, and will be removed after 2027-09-30. It's the only reason Facets
|
|
196
|
+
overrides Ruby's `extend`, which every `extend` call in a program then
|
|
197
|
+
goes through. Use `obj.extend(Module.new { ... })` instead. Without
|
|
198
|
+
Facets, Ruby raises if given only a block, and ignores a block given
|
|
199
|
+
with modules.
|
|
200
|
+
|
|
201
|
+
* Changes that can affect existing code
|
|
202
|
+
|
|
203
|
+
* `Hash#count(value)` and `Array#shelljoin` no longer do what Facets'
|
|
204
|
+
versions did; see Bug Fixes. Both warn until 2027-09-30 when called
|
|
205
|
+
the old way.
|
|
206
|
+
* `Hash#shellwords` gives `--name=jim` rather than `--name="jim"`. Code
|
|
207
|
+
that joined the words with spaces into a shell command should use
|
|
208
|
+
`shelljoin` instead.
|
|
209
|
+
* `Array#split` keeps an empty piece where a match is at either end:
|
|
210
|
+
`[2, 1, 2].split(2)` is `[[], [1], []]`, and `[].split(2)` is `[[]]`.
|
|
211
|
+
Before, empty pieces at the end were dropped.
|
|
212
|
+
* `String#indent` leaves empty lines unchanged unless asked. Without an
|
|
213
|
+
indent string, it indents with the string's own indentation character,
|
|
214
|
+
so a tab-indented string gets more tabs.
|
|
215
|
+
* `String#remove!` returns the string even when nothing was removed.
|
|
216
|
+
Before, it returned `nil` then.
|
|
217
|
+
* `Hash#deep_merge!` replaces a sub-hash with a merged copy instead of
|
|
218
|
+
changing it, so other references to the sub-hash no longer see the
|
|
219
|
+
change.
|
|
220
|
+
* `Class#descendants` lists all subclasses before their own descendants.
|
|
221
|
+
On Ruby 4.1, which adds its own `Module#descendants`, a call without a
|
|
222
|
+
number of generations is passed to Ruby's, so it gives Ruby's list, in
|
|
223
|
+
Ruby's order. Only `descendants(n)` is still Facets' own there.
|
|
224
|
+
|
|
3
225
|
## 4.0.1 / 2026-11-02
|
|
4
226
|
|
|
5
227
|
A patch release with a security fix: `require 'facets/shellwords'` replaced
|
data/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
**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.
|
|
7
7
|
|
|
8
|
-
Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **4.0
|
|
8
|
+
Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **4.2.0**, 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.
|
|
9
9
|
|
|
10
10
|
## Install
|
|
11
11
|
|
|
@@ -62,7 +62,7 @@ require 'facets'
|
|
|
62
62
|
require 'facets/ostruct'
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
This loads `ostruct` and Facets' OpenStruct extensions. On Ruby
|
|
65
|
+
This loads `ostruct` and Facets' OpenStruct extensions. On Ruby 4.0+, list the `ostruct` gem in your Gemfile, because it is now a bundled gem rather than a default gem.
|
|
66
66
|
|
|
67
67
|
## Documentation
|
|
68
68
|
|
|
@@ -5,7 +5,7 @@ class Array
|
|
|
5
5
|
# common if they return the same value for Object#hash and if obj1 == obj2.
|
|
6
6
|
#
|
|
7
7
|
# This can be useful, for instance, in determining all persons that share
|
|
8
|
-
# their last name with another person
|
|
8
|
+
# their last name with another person:
|
|
9
9
|
#
|
|
10
10
|
# persons.commonality { |person| person.last_name }
|
|
11
11
|
#
|
|
@@ -7,15 +7,16 @@ class Array
|
|
|
7
7
|
# the item is not found.
|
|
8
8
|
#
|
|
9
9
|
# a = [ "a", "b", "b", "b", "c" ]
|
|
10
|
-
# a.delete_first("b")
|
|
11
|
-
# a
|
|
12
|
-
# a.
|
|
13
|
-
# a.
|
|
10
|
+
# a.delete_first("b") #=> "b"
|
|
11
|
+
# a #=> ["a", "b", "b", "c"]
|
|
12
|
+
# a.delete_first("z") #=> nil
|
|
13
|
+
# a.delete_first("z") { "not found" } #=> "not found"
|
|
14
14
|
def delete_first(el)
|
|
15
15
|
i = index(el)
|
|
16
16
|
if i
|
|
17
17
|
delete_at(i)
|
|
18
|
+
elsif block_given?
|
|
19
|
+
yield(el)
|
|
18
20
|
end
|
|
19
21
|
end
|
|
20
22
|
end
|
|
21
|
-
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
class Array
|
|
2
|
+
|
|
3
|
+
# Reads the array as the digit values of a number in the given base,
|
|
4
|
+
# most significant first, and returns the number. Any base from 2 up
|
|
5
|
+
# works.
|
|
6
|
+
#
|
|
7
|
+
# [1, 0].from_base(256) #=> 256
|
|
8
|
+
# [100, 10].from_base(256) #=> 25610
|
|
9
|
+
# [2, 5, 5].from_base(10) #=> 255
|
|
10
|
+
#
|
|
11
|
+
# This reverses Ruby's `Integer#digits`, which gives the digit values
|
|
12
|
+
# least significant first:
|
|
13
|
+
#
|
|
14
|
+
# 255.digits(16) #=> [15, 15]
|
|
15
|
+
# 255.digits(16).reverse.from_base(16) #=> 255
|
|
16
|
+
#
|
|
17
|
+
# The base can also be given as Integer#to_base takes it for an
|
|
18
|
+
# array: as an array holding the base, or as an array of the digits,
|
|
19
|
+
# starting with the digit for zero. Whatever array `to_base` was
|
|
20
|
+
# given reads its result back.
|
|
21
|
+
#
|
|
22
|
+
# [10, 0].from_base([100]) #=> 1000
|
|
23
|
+
# %w[L O L].from_base(%w[O L T W F S]) #=> 37
|
|
24
|
+
# [:one, :zero, :one].from_base([:zero, :one]) #=> 5
|
|
25
|
+
#
|
|
26
|
+
# Raises ArgumentError for an empty array, and for an element that
|
|
27
|
+
# isn't a digit of the base: an Integer from 0 to one less than the
|
|
28
|
+
# base, or one of the digits given.
|
|
29
|
+
#
|
|
30
|
+
# String#from_base reads a number written as a string.
|
|
31
|
+
#
|
|
32
|
+
# Since: 4.2.0
|
|
33
|
+
|
|
34
|
+
def from_base(base)
|
|
35
|
+
values = nil
|
|
36
|
+
case base
|
|
37
|
+
when ::Integer
|
|
38
|
+
# digit values
|
|
39
|
+
when ::Array
|
|
40
|
+
if base.size == 1 && base.first.is_a?(::Integer)
|
|
41
|
+
base = base.first
|
|
42
|
+
else
|
|
43
|
+
if base.size < 2
|
|
44
|
+
raise ArgumentError, "a base needs at least two digits"
|
|
45
|
+
end
|
|
46
|
+
if base.uniq.size < base.size
|
|
47
|
+
raise ArgumentError, "digits must not repeat"
|
|
48
|
+
end
|
|
49
|
+
values = {}
|
|
50
|
+
base.each_with_index { |d, i| values[d] = i }
|
|
51
|
+
base = base.size
|
|
52
|
+
end
|
|
53
|
+
else
|
|
54
|
+
raise TypeError, "base must be an Integer or Array, not #{base.class}"
|
|
55
|
+
end
|
|
56
|
+
raise ArgumentError, "invalid radix #{base}" if base < 2
|
|
57
|
+
raise ArgumentError, "no digits" if empty?
|
|
58
|
+
|
|
59
|
+
inject(0) do |n, d|
|
|
60
|
+
v = values ? values[d] : d
|
|
61
|
+
unless v.is_a?(::Integer) && v >= 0 && v < base
|
|
62
|
+
raise ArgumentError, "invalid digit #{d.inspect} for base #{base}"
|
|
63
|
+
end
|
|
64
|
+
n * base + v
|
|
65
|
+
end
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
end
|
|
@@ -87,7 +87,7 @@ class Enumerator::Lazy
|
|
|
87
87
|
# If neither a block nor argument is given, an Enumerator for _all_ indexes is returned.
|
|
88
88
|
#
|
|
89
89
|
# enum = (42 .. Float::INFINITY).lazy.indexes
|
|
90
|
-
# #=>
|
|
90
|
+
# enum.class #=> Enumerator::Lazy
|
|
91
91
|
# enum.next #=> 0
|
|
92
92
|
# enum.next #=> 1
|
|
93
93
|
# enum.first(5) #=> [0, 1, 2, 3, 4]
|
|
@@ -1,20 +1,30 @@
|
|
|
1
1
|
class Array
|
|
2
2
|
|
|
3
|
-
# Split on matching
|
|
4
|
-
# elements.
|
|
5
|
-
#
|
|
6
|
-
# Examples
|
|
3
|
+
# Split on matching elements. Unlike #divide this does not include the
|
|
4
|
+
# matching elements. An element matches if `pattern === element`, so a
|
|
5
|
+
# pattern can be a value, a Regexp or a class.
|
|
7
6
|
#
|
|
8
7
|
# ['a1','a2','b1','a3','b2','a4'].split(/^b/)
|
|
9
8
|
# #=> [['a1','a2'],['a3'],['a4']]
|
|
10
9
|
#
|
|
10
|
+
# Or give a block, and split where it returns true.
|
|
11
|
+
#
|
|
12
|
+
# [1, 2, 3, 4, 5].split { |x| x % 3 == 0 }
|
|
13
|
+
# #=> [[1, 2], [4, 5]]
|
|
14
|
+
#
|
|
15
|
+
# As with ActiveSupport's Array#split, every match ends a piece, so a match
|
|
16
|
+
# at either end gives an empty piece there.
|
|
17
|
+
#
|
|
18
|
+
# [2, 1, 2].split(2) #=> [[], [1], []]
|
|
19
|
+
# [].split(2) #=> [[]]
|
|
20
|
+
#
|
|
11
21
|
# Returns list of split-up arrays. [Array<Array>]
|
|
12
22
|
|
|
13
|
-
def split(pattern)
|
|
23
|
+
def split(pattern=nil, &block)
|
|
14
24
|
memo = []
|
|
15
25
|
sect = []
|
|
16
26
|
each do |obj|
|
|
17
|
-
if pattern === obj
|
|
27
|
+
if block ? block.call(obj) : pattern === obj
|
|
18
28
|
memo << sect
|
|
19
29
|
sect = []
|
|
20
30
|
else
|
|
@@ -22,9 +32,6 @@ class Array
|
|
|
22
32
|
end
|
|
23
33
|
end
|
|
24
34
|
memo << sect
|
|
25
|
-
memo.pop while memo.last == []
|
|
26
|
-
memo
|
|
27
35
|
end
|
|
28
36
|
|
|
29
37
|
end
|
|
30
|
-
|
|
@@ -5,10 +5,10 @@ class Array
|
|
|
5
5
|
#
|
|
6
6
|
# Examples
|
|
7
7
|
#
|
|
8
|
-
# ['a1','a2','b1','a3','b2','a4'].
|
|
9
|
-
# #=> [['a1','a2'],b1,['a3','b2','a4']]
|
|
8
|
+
# ['a1','a2','b1','a3','b2','a4'].split_at('b1')
|
|
9
|
+
# #=> [['a1','a2'],'b1',['a3','b2','a4']]
|
|
10
10
|
#
|
|
11
|
-
# ['a1','a2','b1','a3','b2','a4'].
|
|
11
|
+
# ['a1','a2','b1','a3','b2','a4'].split_at('foo')
|
|
12
12
|
# #=> [[],nil,[]]
|
|
13
13
|
#
|
|
14
14
|
# Returns list of split-up arrays. [Tuple<Array,Object,Array>]
|
data/lib/core/facets/array.rb
CHANGED
|
@@ -16,6 +16,7 @@ require_relative 'array/each_pair.rb'
|
|
|
16
16
|
require_relative 'array/each_value.rb'
|
|
17
17
|
require_relative 'array/entropy.rb'
|
|
18
18
|
require_relative 'array/from.rb'
|
|
19
|
+
require_relative 'array/from_base.rb'
|
|
19
20
|
require_relative 'array/indexable.rb'
|
|
20
21
|
#require_relative 'array/intersection.rb' # too new
|
|
21
22
|
#require_relative 'array/median.rb' # uncommon
|
data/lib/core/facets/boolean.rb
CHANGED
|
@@ -69,7 +69,7 @@ end
|
|
|
69
69
|
class String
|
|
70
70
|
# Interpret common affirmative string meanings as true,
|
|
71
71
|
# otherwise nil or false. Blank space and case are ignored.
|
|
72
|
-
# The following strings that will return true
|
|
72
|
+
# The following strings that will return true:
|
|
73
73
|
#
|
|
74
74
|
# true
|
|
75
75
|
# yes
|
|
@@ -79,7 +79,7 @@ class String
|
|
|
79
79
|
# y
|
|
80
80
|
# ==
|
|
81
81
|
#
|
|
82
|
-
# The following strings will return nil
|
|
82
|
+
# The following strings will return nil:
|
|
83
83
|
#
|
|
84
84
|
# nil
|
|
85
85
|
# null
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
class Class
|
|
2
2
|
|
|
3
|
-
# List all
|
|
3
|
+
# List all descendants of this class. The order differs between
|
|
4
|
+
# Rubies, so these examples sort the list.
|
|
4
5
|
#
|
|
5
6
|
# class A ; end
|
|
6
7
|
# class B < A; end
|
|
7
8
|
# class C < A; end
|
|
8
|
-
# A.descendants #=> [B,C]
|
|
9
|
+
# A.descendants.sort_by(&:name) #=> [B,C]
|
|
9
10
|
#
|
|
10
11
|
# You may also limit the generational distance the subclass may be from
|
|
11
12
|
# the parent class.
|
|
@@ -13,22 +14,35 @@ class Class
|
|
|
13
14
|
# class X ; end
|
|
14
15
|
# class Y < X; end
|
|
15
16
|
# class Z < Y; end
|
|
16
|
-
# X.descendants
|
|
17
|
-
# X.descendants(1)
|
|
17
|
+
# X.descendants.sort_by(&:name) #=> [Y,Z]
|
|
18
|
+
# X.descendants(1) #=> [Y]
|
|
19
|
+
#
|
|
20
|
+
# Ruby 4.1 adds its own Module#descendants. Where Ruby has it, a call
|
|
21
|
+
# without a limit is passed to Ruby's, and Facets only handles the
|
|
22
|
+
# generations limit. Ruby doesn't define the order of its list.
|
|
23
|
+
#
|
|
24
|
+
# On older Rubies, the list is in the same order as ActiveSupport's
|
|
25
|
+
# Class#descendants: the subclasses first, then each one's own
|
|
26
|
+
# descendants.
|
|
27
|
+
#
|
|
28
|
+
# The generations walk goes through #subclasses only, never #descendants,
|
|
29
|
+
# because ActiveSupport wraps #descendants in a version that takes no
|
|
30
|
+
# argument.
|
|
31
|
+
#
|
|
32
|
+
# NOTE: With ActiveSupport loaded, calling descendants with an argument
|
|
33
|
+
# raises ArgumentError, because of that wrapper.
|
|
18
34
|
#
|
|
19
35
|
# NOTE: This is a intensive operation. Do not expect it to be very fast.
|
|
20
36
|
#
|
|
21
37
|
# @author Roger Pack
|
|
22
38
|
def descendants(generations=-1)
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
if
|
|
27
|
-
|
|
28
|
-
end
|
|
39
|
+
return super() if generations < 1 && Module.method_defined?(:descendants)
|
|
40
|
+
walk = lambda do |klass, gen|
|
|
41
|
+
subs = klass.subclasses
|
|
42
|
+
next subs if gen == 1
|
|
43
|
+
subs + subs.flat_map { |k| walk.(k, gen - 1) }
|
|
29
44
|
end
|
|
30
|
-
|
|
45
|
+
walk.(self, generations)
|
|
31
46
|
end
|
|
32
47
|
|
|
33
48
|
end
|
|
34
|
-
|
|
@@ -5,7 +5,7 @@ class Dir
|
|
|
5
5
|
# Dir.multiglob('tmp/*.rb', 'tmp/*.py')
|
|
6
6
|
#
|
|
7
7
|
# Rather then constants for options multiglob accepts a trailing options
|
|
8
|
-
# hash of symbol keys
|
|
8
|
+
# hash of symbol keys:
|
|
9
9
|
#
|
|
10
10
|
# :noescape File::FNM_NOESCAPE
|
|
11
11
|
# :casefold File::FNM_CASEFOLD
|
|
@@ -13,7 +13,7 @@ class Dir
|
|
|
13
13
|
# :dotmatch File::FNM_DOTMATCH
|
|
14
14
|
# :strict File::FNM_PATHNAME && File::FNM_DOTMATCH
|
|
15
15
|
#
|
|
16
|
-
# It also has an option for recurse
|
|
16
|
+
# It also has an option for recurse:
|
|
17
17
|
#
|
|
18
18
|
# :recurse Recurively include contents of directories.
|
|
19
19
|
#
|
|
@@ -26,11 +26,10 @@ class Dir
|
|
|
26
26
|
# Dir.multiglob('tmp/**/*')
|
|
27
27
|
#
|
|
28
28
|
def self.multiglob(*patterns)
|
|
29
|
-
options = (Hash === patterns.last ? patterns.pop : {})
|
|
29
|
+
options = (Hash === patterns.last ? patterns.pop.dup : {})
|
|
30
30
|
|
|
31
31
|
if options.delete(:recurse)
|
|
32
|
-
|
|
33
|
-
multiglob_r(*patterns)
|
|
32
|
+
return multiglob_r(*patterns)
|
|
34
33
|
end
|
|
35
34
|
|
|
36
35
|
bitflags = 0
|
|
@@ -41,10 +40,6 @@ class Dir
|
|
|
41
40
|
|
|
42
41
|
patterns = [patterns].flatten.compact
|
|
43
42
|
|
|
44
|
-
if options[:recurse]
|
|
45
|
-
patterns += patterns.collect{ |f| File.join(f, '**', '**') }
|
|
46
|
-
end
|
|
47
|
-
|
|
48
43
|
files = []
|
|
49
44
|
files += patterns.collect{ |pattern| Dir.glob(pattern, bitflags) }.flatten.uniq
|
|
50
45
|
|
|
@@ -10,9 +10,9 @@ module Enumerable
|
|
|
10
10
|
# r #=> 6
|
|
11
11
|
#
|
|
12
12
|
def apply
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
##Functor.new do |sym, *args, &blk|
|
|
14
|
+
## inject{ |r, e| r.__send__(sym, e, *args, &blk) }
|
|
15
|
+
##end
|
|
16
16
|
per(:inject)
|
|
17
17
|
end
|
|
18
18
|
|
|
@@ -3,10 +3,10 @@ module Enumerable
|
|
|
3
3
|
# Clusters together adjacent elements into a list of sub-arrays.
|
|
4
4
|
#
|
|
5
5
|
# [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
|
|
6
|
-
#
|
|
6
|
+
# #=> [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
|
|
7
7
|
#
|
|
8
8
|
# ["dog", "duck", "cat", "dude"].cluster{ |x| x[0] }
|
|
9
|
-
#
|
|
9
|
+
# #=> [["dog", "duck"], ["cat"], ["dude"]]
|
|
10
10
|
#
|
|
11
11
|
# @author Oleg K
|
|
12
12
|
|
|
@@ -26,9 +26,12 @@ module Enumerable
|
|
|
26
26
|
# Array or Hash built with the results, or each{...} if you just want
|
|
27
27
|
# to output each result and discard it.
|
|
28
28
|
#
|
|
29
|
+
# @deprecated Use Enumerable#lazy, built into Ruby since 2.0. The block
|
|
30
|
+
# form is Enumerator::Lazy.new(enum) { |out, i| ... }. Scheduled for
|
|
31
|
+
# removal after 2027-09-30.
|
|
29
32
|
def defer(&blk)
|
|
30
33
|
warn "Enumerable#defer is deprecated. Use Enumerable#lazy instead. It will be removed after 2027-09-30.", uplevel: 1
|
|
31
|
-
lazy
|
|
34
|
+
blk ? Enumerator::Lazy.new(self, &blk) : lazy
|
|
32
35
|
end
|
|
33
36
|
|
|
34
37
|
end
|