facets 4.1.0 → 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.
Files changed (79) hide show
  1. checksums.yaml +4 -4
  2. data/HISTORY.md +82 -0
  3. data/README.md +1 -1
  4. data/lib/core/facets/array/commonality.rb +1 -1
  5. data/lib/core/facets/array/delete_first.rb +6 -5
  6. data/lib/core/facets/array/divide.rb +1 -1
  7. data/lib/core/facets/array/from_base.rb +68 -0
  8. data/lib/core/facets/array/indexes.rb +1 -1
  9. data/lib/core/facets/array/occur.rb +1 -1
  10. data/lib/core/facets/array/split_at.rb +3 -3
  11. data/lib/core/facets/array.rb +1 -0
  12. data/lib/core/facets/boolean.rb +2 -2
  13. data/lib/core/facets/class/descendants.rb +5 -4
  14. data/lib/core/facets/dir/ascend.rb +1 -2
  15. data/lib/core/facets/dir/multiglob.rb +4 -9
  16. data/lib/core/facets/enumerable/apply.rb +3 -3
  17. data/lib/core/facets/enumerable/cluster.rb +2 -2
  18. data/lib/core/facets/enumerable/hashify.rb +5 -5
  19. data/lib/core/facets/enumerable/with_position.rb +2 -2
  20. data/lib/core/facets/enumerator/fx.rb +11 -11
  21. data/lib/core/facets/essentials.rb +2 -2
  22. data/lib/core/facets/file/atomic_open.rb +1 -1
  23. data/lib/core/facets/file/rewrite.rb +4 -4
  24. data/lib/core/facets/hash/deep_rekey.rb +1 -1
  25. data/lib/core/facets/hash/except.rb +1 -1
  26. data/lib/core/facets/hash/op_mul.rb +2 -0
  27. data/lib/core/facets/hash/op_push.rb +7 -7
  28. data/lib/core/facets/hash/rekey.rb +7 -7
  29. data/lib/core/facets/hash/weave.rb +1 -1
  30. data/lib/core/facets/integer/to_base.rb +115 -0
  31. data/lib/core/facets/integer.rb +1 -0
  32. data/lib/core/facets/kernel/ask.rb +3 -3
  33. data/lib/core/facets/kernel/blank.rb +4 -4
  34. data/lib/core/facets/kernel/callstack.rb +2 -2
  35. data/lib/core/facets/kernel/d.rb +3 -3
  36. data/lib/core/facets/kernel/demo.rb +2 -2
  37. data/lib/core/facets/kernel/functor.rb +1 -1
  38. data/lib/core/facets/kernel/instance_assign.rb +2 -3
  39. data/lib/core/facets/kernel/instance_replace.rb +2 -2
  40. data/lib/core/facets/kernel/maybe.rb +1 -1
  41. data/lib/core/facets/kernel/meta_class.rb +2 -1
  42. data/lib/core/facets/kernel/meta_def.rb +3 -3
  43. data/lib/core/facets/kernel/object_hexid.rb +2 -7
  44. data/lib/core/facets/kernel/try.rb +3 -1
  45. data/lib/core/facets/module/attr_class_accessor.rb +2 -2
  46. data/lib/core/facets/module/class_accessor.rb +2 -2
  47. data/lib/core/facets/module/instance_method.rb +2 -2
  48. data/lib/core/facets/module/is.rb +1 -1
  49. data/lib/core/facets/numeric/delimit.rb +1 -1
  50. data/lib/core/facets/proc/wrap.rb +1 -1
  51. data/lib/core/facets/range/op_sub.rb +2 -2
  52. data/lib/core/facets/range/within.rb +1 -1
  53. data/lib/core/facets/regexp/op_or.rb +1 -1
  54. data/lib/core/facets/string/align.rb +4 -4
  55. data/lib/core/facets/string/ascii_only.rb +2 -2
  56. data/lib/core/facets/string/dashcase.rb +1 -1
  57. data/lib/core/facets/string/file.rb +1 -1
  58. data/lib/core/facets/string/from_base.rb +85 -0
  59. data/lib/core/facets/string/indent.rb +3 -3
  60. data/lib/core/facets/string/margin.rb +18 -4
  61. data/lib/core/facets/string/mask.rb +264 -0
  62. data/lib/core/facets/string/natcmp.rb +1 -1
  63. data/lib/core/facets/string/random.rb +1 -1
  64. data/lib/core/facets/string/rotate.rb +1 -1
  65. data/lib/core/facets/string/similarity.rb +2 -2
  66. data/lib/core/facets/string/trim.rb +1 -1
  67. data/lib/core/facets/string/unfold.rb +1 -1
  68. data/lib/core/facets/string/word_wrap.rb +1 -1
  69. data/lib/core/facets/string/words.rb +2 -2
  70. data/lib/core/facets/string.rb +2 -0
  71. data/lib/core/facets/symbol/call.rb +0 -9
  72. data/lib/core/facets/time/change.rb +3 -3
  73. data/lib/core/facets/time/stamp.rb +1 -1
  74. data/lib/core/facets/version.rb +1 -1
  75. data/lib/rails/facets/file/atomic_write.rb +1 -1
  76. data/lib/standard/facets/crypt3.rb +4 -2
  77. data/lib/standard/facets/mirror.rb +276 -0
  78. data/lib/standard/facets/paramix.rb +150 -0
  79. metadata +7 -1
