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,276 @@
1
+ module Kernel
2
+
3
+ # A Mirror looks at an object from the outside: its instance variables,
4
+ # its class and its methods. Ruby puts these reflection methods on every
5
+ # object, where a class can redefine them or, like BasicObject, not have
6
+ # them. A mirror calls Ruby's own versions, saved when this file loads,
7
+ # so it gives the true answers for any object.
8
+ #
9
+ # class Song
10
+ # def initialize(title, year)
11
+ # @title, @year = title, year
12
+ # end
13
+ # end
14
+ #
15
+ # song = Song.new("Paranoid", 1970)
16
+ # mirror = song.mirror # or Mirror.new(song)
17
+ #
18
+ # mirror.keys #=> [:title, :year]
19
+ # mirror[:title] #=> "Paranoid"
20
+ # mirror.to_h #=> {title: "Paranoid", year: 1970}
21
+ # mirror.update(year: 1971)
22
+ # mirror[:year] #=> 1971
23
+ #
24
+ # Instance variable names can be given with or without the "@".
25
+ #
26
+ # The class lives in Kernel, so `Mirror` works everywhere, but an
27
+ # application's own top-level `Mirror` class doesn't clash with it: the
28
+ # application's takes precedence, and this one is still
29
+ # `Kernel::Mirror`. A class can also define its own `#mirror`, so code
30
+ # that must work on any object should use `Mirror.new(obj)`.
31
+ #
32
+ # NOTE: This is not loaded by `require 'facets'`. Use:
33
+ #
34
+ # require 'facets/mirror'
35
+ #
36
+ # Based on the Instance gem.
37
+ #
38
+ # Since: 4.2.0
39
+ # Author: Trans
40
+
41
+ class Mirror
42
+ include Enumerable
43
+
44
+ # Ruby's own reflection methods, saved so that later changes to them,
45
+ # or an object that redefines them, can't affect a mirror. Methods
46
+ # from Kernel and BasicObject can be called on any object, including
47
+ # a BasicObject.
48
+ KERNEL = %i[
49
+ class instance_of? kind_of? object_id to_s
50
+ instance_variables instance_variable_get instance_variable_set
51
+ instance_variable_defined? remove_instance_variable
52
+ methods public_methods protected_methods private_methods
53
+ singleton_methods method
54
+ ].to_h { |name| [name, ::Kernel.instance_method(name)] }.merge(
55
+ %i[instance_eval instance_exec].to_h { |name| [name, ::BasicObject.instance_method(name)] }
56
+ ).freeze
57
+
58
+ # Ruby's own Module reflection methods, for a mirror of a module or
59
+ # class.
60
+ MODULE = %i[
61
+ instance_methods public_instance_methods protected_instance_methods
62
+ private_instance_methods instance_method
63
+ ].to_h { |name| [name, ::Module.instance_method(name)] }.freeze
64
+
65
+ private_constant :KERNEL, :MODULE
66
+
67
+ # A mirror of +object+.
68
+ def initialize(object)
69
+ @object = object
70
+ end
71
+
72
+ # The object this mirror reflects.
73
+ attr_reader :object
74
+
75
+ # Instance variable names as Ruby gives them, with the "@".
76
+ #
77
+ # mirror.variables #=> [:@title, :@year]
78
+ def variables
79
+ call(:instance_variables)
80
+ end
81
+
82
+ # Instance variable names as symbols, without the "@".
83
+ #
84
+ # mirror.keys #=> [:title, :year]
85
+ def keys
86
+ variables.map { |name| name[1..-1].to_sym }
87
+ end
88
+
89
+ # Instance variable values, in the same order as #keys.
90
+ def values
91
+ variables.map { |name| call(:instance_variable_get, name) }
92
+ end
93
+
94
+ # Number of instance variables.
95
+ def size
96
+ variables.size
97
+ end
98
+
99
+ # Yields each instance variable's name, without the "@", and value.
100
+ # Mirror is Enumerable, so `to_h`, `select` and the rest work too.
101
+ #
102
+ # mirror.to_h #=> {title: "Paranoid", year: 1970}
103
+ def each
104
+ return to_enum(:each) { size } unless block_given?
105
+ variables.each do |name|
106
+ yield name[1..-1].to_sym, call(:instance_variable_get, name)
107
+ end
108
+ self
109
+ end
110
+
111
+ # Value of an instance variable, or nil if it isn't set.
112
+ def get(name)
113
+ call(:instance_variable_get, ivar(name))
114
+ end
115
+ alias_method :[], :get
116
+
117
+ # Sets an instance variable, and returns the value.
118
+ def set(name, value)
119
+ call(:instance_variable_set, ivar(name), value)
120
+ end
121
+ alias_method :[]=, :set
122
+
123
+ # Sets instance variables from a hash of names and values, and
124
+ # returns the mirror.
125
+ #
126
+ # mirror.update(title: "War Pigs", year: 1970)
127
+ def update(hash)
128
+ hash.each { |name, value| set(name, value) }
129
+ self
130
+ end
131
+
132
+ # Is the instance variable set?
133
+ def key?(name)
134
+ call(:instance_variable_defined?, ivar(name))
135
+ end
136
+
137
+ # Removes an instance variable, and returns its value. Raises
138
+ # NameError if it isn't set.
139
+ def remove(name)
140
+ call(:remove_instance_variable, ivar(name))
141
+ end
142
+
143
+ # Evaluates a string or a block with the object as self, like
144
+ # `instance_eval`.
145
+ def eval(*args, &block)
146
+ call(:instance_eval, *args, &block)
147
+ end
148
+
149
+ # Calls the block with the object as self, passing the arguments, like
150
+ # `instance_exec`.
151
+ def exec(*args, &block)
152
+ call(:instance_exec, *args, &block)
153
+ end
154
+
155
+ # The object's class, even if the object redefines #class.
156
+ def object_class
157
+ call(:class)
158
+ end
159
+
160
+ # Is the object an instance of exactly this class?
161
+ def of?(klass)
162
+ call(:instance_of?, klass)
163
+ end
164
+
165
+ # Is the object an instance of this class or module, or of a
166
+ # subclass, as with `is_a?`?
167
+ def is?(mod)
168
+ call(:kind_of?, mod)
169
+ end
170
+
171
+ # The object's object_id.
172
+ def id
173
+ call(:object_id)
174
+ end
175
+
176
+ # Names of the object's methods. With no arguments, the same as
177
+ # `methods`. Otherwise any of :public, :protected, :private and
178
+ # :singleton, or :all for the first three.
179
+ #
180
+ # mirror.method_names(:private)
181
+ def method_names(*kinds)
182
+ return call(:methods) if kinds.empty?
183
+ kinds = [:public, :protected, :private] if kinds.include?(:all)
184
+ kinds.uniq.flat_map do |kind|
185
+ case kind
186
+ when :public then call(:public_methods)
187
+ when :protected then call(:protected_methods)
188
+ when :private then call(:private_methods)
189
+ when :singleton then call(:singleton_methods)
190
+ else raise ArgumentError, "unknown kind of method: #{kind.inspect}"
191
+ end
192
+ end
193
+ end
194
+
195
+ # The object's method of this name, as a Method, even if the object
196
+ # redefines #method.
197
+ def method_object(name)
198
+ call(:method, name)
199
+ end
200
+
201
+ # For a module or class: names of the methods it defines for its
202
+ # instances. With no arguments, the same as `instance_methods`.
203
+ # Otherwise any of :public, :protected and :private, or :all.
204
+ # Raises TypeError for any other object.
205
+ def method_definitions(*kinds)
206
+ return module_call(:instance_methods) if kinds.empty?
207
+ kinds = [:public, :protected, :private] if kinds.include?(:all)
208
+ kinds.uniq.flat_map do |kind|
209
+ case kind
210
+ when :public then module_call(:public_instance_methods)
211
+ when :protected then module_call(:protected_instance_methods)
212
+ when :private then module_call(:private_instance_methods)
213
+ else raise ArgumentError, "unknown kind of method: #{kind.inspect}"
214
+ end
215
+ end
216
+ end
217
+
218
+ # For a module or class: the instance method of this name, as an
219
+ # UnboundMethod. Raises TypeError for any other object.
220
+ def method_definition(name)
221
+ module_call(:instance_method, name)
222
+ end
223
+
224
+ # Two mirrors are equal if they reflect the same object.
225
+ def ==(other)
226
+ other.is_a?(Mirror) && other.object.equal?(@object)
227
+ end
228
+ alias_method :eql?, :==
229
+
230
+ def hash
231
+ [Mirror, id].hash
232
+ end
233
+
234
+ # Shows the object's class and address, without calling the
235
+ # object's own #inspect, which it may not have.
236
+ def inspect
237
+ "#<#{self.class} of #{call(:to_s)}>"
238
+ end
239
+
240
+ private
241
+
242
+ def call(name, *args, &block)
243
+ KERNEL.fetch(name).bind_call(@object, *args, &block)
244
+ end
245
+
246
+ def module_call(name, *args)
247
+ unless call(:kind_of?, ::Module)
248
+ raise TypeError, "#{call(:class)} is not a module or class"
249
+ end
250
+ MODULE.fetch(name).bind_call(@object, *args)
251
+ end
252
+
253
+ def ivar(name)
254
+ name = name.to_s
255
+ name.start_with?('@') ? name.to_sym : :"@#{name}"
256
+ end
257
+ end
258
+
259
+ # A Mirror of this object, for looking at its instance variables,
260
+ # class and methods from the outside.
261
+ #
262
+ # song.mirror.to_h #=> {title: "Paranoid", year: 1970}
263
+ #
264
+ # A class can define its own #mirror. To be sure of getting a mirror
265
+ # for any object, use `Mirror.new(obj)`.
266
+ #
267
+ # NOTE: This is not loaded by `require 'facets'`. Use:
268
+ #
269
+ # require 'facets/mirror'
270
+ #
271
+ # Since: 4.2.0
272
+ def mirror
273
+ ::Kernel::Mirror.new(self)
274
+ end
275
+
276
+ end
@@ -0,0 +1,150 @@
1
+ # Paramix makes a module parametric: one that takes parameters where it
2
+ # is included or extended, with `Module[parameters]`. Its `parameterized`
3
+ # block is given the parameters, and defines the methods that depend on
4
+ # them.
5
+ #
6
+ # module Greeter
7
+ # include Paramix
8
+ #
9
+ # parameterized do |params|
10
+ # define_method :hello do
11
+ # "Hello from #{params[:name]}!"
12
+ # end
13
+ # end
14
+ # end
15
+ #
16
+ # class English
17
+ # include Greeter[:name => 'England']
18
+ # end
19
+ #
20
+ # class Scots
21
+ # include Greeter[:name => 'Scotland']
22
+ # end
23
+ #
24
+ # English.new.hello #=> "Hello from England!"
25
+ # Scots.new.hello #=> "Hello from Scotland!"
26
+ #
27
+ # Each use of `Module[parameters]` makes a new module that includes the
28
+ # parametric one, so each class gets its own methods. The block runs in
29
+ # that module, where `public`, `private` and `protected` also define a
30
+ # method when given a block:
31
+ #
32
+ # module Named
33
+ # include Paramix
34
+ #
35
+ # parameterized do |params|
36
+ # public(params[:as]) { params[:value] }
37
+ # end
38
+ # end
39
+ #
40
+ # class Config
41
+ # extend Named[:as => :env, :value => 'test']
42
+ # end
43
+ #
44
+ # Config.env #=> "test"
45
+ #
46
+ # A module that includes a parametric module without giving it
47
+ # parameters becomes parametric too, and passes its own parameters on.
48
+ #
49
+ # NOTE: This is not loaded by `require 'facets'`. Use:
50
+ #
51
+ # require 'facets/paramix'
52
+ #
53
+ # Based on the Paramix gem.
54
+ #
55
+ # Since: 4.2.0
56
+ # Author: Trans
57
+
58
+ module Paramix
59
+
60
+ #
61
+ def self.included(base)
62
+ base.extend(Extensions)
63
+ end
64
+
65
+ # Class-level methods of a parametric module.
66
+ module Extensions
67
+
68
+ # Apply parameters, giving a module to include or extend.
69
+ #
70
+ # Returns a new Mixin. [Mixin]
71
+ def [](parameters={})
72
+ Mixin.new(self, parameters)
73
+ end
74
+
75
+ # Add a block to run when parameters are applied. Without a block,
76
+ # gives the blocks added so far.
77
+ #
78
+ # Returns the list of blocks. [Array<Proc>]
79
+ def parameterized(&code)
80
+ @code ||= []
81
+ if block_given?
82
+ @code << code
83
+ else
84
+ @code
85
+ end
86
+ end
87
+
88
+ #
89
+ def append_features(base)
90
+ return super(base) if Mixin === base || Mixin === self
91
+
92
+ base.extend(Extensions)
93
+
94
+ anc = ancestors.find{ |a| a.respond_to?(:parameterized) }
95
+ base.parameterized.concat(anc.parameterized)
96
+
97
+ super(base)
98
+ end
99
+
100
+ #
101
+ def extend_object(base)
102
+ return super(base) if Mixin === base || Mixin === self
103
+
104
+ base.extend(Extensions)
105
+
106
+ anc = ancestors.find{ |a| a.respond_to?(:parameterized) }
107
+ base.parameterized.concat(anc.parameterized)
108
+
109
+ super(base)
110
+ end
111
+
112
+ end
113
+
114
+ # An instance of the Mixin module class is what is produced
115
+ # when parameters are applied to a parametric module.
116
+ #
117
+ class Mixin < Module
118
+
119
+ def initialize(base, parameters)
120
+ super()
121
+ include(base)
122
+ base.parameterized.each do |code|
123
+ instance_exec(parameters, &code)
124
+ end
125
+ end
126
+
127
+ # As Module#public, and given a block, define the method first.
128
+ def public(*names, &code)
129
+ define_method(names.first, &code) if code
130
+ super(*names)
131
+ end
132
+
133
+ # As Module#private, and given a block, define the method first.
134
+ def private(*names, &code)
135
+ define_method(names.first, &code) if code
136
+ super(*names)
137
+ end
138
+
139
+ # As Module#protected, and given a block, define the method first.
140
+ def protected(*names, &code)
141
+ define_method(names.first, &code) if code
142
+ super(*names)
143
+ end
144
+
145
+ end
146
+
147
+ # The name this module had in the Paramix gem.
148
+ Parametric = self
149
+
150
+ end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: facets
3
3
  version: !ruby/object:Gem::Version
