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,115 @@
1
+ class Integer
2
+
3
+ # Converts the integer to a string in any base from 2 to 62, or
4
+ # with a custom set of digits.
5
+ #
6
+ # Ruby's own `to_s(base)` stops at base 36. Above that, the digits are
7
+ # 0-9, then a-z, then A-Z. Up to base 36, the result is the same as
8
+ # `to_s(base)`.
9
+ #
10
+ # 255.to_base(16) #=> "ff"
11
+ # 255.to_base(62) #=> "47"
12
+ # 809145531659995.to_base(62) #=> "3HLszsQsP"
13
+ # -255.to_base(62) #=> "-47"
14
+ #
15
+ # To use other digits, give them as a string, starting with the digit
16
+ # for zero. The number of digits is the base.
17
+ #
18
+ # 37.to_base("OLTWFS") #=> "LOL"
19
+ #
20
+ # In base 256 the digits are bytes, so the result is the number's
21
+ # bytes, most significant first, as a binary string.
22
+ #
23
+ # 256.to_base(256) #=> "\x01\x00"
24
+ # 0.to_base(256) #=> "\x00"
25
+ #
26
+ # Combining the two encodes binary data, as with Base58:
27
+ #
28
+ # b58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
29
+ # "hello".from_base(256).to_base(b58) #=> "Cn8eVZg"
30
+ # "Cn8eVZg".from_base(b58).to_base(256) #=> "hello"
31
+ #
32
+ # This goes through a number, so leading zero bytes are lost:
33
+ # "\x00hi" comes back as "hi". Formats such as Bitcoin's Base58 keep
34
+ # them with their own rules, which this doesn't follow.
35
+ #
36
+ # A negative number gets a leading "-", unless "-" is one of the
37
+ # digits, in which case it raises ArgumentError. That includes base
38
+ # 256, where "-" is byte 45.
39
+ #
40
+ # Given an array, the result is an array, with one element for each
41
+ # digit, most significant first. An array holding one number is a
42
+ # base, of any size from 2 up, and the result is the digit values:
43
+ #
44
+ # 1000.to_base([100]) #=> [10, 0]
45
+ # 256.to_base([256]) #=> [1, 0]
46
+ # 255.to_base([16]) #=> [15, 15]
47
+ #
48
+ # Any other array is the digits themselves, starting with the digit
49
+ # for zero. They can be any objects:
50
+ #
51
+ # 37.to_base(%w[O L T W F S]) #=> ["L", "O", "L"]
52
+ # 37.to_base(%w[O L T W F S]).join #=> "LOL"
53
+ # 5.to_base([:zero, :one]) #=> [:one, :zero, :one]
54
+ #
55
+ # An array can't show a sign, so a negative number raises
56
+ # ArgumentError.
57
+ #
58
+ # String#from_base converts a string back, and Array#from_base an
59
+ # array.
60
+ #
61
+ # Since: 4.2.0
62
+
63
+ def to_base(base)
64
+ case base
65
+ when ::Integer
66
+ if base == 256
67
+ if negative?
68
+ raise ArgumentError, "can't show a negative number in base 256, where '-' is a digit"
69
+ end
70
+ hex = to_s(16)
71
+ hex = "0#{hex}" if hex.size.odd?
72
+ return [hex].pack('H*')
73
+ end
74
+ unless base >= 2 && base <= 62
75
+ hint = base > 62 ? "; for digit values use to_base([#{base}])" : ""
76
+ raise ArgumentError, "invalid radix #{base}#{hint}"
77
+ end
78
+ return to_s(base) if base <= 36
79
+ digits = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"[0, base]
80
+ when ::String
81
+ digits = base.chars
82
+ if digits.size < 2
83
+ raise ArgumentError, "a base needs at least two digits"
84
+ end
85
+ if digits.uniq.size < digits.size
86
+ raise ArgumentError, "digits must not repeat"
87
+ end
88
+ if negative? && digits.include?('-')
89
+ raise ArgumentError, "can't show a negative number when '-' is a digit"
90
+ end
91
+ digits = base
92
+ when ::Array
93
+ if negative?
94
+ raise ArgumentError, "can't show a negative number as an array"
95
+ end
96
+ if base.size == 1 && base.first.is_a?(::Integer)
97
+ raise ArgumentError, "invalid radix #{base.first}" if base.first < 2
98
+ return digits(base.first).reverse
99
+ end
100
+ if base.size < 2
101
+ raise ArgumentError, "a base needs at least two digits"
102
+ end
103
+ if base.uniq.size < base.size
104
+ raise ArgumentError, "digits must not repeat"
105
+ end
106
+ return digits(base.size).reverse.map { |d| base[d] }
107
+ else
108
+ raise TypeError, "base must be an Integer, String or Array, not #{base.class}"
109
+ end
110
+
111
+ s = abs.digits(digits.size).reverse.map { |d| digits[d] }.join
112
+ negative? ? "-#{s}" : s
113
+ end
114
+
115
+ end
@@ -5,4 +5,5 @@ require_relative 'integer/multiple.rb'
5
5
  require_relative 'integer/of.rb'