@@ -0,0 +1,264 @@
1
+ class String
2
+
3
+ # Make a mask of the string, in which each `re` is an empty slot.
4
+ # See String::Mask.
5
+ #
6
+ # m = "abc..123".mask('.')
7
+ # (m + "ab..789.").to_s #=> "abc.7893"
8
+ #
9
+ # re - The character that marks an empty slot. [String]
10
+ #
11
+ # Returns a new mask. [String::Mask]
12
+ #
13
+ # @uncommon
14
+ # require 'facets/string/mask'
15
+ #
16
+ # Since: 4.2.0
17
+
18
+ def mask(re=nil)
19
+ Mask.new(self, re)
20
+ end
21
+
22
+ # A Mask is a string in which some characters are empty slots. Masks
23
+ # of the same length combine character by character, with operators
24
+ # that work like those of sets or bits.
25
+ #
26
+ # m1 = String::Mask.new("abc..123", '.')
27
+ # m2 = "ab..789.".mask('.')
28
+ #
29
+ # (m1 + m2).to_s #=> "abc.7893"
30
+ # (m1 - m2).to_s #=> "....789."
31
+ # (m1 & m2).to_s #=> "ab......"
32
+ # (m1 ^ m2).to_s #=> "..c.7..3"
33
+ #
34
+ # The second operand can be an ordinary string, which is read as a
35
+ # mask with the same empty-slot character as the first.
36
+ #
37
+ # ("abc..123".mask('.') + "ab..789.").to_s #=> "abc.7893"
38
+ #
39
+ # Where one mask is shorter than the other, its missing characters
40
+ # count as empty slots.
41
+ #
42
+ # Without an empty-slot character, the ASCII substitute character
43
+ # (`"\x1A"`, Mask::ESC) marks an empty slot. That is the better choice
44
+ # when "." or any other printable character might be part of the text.
45
+ #
46
+ # Methods a mask doesn't have are passed to its string, so
47
+ # `mask.size` and `mask.upcase` work as they do for a string.
48
+ #
49
+ # Based on the Strmask gem, which began as Facets' `string/mask`.
50
+ #
51
+ # Since: 4.2.0
52
+ # Author: Trans
53
+
54
+ class Mask
55
+
56
+ # The character that stands for an empty slot inside a mask: ASCII
57
+ # substitute.
58
+ ESC = "\032"
59
+
60
+ # Make a mask. Same as Mask.new.
61
+ #
62
+ # Returns a new mask. [String::Mask]
63
+ def self.[](string, re=nil)
64
+ new(string, re)
65
+ end
66
+
67
+ # string - Any string, or the string of another mask. [String]
68
+ # re - The character that marks an empty slot. [String]
69
+ def initialize(string, re=nil)
70
+ @to_str = string.to_str.dup
71
+ @re = re || ESC
72
+ mask!(re) if re
73
+ end
74
+
75
+ # The underlying string, in which ESC marks each empty slot.
76
+ #
77
+ # Returns the string. [String]
78
+ def to_str
79
+ @to_str
80
+ end
81
+
82
+ # The mask as an ordinary string, with the empty-slot character it
83
+ # was made with.
84
+ #
85
+ # Returns a new string. [String]
86
+ def to_s
87
+ @to_str.gsub(ESC, @re)
88
+ end
89
+
90
+ #
91
+ def inspect
92
+ to_s.inspect
93
+ end
94
+
95
+ # Index into the underlying string.
96
+ def [](*a)
97
+ to_str[*a]
98
+ end
99
+
100
+ # A mask of the same underlying string with another empty-slot
101
+ # character.
102
+ #
103
+ # re - The character that marks an empty slot. [String]
104
+ #
105
+ # Returns a new mask. [String::Mask]
106
+ def mask(re)
107
+ self.class.new(to_str, re)
108
+ end
109
+
110
+ # Turn each `re` in this mask into an empty slot.
111
+ #
112
+ # Returns this mask. [String::Mask]
113
+ def mask!(re)
114
+ to_str.gsub!(re){ |s| ESC * s.size }
115
+ self
116
+ end
117
+
118
+ # Mask subtraction. Where the characters are the same, the result is
119
+ # empty; where they differ, the result is the other's.
120
+ #
121
+ # a = "abc..123".mask('.')
122
+ # b = "ab..789.".mask('.')
123
+ #
124
+ # (a - b).to_s #=> "....789."
125
+ # (b - a).to_s #=> "..c..123"
126
+ #
127
+ def -(other)
128
+ combine(other){ |a, b| a == b ? ESC : b }
129
+ end
130
+
131
+ # Mask addition. The other's character comes through unless it is
132
+ # empty, in which case this mask's does.
133
+ #
134
+ # a = "abc..123".mask('.')
135
+ # b = "ab..789.".mask('.')
136
+ #
137
+ # (a + b).to_s #=> "abc.7893"
138
+ # (b + a).to_s #=> "abc.7123"
139
+ #
140
+ def +(other)
141
+ combine(other){ |a, b| b == ESC ? a : b }
142
+ end
143
+
144
+ # Mask OR is the same as addition.
145
+ alias_method :|, :+
146
+
147
+ # Mask XAND. Where the characters are the same, the result is the
148
+ # same; where they differ, the result is the other's.
149
+ #
150
+ # a = "abc..123".mask('.')
151
+ # b = "ab..789.".mask('.')
152
+ #
153
+ # (a * b).to_s #=> "ab..789."
154
+ # (b * a).to_s #=> "abc..123"
155
+ #
156
+ def *(other)
157
+ combine(other){ |a, b| a == b ? a : b }
158
+ end
159
+
160
+ # Mask AND. Only characters that are the same come through.
161
+ #
162
+ # a = "abc..123".mask('.')
163
+ # b = "ab..789.".mask('.')
164
+ #
165
+ # (a & b).to_s #=> "ab......"
166
+ # (b & a).to_s #=> "ab......"
167
+ #
168
+ def &(other)
169
+ combine(other){ |a, b| a == b ? a : ESC }
170
+ end
171
+
172
+ # Mask XOR. A character comes through only where the other mask has
173
+ # an empty slot.
174
+ #
175
+ # a = "abc..123".mask('.')
176
+ # b = "ab..789.".mask('.')
177
+ #
178
+ # (a ^ b).to_s #=> "..c.7..3"
179
+ # (b ^ a).to_s #=> "..c.7..3"
180
+ #
181
+ def ^(other)
182
+ combine(other) do |a, b|
183
+ if a == ESC then b
184
+ elsif b == ESC then a
185
+ else ESC
186
+ end
187
+ end
188
+ end
189
+
190
+ # Masks are equal if they have the same characters and the same
191
+ # empty slots, whatever character each was made with. A mask is
192
+ # never equal to an ordinary string: compare its `to_s` instead.
193
+ #
194
+ # m = "abc..123".mask('.')
195
+ #
196
+ # (m == "abc__123".mask('_')) #=> true
197
+ # (m == "abc..123") #=> false
198
+ # (m.to_s == "abc..123") #=> true
199
+ #
200
+ def ==(other)
201
+ Mask === other && to_str == other.to_str
202
+ end
203
+
204
+ alias_method :eql?, :==
205
+
206
+ #
207
+ def hash
208
+ to_str.hash
209
+ end
210
+
211
+ # Call a method on the underlying string and make a mask of the
212
+ # result.
213
+ #
214
+ # "abc..123".mask('.').apply(:upcase).to_s #=> "ABC..123"
215
+ #
216
+ # Returns a new mask. [String::Mask]
217
+ def apply(op, *a, &b)
218
+ self.class.new(to_str.public_send(op, *a, &b), @re)
219
+ end
220
+
221
+ # Replace the underlying string.
222
+ #
223
+ # Returns this mask. [String::Mask]
224
+ def replace(string)
225
+ @to_str = string.to_s.dup
226
+ self
227
+ end
228
+
229
+ # Pass any other method to the underlying string.
230
+ def method_missing(s, *a, &b)
231
+ if to_str.respond_to?(s)
232
+ to_str.public_send(s, *a, &b)
233
+ else
234
+ super
235
+ end
236
+ end
237
+
238
+ #
239
+ def respond_to_missing?(s, include_all=false)
240
+ to_str.respond_to?(s) || super
241
+ end
242
+
243
+ private
244
+
245
+ # Read anything that isn't a mask as one with this mask's empty-slot
246
+ # character.
247
+ def convert(other)
248
+ Mask === other ? other : self.class.new(other.to_str, @re)
249
+ end
250
+
251
+ # A new mask made by giving the block each pair of characters, with
252
+ # ESC standing in past the end of the shorter mask.
253
+ def combine(other)
254
+ other = convert(other).to_str
255
+ out = String.new(encoding: to_str.encoding)
256
+ [to_str.size, other.size].max.times do |i|
257
+ out << yield(to_str[i] || ESC, other[i] || ESC)
258
+ end
259
+ self.class.new(out, @re)
260
+ end
261
+
262
+ end
263
+
264
+ end
@@ -29,7 +29,7 @@
29
29
  #