4
- version: 4.1.0
4
+ version: 4.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Thomas Sawyer
@@ -48,6 +48,7 @@ files:
48
48
  - lib/core/facets/array/entropy.rb
49
49
  - lib/core/facets/array/first.rb
50
50
  - lib/core/facets/array/from.rb
51
+ - lib/core/facets/array/from_base.rb
51
52
  - lib/core/facets/array/indexable.rb
52
53
  - lib/core/facets/array/indexes.rb
53
54
  - lib/core/facets/array/last.rb
@@ -259,6 +260,7 @@ files:
259
260
  - lib/core/facets/integer/of.rb
260
261
  - lib/core/facets/integer/ordinal.rb
261
262
  - lib/core/facets/integer/roman.rb
263
+ - lib/core/facets/integer/to_base.rb
262
264
  - lib/core/facets/kernel.rb
263
265
  - lib/core/facets/kernel/__class__.rb
264
266
  - lib/core/facets/kernel/__get__.rb
@@ -477,6 +479,7 @@ files:
477
479
  - lib/core/facets/string/expand_tab.rb
478
480
  - lib/core/facets/string/file.rb
479
481
  - lib/core/facets/string/fold.rb
482
+ - lib/core/facets/string/from_base.rb
480
483
  - lib/core/facets/string/indent.rb