6
6
  require_relative 'integer/ordinal.rb'
7
7
  #require_relative 'integer/roman.rb' # uncommon
8
+ require_relative 'integer/to_base.rb'
8
9
 
@@ -4,15 +4,15 @@ module Kernel
4
4
 
5
5
  # Very simple convenience method to get user input
6
6
  # via the console. A prompt will be sent to $stdout,
7
- # if given, and the input taken from $stdin...
7
+ # if given, and the input taken from $stdin:
8
8
  #
9
9
  # ask "Are you happy? [Yn]"
10
10
  #
11
- # On the command line one would see...
11
+ # On the command line one would see:
12
12
  #
13
13
  # Are you happy? [Yn]
14
14
  #
15
- # Responding...
15
+ # Responding:
16
16
  #
17
17
  # Are you happy? [Yn] Y <ENTER>
18
18
  #
@@ -2,11 +2,11 @@ module Kernel
2
2
  # An object is blank if it's nil, empty, or a whitespace string.
3
3
  # For example, "", " ", nil, [], and {} are blank.
4
4
  #
5
- # This simplifies...
5
+ # This simplifies:
6
6
  #
7
7
  # if !address.nil? && !address.empty?
8
8
  #
9
- # to...
9
+ # to:
10
10
  #
11
11
  # if !address.blank?
12
12
  #
@@ -25,13 +25,13 @@ module Kernel
25
25
  #
26
26
  # This is handy for any representation of objects where blank is the same
27
27
  # as not present at all. For example, this simplifies a common check for
28
- # HTTP POST/query parameters...
28
+ # HTTP POST/query parameters:
29
29
  #
30
30
  # state = params[:state] if params[:state].present?
31
31
  # country = params[:country] if params[:country].present?
32
32
  # region = state || country || 'US'
33
33
  #
34
- # becomes...
34
+ # becomes:
35
35
  #
36
36
  # region = params[:state].presence || params[:country].presence || 'US'
37
37
  #
@@ -5,11 +5,11 @@ module Kernel
5
5
 
6
6
  # Returns the call stack as an array of [file, lineno, method] entries.
7
7
  #
8
- # For example, from irb
8
+ # For example, from irb:
9
9
  #
10
10
  # callstack(1)
11
11
  #
12
- # _produces_ ...
12
+ # _produces_:
13
13
  #
14
14
  # [["(irb)", 2, :irb_binding], ...]
15
15
  #
@@ -1,12 +1,12 @@
1
1
  module Kernel
2
2
 
3
- # Like #p but gives file and line number...
3
+ # Like #p but gives file and line number:
4
4
  #
5
5
  # d("hi")
6
6
  #
7
- # produces ...
7
+ # produces:
8
8
  #
9
- # "hi" (/home/dave/projects/foo.rb, 38)
9
+ # ["hi"] /home/dave/projects/foo.rb:38:in '<main>'
10
10
  #
11
11
  def d(*x)
12
12
  puts "#{x.inspect} #{caller[0]}"
@@ -4,13 +4,13 @@ module Kernel
4
4
  # Preferably just a block and no string.
5
5
 
6
6
  # For debugging and showing examples. Currently this
7
- # takes an argument of a string in a block...
7
+ # takes an argument of a string in a block:
8
8
  #
9
9
  # demo {%{ a = [1,2,3] }}
10
10
  # demo {%{ a.slice(1,2) }}
11
11
  # demo {%{ a.map { |x| x**3 } }}
12
12
  #
13
- # produces ...
13
+ # produces:
14
14
  #
15
15
  # a = [1,2,3] #=> [1, 2, 3]
16
16
  # a.slice(1,2) #=> [2, 3]