30
30
  class String
31
31
 
32
- # 'Natural order' comparison of strings, e.g. ...
32
+ # 'Natural order' comparison of strings, e.g.:
33
33
  #
34
34
  # "my_prog_v1.1.0" < "my_prog_v1.2.0" < "my_prog_v1.10.0"
35
35
  #
@@ -4,7 +4,7 @@ class String
4
4
  #
5
5
  # Character set is an Array which can contain Ranges, Arrays, Characters
6
6
  #
7
- # Examples
7
+ # Examples:
8
8
  #
9
9
  # String.random
10
10
  # => "D9DxFIaqR3dr8Ct1AfmFxHxqGsmA4Oz3"
@@ -16,7 +16,7 @@ class String
16
16
  #
17
17
  # s='abcdefgh'
18
18
  # s.rotate!(2)
19
- # s.should eq 'cdefghab'
19
+ # s #=> 'cdefghab'
20
20
  #
21
21
  # CREDIT: T. Yamada
22
22
  def rotate!(count=1) replace(rotate(count)) end
@@ -8,13 +8,13 @@ class String
8
8
  #
9
9
  # The way it works:
10
10
  #
11
- # 1. Converts each string into a "graph like" object, with edges ...
11
+ # 1. Converts each string into a "graph like" object, with edges:
12
12
  #