481
484
  - lib/core/facets/string/index_all.rb
482
485
  - lib/core/facets/string/indexable.rb
@@ -486,6 +489,7 @@ files:
486
489
  - lib/core/facets/string/linear.rb
487
490
  - lib/core/facets/string/lowercase.rb
488
491
  - lib/core/facets/string/margin.rb
492
+ - lib/core/facets/string/mask.rb
489
493
  - lib/core/facets/string/methodize.rb
490
494
  - lib/core/facets/string/modulize.rb
491
495
  - lib/core/facets/string/mscan.rb
@@ -680,6 +684,7 @@ files:
680
684
  - lib/standard/facets/math/variance.rb
681
685
  - lib/standard/facets/memoizable.rb
682
686
  - lib/standard/facets/memoizer.rb
687
+ - lib/standard/facets/mirror.rb
683
688
  - lib/standard/facets/multipliers.rb
684
689
  - lib/standard/facets/multiton.rb
685
690
  - lib/standard/facets/net/http.rb
@@ -689,6 +694,7 @@ files:
689
694
  - lib/standard/facets/ostruct.rb
690
695
  - lib/standard/facets/ostruct/initialize.rb
691
696
  - lib/standard/facets/ostruct/to_ostruct.rb
697
+ - lib/standard/facets/paramix.rb
692
698
  - lib/standard/facets/pathname.rb
693
699
  - lib/standard/facets/pathname/chdir.rb
694
700
  - lib/standard/facets/pathname/empty.rb