@@ -4,7 +4,7 @@ module Kernel
4
4
 
5
5
  # Returns a Functor that intercepts method calls, forwards
6
6
  # them to self for side effects, and returns self. This is like
7
- # a block-less version of #tap that allows method chaining.
7
+ # a block-less version of #tap that allows method chaining:
8
8
  #
9
9
  # YAML.functor.load_file('foo.yml').load_file('bar.yml')
10
10
  #
@@ -6,9 +6,8 @@ module Kernel
6
6
  # @a #=> 1
7
7
  # @b #=> 2
8
8
  #
9
- # NOTE: Conceptually a better alternative to this method is `instance.update`
10
- # from the `instance` gem. However, practically this method is probably
11
- # the better choice until such time that Ruby supports anonymous delegators.
9
+ # `Mirror#update`, from `require 'facets/mirror'`, does the same
10
+ # through a mirror: `obj.mirror.update(a: 1)`.
12
11
  #
13
12
  def instance_assign(hash)
14
13
  hash.each do |k,v|
@@ -26,8 +26,8 @@ module Kernel
26
26
  # by the class of object, in the same manner as Array#replace.
27
27
  #
28
28
  # NOTE: Conceptually a better alternative is `instance.replace` provided
29
- # by the `instance` gem. However, practically this method is probably
30
- # the better choice until such time that Ruby support anonymous delegators.
29
+ # by the `instance` gem. However, practically this method is probably
30
+ # the better choice until such time that Ruby support anonymous delegators.
31
31
  #
32
32
  def instance_replace(source)
33
33
  raise ArgumentError, "not a #{self.class} -- #{source}" unless source.is_a?(self.class)
@@ -2,7 +2,7 @@ module Kernel
2
2
 
3
3
  # Random generator that returns true or false.
4
4
  # Can also take a block that has a 50/50 chance
5
- # to being executed...
5
+ # to being executed:
6
6
  #
7
7
  # maybe #=> true
8
8
  # maybe #=> false
@@ -2,7 +2,8 @@ module Kernel
2
2
 
3
3
  # Easy access to an object's singleton class, with optional block eval.
4
4
  #
5
- # obj.meta_class #=> #<Class:obj>
5
+ # obj = Object.new
6
+ # obj.meta_class #=> obj.singleton_class
6
7
  # obj.meta_class { def foo; end }
7
8
  #
8
9
  # This is a concise alternative to Ruby's `singleton_class` that also
@@ -16,9 +16,9 @@ module Kernel
16
16
  end
17
17
  end
18
18
 
19
- #def meta_def( name, &blk )
20
- # meta_eval { define_method name, &blk }
21
- #end
19
+ ##def meta_def( name, &blk )
20
+ ## meta_eval { define_method name, &blk }
21
+ ##end
22
22
 
23
23
  end
24
24
 
@@ -17,17 +17,12 @@ module Kernel
17
17
  end
18
18
 
19
19
  # Returns the object id as a string in hexideciaml,
20
- # which is how Ruby reports them with inspect...
20
+ # which is how Ruby reports them with inspect:
21
21
  #
22
- # "ABC".object_hexid #=> "0x402d359c"
22
+ # "ABC".object_hexid #=> "0x000000000006b0"
23
23
  #
24
24
  def object_hexid
25
25
  HEXID_TEMPLATE % (__id__ << 1)
26
26
  end
27
27
 
28
- # The 1.9.3 definition is as follows:
29
- #def object_hexid
30
- # "0x" + [object_id << 1].pack("L>!").unpack("H*")[0]
31
- #end
32
-
33
28
  end
@@ -8,9 +8,11 @@ module Kernel
8
8
  # exactly like a normal call (or &.): a method the receiver doesn't have,
9
9
  # or a private one, raises NoMethodError.
10
10
  #
11
+ # @example = Struct.new(:name).new("bob")
12
+ #
11
13
  # @example.try(:name) #=> "bob"
12
14
  # @example.try { |o| o.name } #=> "bob"
13
- # @example.try.name #=> "bob" (Functor form)
15
+ # @example.try.name #=> "bob"
14
16
  # nil.try.name #=> nil
15
17
  #
16
18
  # NOTE: THIS IS NOT ACTIVESUPPORT'S #try. SINCE RAILS 4.0, ACTIVESUPPORT'S