13
13
  # "alexsander" -> [ alexsander, alexsand, alexsan ... lexsand ... san ... an, etc ]
14
14
  # "aleksander" -> [ aleksander, aleksand ... etc. ]
15
15
  #
16
16
  # 2. Perform match, then remove any subsets from this matched set (i.e. a hit
17
- # on "san" is a subset of a hit on "sander") ...
17
+ # on "san" is a subset of a hit on "sander"):
18
18
  #
19
19
  # Above example, once reduced -> [ ale, sander ]
20
20
  #
@@ -7,7 +7,7 @@ class String
7
7
  # when literal multi-line strings are needed in code.
8
8
  #
9
9
  # num - Number of extra spaces with which to replace the
10
- # trim character. [Integer]
10
+ # trim character. [Integer]
11
11
  #
12
12
  # Examples
13
13
  #
@@ -7,7 +7,7 @@ class String
7
7
  # change in the future.
8
8
  #
9
9
  # FIXME: Sometimes adds one too many blank lines, which is why we are
10
- # using rstrip. Fix and probably remove the rstrip.
10
+ # using rstrip. Fix and probably remove the rstrip.
11
11
  #
12
12
  def unfold
13
13
  blank = false
@@ -4,7 +4,7 @@ class String
4
4
  #
5
5
  # "this is a test".word_wrap(4)
6
6
  #
7
- # _produces_ ...
7
+ # _produces_:
8
8
  #
9
9
  # this
10
10
  # is a
@@ -11,8 +11,8 @@ class String
11
11
  # Returns an array of words in the commonly-understood sense (not including punctuation).
12
12
  # This takes into account international punctuation characters as well as English ones.
13
13
  #
14
- # 'Slowly, grudgingly he said: "This has to stop."'.words
15
- # => ["Slowly", "grudgingly", "he", "said", "This", "has", "to", "stop"]
14
+ # 'Slowly, grudgingly he said: "This has to stop."'.words_without_punctuation
15
+ # #=> ["Slowly", "grudgingly", "he", "said", "This", "has", "to", "stop"]
16
16
  def words_without_punctuation
17
17
  s = self.dup