@@ -17,7 +17,7 @@ class Module
17
17
  # loaded automatically when using <code>require 'facets'</code>.
18
18
  #
19
19
  # @uncommon
20
- # require 'facets/module/attr_class_reader'
20
+ # require 'facets/module/attr_class_accessor'
21
21
  #
22
22
  def attr_class_reader(name)
23
23
  module_eval(<<-EOS, __FILE__, __LINE__)
@@ -35,7 +35,7 @@ class Module
35
35
  # loaded automatically when using <code>require 'facets'</code>.
36
36
  #
37
37
  # @uncommon
38
- # require 'facets/module/attr_class_writer'
38
+ # require 'facets/module/attr_class_accessor'
39
39
  #
40
40
  def attr_class_writer(name)
41
41
  module_eval(<<-EOS, __FILE__, __LINE__)
@@ -17,7 +17,7 @@ class Module
17
17
  # loaded automatically when using <code>require 'facets'</code>.
18
18
  #
19
19
  # @uncommon
20
- # require 'facets/module/class_reader'
20
+ # require 'facets/module/class_accessor'
21
21
  #
22
22
  def class_reader(name)
23
23
  module_eval(<<-EOS, __FILE__, __LINE__)
@@ -32,7 +32,7 @@ class Module
32
32
  # loaded automatically when using <code>require 'facets'</code>.
33
33
  #
34
34
  # @uncommon
35
- # require 'facets/module/class_writer'
35
+ # require 'facets/module/class_accessor'
36
36
  #
37
37
  def class_writer(name)
38
38
  module_eval(<<-EOS, __FILE__, __LINE__)
@@ -3,7 +3,7 @@ $FIRST_CLASS_INSTANCE_METHODS = Hash.new{ |h,k| h[k] = {} }
3
3
  #
4
4
  class Module
5
5
 
6
- # Access method as a singleton object and retain state.
6
+ # Access method as a singleton object and retain state:
7
7
  #
8
8
  # module ::K
9
9
  # def hello
@@ -11,7 +11,7 @@ class Module
11
11
  # end
12
12
  # end
13
13
  #
14
- # K.instance_method!(:hello).inspect #=> "#<UnboundMethod: K#hello>"
14
+ # K.instance_method!(:hello).inspect #=> "#<UnboundMethod: K#hello() ...>"
15
15
  #
16
16
  # NOTE: This is limited to the scope of the current module/class.
17
17
 
@@ -41,7 +41,7 @@ class Module
41
41
  # Expirmental idea for #is.
42
42
  #
43
43
  # If the module has #append_feature_function
44
- # defined, this will use that instead of #include ...
44
+ # defined, this will use that instead of #include:
45
45
  #
46
46
  # def is(*modules)
47
47
  # module.each do { |m|
@@ -9,7 +9,7 @@ class Numeric
9
9
  # * <tt>separator</tt> - defaults to "." but can be any string
10
10
  #
11
11
  # 1000.delimit(:delimiter => "_") # => "1_000"
12
- # (1000.00).delimit(:delimiter => ".", :separator => ",") # => "1.000,00"
12
+ # (1000.00).delimit(:delimiter => ".", :separator => ",") # => "1.000,0"
13
13
  def delimit(options = {})
14
14
  opts = { :delimiter => ',', :separator => '.' }.merge(options)
15
15
  digits, decimals = self.to_s.split('.')
@@ -4,7 +4,7 @@ class Proc
4
4
  # already a Proc object.
5
5
  #
6
6
  # TODO: Would this make more sense as `Kernel#Proc()` method,
7
- # akin to `Integer()` and the like?
7
+ # akin to `Integer()` and the like?
8
8
  #
9
9
  # Returns [Proc]
10
10
  #
@@ -4,9 +4,9 @@ class Range
4
4
  #
5
5
  # Examples
6
6
  #
7
- # (1..10) - (4..6) => [1..3, 7..10]
7
+ # ((1..10) - (4..6)) #=> [1..3, 7..10]
8
8
  #
9
- # (1..10) - (9..12) => [1..8]
9
+ # ((1..10) - (9..12)) #=> [1..8]
10
10
  #
11
11
  # Returns [Array]
12
12
  #
@@ -19,7 +19,7 @@ class Range
19
19
  # Returns a two element array of the relationship
20
20
  # between two Ranges.
21
21
  #
22
- # Diagram ...
22
+ # Diagram:
23
23
  #
24
24
  # Relationship Returns
25
25
  #
@@ -2,7 +2,7 @@ class Regexp
2
2
 
3
3
  # Operator form of `Regexp.union`.
4
4
  #
5
- # /a/ | /b/ #=> /(?-mix:a)|(?-mix:b)/
5
+ # (/a/ | /b/) #=> /(?-mix:a)|(?-mix:b)/
6
6
  #
7
7
  # If +other+ is not a Regexp it is passed to Regexp.escape.
8
8
  #
@@ -11,7 +11,7 @@ class String
11
11
  #
12
12
  # s.align(:right, 14)
13
13
  #
14
- # _produces_ ...
14
+ # _produces_:
15
15
  #
16
16
  # This is a test
17
17
  # and
@@ -45,7 +45,7 @@ class String
45
45
  #
46
46
  # s.align_right(14)
47
47
  #
48
- # _produces_ ...
48
+ # _produces_:
49
49
  #
50
50
  # This is a test
51
51
  # and
@@ -75,7 +75,7 @@ class String
75
75
  #
76
76
  # s.align_left(20, "\n", '.')
77
77
  #
78
- # _produces_ ...
78
+ # _produces_:
79
79
  #
80
80
  # This is a test......
81
81
  # and.................
@@ -105,7 +105,7 @@ class String
105
105
  #
106
106
  # s.align_center(14)
107
107
  #
108
- # _produces_ ...
108
+ # _produces_:
109
109
  #
110
110
  # This is a test
111
111
  # and
@@ -2,7 +2,7 @@ class String
2
2
  # Get a new string with non-ASCII characters removed.
3
3
  #
4
4
  # alt - String to replace non-ASCII characters with.
5
- # Defaults to a blank string (`''`).
5
+ # Defaults to a blank string (`''`).
6
6
  #
7
7
  # Examples
8
8
  #
@@ -27,7 +27,7 @@ class String
27
27
  # Modify string keeping only ASCII characters.
28
28
  #
29
29
  # alt - String to replace non-ASCII characters with.
30
- # Defaults to a blank string (`''`).
30
+ # Defaults to a blank string (`''`).
31
31
  #
32
32
  # Examples
33
33
  #
@@ -14,7 +14,7 @@ class String
14
14
  gsub(/([a-z\d])([A-Z])/,'\1_\2').
15
15
  tr('_', '-').
16
16
  gsub(/\s/, '-').
17
- gsub(/__+/, '-').
17
+ gsub(/--+/, '-').
18
18
  downcase
19
19
  end
20
20
 
@@ -6,7 +6,7 @@ class String
6
6
 
7
7
  # Use fluent notation for making file directives.
8
8
  #
9
- # For instance, if we had a file 'foo.txt',
9
+ # For instance, if we had a file 'foo.txt':
10
10
  #
11
11
  # 'foo.txt'.file.mtime
12
12
  #