18
18
  s.gsub!(/[.?¿¡…!,::;—"。?!、‘“”„«»〈〉《》,\/\[\]]/, ' ')
@@ -16,6 +16,7 @@ require_relative 'string/exclude.rb'
16
16
  require_relative 'string/expand_tab.rb'
17
17
  require_relative 'string/file.rb'
18
18
  require_relative 'string/fold.rb'
19
+ require_relative 'string/from_base.rb'
19
20
  require_relative 'string/indent.rb'
20
21
  require_relative 'string/index_all.rb'
21
22
  require_relative 'string/interpolate.rb'
@@ -24,6 +25,7 @@ require_relative 'string/line_wrap.rb'
24
25
  require_relative 'string/linear.rb'
25
26
  require_relative 'string/lowercase.rb'
26
27
  require_relative 'string/margin.rb'
28
+ #require_relative 'string/mask.rb' # uncommon
27
29
  require_relative 'string/methodize.rb'
28
30
  require_relative 'string/modulize.rb'
29
31
  require_relative 'string/mscan.rb'
@@ -9,15 +9,6 @@ class Symbol
9
9
  # [1,2,3].map(&:to_s.(2))
10
10
  # #=> ['1','10','11']
11
11
  #
12
- # ['abc','cdef','xy','z','wwww'].select(&:size.() == 4)
13
- # #=> ['cdef', 'wwww']
14
- #
15
- # ['abc','aaA','AaA','z'].count(&:upcase.().succ == 'AAB')
16
- # #=> 2
17
- #
18
- # [%w{1 2 3 4 5},%w{6 7 8 9}].map(&:join.().length)
19
- # #=> [5,4]
20
- #
21
12
  # CREDIT: Ilya Vorontsov, Nobuyoshi Nakada
22
13
 
23
14
  def call(*args, &block)
@@ -7,7 +7,7 @@ class Time
7
7
  # minute, sec, and usec is set to 0. If the hour and
8
8
  # minute is passed, then sec and usec is set to 0.
9
9
  #
10
- # t1 = Time.at(10000)
10
+ # t1 = Time.at(10000, in: "-05:00")
11
11
  # t1.ctime #=> "Wed Dec 31 21:46:40 1969"
12
12
  #
13
13
  # t2 = t1.change(:hour => 11)
@@ -18,8 +18,8 @@ class Time
18
18
  # unless :offset gives a new one.
19
19
  #
20
20
  # t = Time.new(2026, 11, 4, 15, 30, 0, "+09:00")
21
- # t.change(hour: 1) #=> 2026-11-04 01:00:00 +0900
22
- # t.change(offset: "+01:00") #=> 2026-11-04 15:30:00 +0100
21
+ # t.change(hour: 1).to_s #=> "2026-11-04 01:00:00 +0900"
22
+ # t.change(offset: "+01:00").to_s #=> "2026-11-04 15:30:00 +0100"
23
23
  #
24
24
  # It takes the same options and gives the same results as ActiveSupport's
25
25
  # Time#change, so the two agree whichever is loaded.
@@ -29,7 +29,7 @@ class Time
29
29
 
30
30
  # Create a time stamp.
31
31
  #
32
- # t = Time.at(10000)
32
+ # t = Time.at(10000, in: "-05:00")
33
33
  # t.stamp(:short) #=> "31 Dec 21:46"
34
34
  #
35
35
  # Supported formats come from the Time::FORMAT constant.
@@ -1,3 +1,3 @@
1
1
  module Facets
2
- VERSION = '4.1.0'
2
+ VERSION = '4.2.0'
3
3
  end
@@ -27,7 +27,7 @@ class File
27
27
  # CREDIT: David Heinemeier Hansson
28
28
  #
29
29
  # @uncommon
30
- # require 'facets/fileutils/atomic_write'
30
+ # require 'facets/file/atomic_write'
31
31
  #
32
32
  def self.atomic_write(file_name, temp_dir=nil)
33
33
  temp_dir = temp_dir || Dir.tmpdir
@@ -1,3 +1,5 @@
1
+ require 'securerandom'
2
+
1
3
  # Crypt3 is a pure Ruby version of crypt(3), a salted one-way hashing
2
4
  # of a password.
3
5
  #
@@ -112,7 +114,7 @@ module Crypt3
112
114
  self.crypt(password, algo, salt, magic) == hash
113
115
  end
114
116
 
115
- # Generate a random salt of the given size.
117
+ # Generate a random salt of the given size, from SecureRandom.
116
118
  #
117
119
  # Crypt3.generate_salt(8) #=> "xK3d9Wq2"
118
120
  #
@@ -120,7 +122,7 @@ module Crypt3
120
122
  #
121
123
  # Returns random salt. [String]
122
124
  def self.generate_salt(size)
123
- (1..size).map { ITOA64[rand(ITOA64.size)] }.join
125
+ (1..size).map { ITOA64[SecureRandom.random_number(ITOA64.size)] }.join
124
126
  end
125
127
 
126
128
  end