@@ -0,0 +1,85 @@
1
+ class String
2
+
3
+ # Reads the string as a number in any base from 2 to 62, or with a
4
+ # custom set of digits, and returns it as an Integer.
5
+ #
6
+ # Ruby's own `to_i(base)` stops at base 36. Above that, the digits are
7
+ # 0-9, then a-z, then A-Z. Up to base 36, case doesn't matter, as with
8
+ # `to_i(base)`.
9
+ #
10
+ # "ff".from_base(16) #=> 255
11
+ # "FF".from_base(16) #=> 255
12
+ # "47".from_base(62) #=> 255
13
+ # "3HLszsQsP".from_base(62) #=> 809145531659995
14
+ # "-47".from_base(62) #=> -255
15
+ #
16
+ # To use other digits, give them as a string or an array of
17
+ # single characters, starting with the digit for zero.
18
+ #
19
+ # "LOL".from_base("OLTWFS") #=> 37
20
+ # "LOL".from_base(%w[O L T W F S]) #=> 37
21
+ #
22
+ # In base 256 the digits are bytes, so this reads the string's bytes,
23
+ # most significant first, whatever its encoding.
24
+ #
25
+ # "\x01\x00".from_base(256) #=> 256
26
+ #
27
+ # Unlike `to_i`, which stops at the first character it can't read,
28
+ # this raises ArgumentError for a character that isn't a digit of the
29
+ # base, and for an empty string. A leading "-" makes the number
30
+ # negative, unless "-" is one of the digits, as it is in base 256.
31
+ #
32
+ # Integer#to_base converts back. Given an array of digits, it gives
33
+ # an array, which Array#from_base reads.
34
+ #
35
+ # Since: 4.2.0
36
+
37
+ def from_base(base)
38
+ case base
39
+ when ::Integer
40
+ if base == 256
41
+ raise ArgumentError, "no digits in #{inspect}" if empty?
42
+ return unpack1('H*').to_i(16)
43
+ end
44
+ unless base >= 2 && base <= 62
45
+ raise ArgumentError, "invalid radix #{base}"
46
+ end
47
+ digits = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"[0, base].chars
48
+ ignore_case = base <= 36
49
+ when ::String, ::Array
50
+ digits = base.is_a?(::Array) ? base.map(&:to_s) : base.chars
51
+ unless digits.all? { |d| d.length == 1 }
52
+ raise ArgumentError, "digits must be single characters"
53
+ end
54
+ if digits.size < 2
55
+ raise ArgumentError, "a base needs at least two digits"
56
+ end
57
+ if digits.uniq.size < digits.size
58
+ raise ArgumentError, "digits must not repeat"
59
+ end
60
+ ignore_case = false
61
+ else
62
+ raise TypeError, "base must be an Integer, String or Array, not #{base.class}"
63
+ end
64
+
65
+ values = {}
66
+ digits.each_with_index do |d, i|
67
+ values[d] = i
68
+ values[d.upcase] = i if ignore_case
69
+ end
70
+
71
+ str = self
72
+ negative = str.start_with?('-') && !values.key?('-')
73
+ str = str[1..-1] if negative
74
+ raise ArgumentError, "no digits in #{inspect}" if str.empty?
75
+
76
+ n = 0
77
+ str.each_char do |c|
78
+ v = values[c]
79
+ raise ArgumentError, "invalid digit #{c.inspect} in #{inspect}" unless v
80
+ n = n * digits.size + v
81
+ end
82
+ negative ? -n : n
83
+ end
84
+
85
+ end
@@ -54,11 +54,11 @@ class String
54
54
  #
55
55
  # Examples
56
56
  #
57
- # <<-END.unindent
57
+ # text = <<-END.unindent
58
58
  # ohaie
59
59
  # wurld
60
- # END
61
- # #=> "ohaie\n wurld"
60
+ # END
61
+ # text #=> "ohaie\n wurld\n"
62
62
  #
63
63
  # Returns a new unindented string. [String]
64
64
  #
@@ -14,15 +14,27 @@ class String
14
14
  # by the first non-blank line, instead of the minimum white-space for all
15
15
  # lines.
16
16
  #
17
- # Arguments
17
+ # " abc\n xyz".margin(0) #=> "abc\n xyz"
18
+ # " abc\n xyz".margin(2, lead: true) #=> " abc\nxyz"
19
+ #
20
+ # If the `:flush` option is set, relative tabbing is not preserved: every
21
+ # line that isn't blank gets exactly the given number of spaces before
22
+ # non-space, whatever spaces or tabs it started with. Blank lines are
23
+ # left as they are.
24
+ #
25
+ # "abc\n xyz".margin(2) #=> " abc\n xyz"
26
+ # "abc\n xyz".margin(2, flush: true) #=> " abc\n xyz"
27
+ #
28
+ # Arguments:
18
29
  #
19
30
  # num - The size of the desired margin. [Integer]
20
31
  # opts - Margin options. [Hash]
21
32
  #
22
- # Options
33
+ # Options:
23
34
  #
24
- # :tab - Size of tab character in spaces. [Integer]
25
- # :lead - Use first non-blank line as relative marker. [Boolean]
35
+ # :tab - Size of tab character in spaces. [Integer]
36
+ # :lead - Use first non-blank line as relative marker. [Boolean]
37
+ # :flush - Give every line the same margin. [Boolean]
26
38
  #
27
39
  # Returns a new String with adjusted margin. [String]
28
40
  #
@@ -33,6 +45,8 @@ class String
33
45
  # TODO: temporary to help people transition
34
46
  raise ArgumentError, "String#margin has been renamed to #trim." unless num
35
47
 
48
+ return gsub(/^[ \t]*(?=\S)/, ' ' * num) if opts[:flush]
49
+
36
50
  tab = opts[:tab] || 2
37
51
  str = gsub("\t", " " * tab) # TODO: only leading tabs ?
38
52