xqsr3 0.38.2 → 0.39.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (111) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +15 -6
  3. data/examples/count_word_frequencies.md +12 -12
  4. data/examples/count_word_frequencies.rb +4 -4
  5. data/lib/xqsr3/array_utilities/join_with_or.rb +47 -47
  6. data/lib/xqsr3/array_utilities.rb +2 -2
  7. data/lib/xqsr3/command_line_utilities/map_option_string.rb +60 -60
  8. data/lib/xqsr3/command_line_utilities.rb +2 -2
  9. data/lib/xqsr3/containers/frequency_map.rb +399 -399
  10. data/lib/xqsr3/containers/multi_map.rb +448 -448
  11. data/lib/xqsr3/containers.rb +3 -3
  12. data/lib/xqsr3/conversion/bool_parser.rb +51 -51
  13. data/lib/xqsr3/conversion/integer_parser.rb +87 -87
  14. data/lib/xqsr3/conversion.rb +3 -3
  15. data/lib/xqsr3/diagnostics/exception_utilities.rb +145 -145
  16. data/lib/xqsr3/diagnostics/exceptions/with_cause.rb +90 -90
  17. data/lib/xqsr3/diagnostics/inspect_builder.rb +80 -80
  18. data/lib/xqsr3/diagnostics.rb +3 -3
  19. data/lib/xqsr3/doc_.rb +130 -130
  20. data/lib/xqsr3/extensions/array/join_with_or.rb +9 -9
  21. data/lib/xqsr3/extensions/enumerable/collect_with_index.rb +12 -12
  22. data/lib/xqsr3/extensions/enumerable/detect_map.rb +35 -35
  23. data/lib/xqsr3/extensions/enumerable/unique.rb +29 -28
  24. data/lib/xqsr3/extensions/hash/deep_transform.rb +1 -1
  25. data/lib/xqsr3/extensions/hash/except.rb +16 -16
  26. data/lib/xqsr3/extensions/hash/has_match.rb +10 -10
  27. data/lib/xqsr3/extensions/hash/match.rb +10 -10
  28. data/lib/xqsr3/extensions/hash/slice.rb +11 -11
  29. data/lib/xqsr3/extensions/hash.rb +1 -1
  30. data/lib/xqsr3/extensions/integer/to_s_grp.rb +118 -0
  31. data/lib/xqsr3/extensions/integer.rb +3 -0
  32. data/lib/xqsr3/extensions/io/writelines.rb +28 -28
  33. data/lib/xqsr3/extensions/kernel/integer.rb +20 -20
  34. data/lib/xqsr3/extensions/kernel/raise_with_options.rb +8 -8
  35. data/lib/xqsr3/extensions/kernel.rb +1 -0
  36. data/lib/xqsr3/extensions/string/ends_with.rb +1 -1
  37. data/lib/xqsr3/extensions/string/map_option_string.rb +4 -4
  38. data/lib/xqsr3/extensions/string/nil_if_empty.rb +1 -1
  39. data/lib/xqsr3/extensions/string/nil_if_whitespace.rb +1 -1
  40. data/lib/xqsr3/extensions/string/quote_if.rb +1 -1
  41. data/lib/xqsr3/extensions/string/starts_with.rb +1 -1
  42. data/lib/xqsr3/extensions/string/to_bool.rb +8 -8
  43. data/lib/xqsr3/extensions/string/to_symbol.rb +1 -1
  44. data/lib/xqsr3/extensions/string/truncate.rb +1 -1
  45. data/lib/xqsr3/extensions/test/unit/assert_eql.rb +7 -7
  46. data/lib/xqsr3/extensions/test/unit/assert_false.rb +6 -6
  47. data/lib/xqsr3/extensions/test/unit/assert_not.rb +6 -6
  48. data/lib/xqsr3/extensions/test/unit/assert_not_eql.rb +7 -7
  49. data/lib/xqsr3/extensions/test/unit/assert_raise_with_message.rb +61 -61
  50. data/lib/xqsr3/extensions/test/unit/assert_subclass_of.rb +7 -7
  51. data/lib/xqsr3/extensions/test/unit/assert_superclass_of.rb +7 -7
  52. data/lib/xqsr3/extensions/test/unit/assert_true.rb +6 -6
  53. data/lib/xqsr3/extensions/test/unit/assert_type_has_instance_methods.rb +36 -36
  54. data/lib/xqsr3/extensions.rb +5 -5
  55. data/lib/xqsr3/hash_utilities/deep_transform.rb +65 -65
  56. data/lib/xqsr3/hash_utilities/key_matching.rb +77 -77
  57. data/lib/xqsr3/hash_utilities.rb +3 -3
  58. data/lib/xqsr3/internal_/test_unit_version_.rb +85 -85
  59. data/lib/xqsr3/io/writelines.rb +119 -119
  60. data/lib/xqsr3/quality/parameter_checking.rb +445 -445
  61. data/lib/xqsr3/quality.rb +2 -2
  62. data/lib/xqsr3/string_utilities/ends_with.rb +59 -59
  63. data/lib/xqsr3/string_utilities/nil_if_empty.rb +28 -28
  64. data/lib/xqsr3/string_utilities/nil_if_whitespace.rb +29 -29
  65. data/lib/xqsr3/string_utilities/quote_if.rb +50 -50
  66. data/lib/xqsr3/string_utilities/starts_with.rb +59 -59
  67. data/lib/xqsr3/string_utilities/to_symbol.rb +75 -75
  68. data/lib/xqsr3/string_utilities/truncate.rb +55 -55
  69. data/lib/xqsr3/string_utilities.rb +8 -8
  70. data/lib/xqsr3/version.rb +12 -12
  71. data/test/performance/frequency_map.rb +12 -12
  72. data/test/scratch/test_assert_raise_with_message.rb +11 -11
  73. data/test/unit/array_utilities/tc_join_with_or.rb +140 -140
  74. data/test/unit/command_line_utilities/tc_map_option_string.rb +18 -18
  75. data/test/unit/containers/tc_frequency_map.rb +591 -591
  76. data/test/unit/containers/tc_multi_map.rb +558 -558
  77. data/test/unit/conversion/tc_integer_parser.rb +72 -72
  78. data/test/unit/conversion/tc_to_bool.rb +25 -25
  79. data/test/unit/diagnostics/exceptions/tc_with_cause.rb +165 -165
  80. data/test/unit/diagnostics/tc_exception_utilities.rb +156 -156
  81. data/test/unit/extensions/enumerable/tc_collect_with_index.rb +14 -14
  82. data/test/unit/extensions/enumerable/tc_detect_map.rb +20 -20
  83. data/test/unit/extensions/enumerable/tc_unique.rb +34 -34
  84. data/test/unit/extensions/hash/tc_deep_transform.rb +22 -22
  85. data/test/unit/extensions/hash/tc_except.rb +28 -28
  86. data/test/unit/extensions/hash/tc_slice.rb +13 -13
  87. data/test/unit/extensions/integer/tc_to_s_grp.rb +60 -0
  88. data/test/unit/extensions/integer/ts_all.rb +12 -0
  89. data/test/unit/extensions/io/tc_writelines.rb +77 -77
  90. data/test/unit/extensions/kernel/tc_integer.rb +75 -75
  91. data/test/unit/extensions/kernel/tc_raise_with_options.rb +155 -155
  92. data/test/unit/extensions/object/tc_inspect.rb +50 -50
  93. data/test/unit/extensions/string/tc_bool.tb +24 -24
  94. data/test/unit/extensions/string/tc_ends_with.rb +53 -53
  95. data/test/unit/extensions/string/tc_map_option_string.rb +15 -15
  96. data/test/unit/extensions/string/tc_nil_if_empty.rb +8 -8
  97. data/test/unit/extensions/string/tc_nil_if_whitespace.rb +8 -8
  98. data/test/unit/extensions/string/tc_quote_if.rb +18 -18
  99. data/test/unit/extensions/string/tc_starts_with.rb +53 -53
  100. data/test/unit/extensions/string/tc_to_symbol.rb +26 -26
  101. data/test/unit/extensions/string/tc_truncate.rb +18 -18
  102. data/test/unit/extensions/test/unit/tc_assert_raise_with_message.rb +16 -16
  103. data/test/unit/extensions/test/unit/tc_assert_subclass_of.rb +9 -9
  104. data/test/unit/extensions/test/unit/tc_assert_superclass_of.rb +9 -9
  105. data/test/unit/hash_utilities/tc_has_match.rb +70 -70
  106. data/test/unit/hash_utilities/tc_match.rb +83 -83
  107. data/test/unit/io/tc_writelines.rb +106 -106
  108. data/test/unit/quality/tc_parameter_checking.rb +389 -389
  109. data/test/unit/string_utilities/tc_truncate.rb +27 -27
  110. data/test/unit/tc_version.rb +15 -15
  111. metadata +6 -2
@@ -1,11 +1,11 @@
1
1
 
2
2
  %w{
3
3
 
4
- frequency_map
5
- multi_map
4
+ frequency_map
5
+ multi_map
6
6
  }.each do |name|
7
7
 
8
- require File.join(File.dirname(__FILE__), 'containers', name)
8
+ require File.join(File.dirname(__FILE__), 'containers', name)
9
9
  end
10
10
 
11
11
 
@@ -2,16 +2,16 @@
2
2
  # ######################################################################## #
3
3
  # File: lib/xqsr3/conversion/bool_parser.rb
4
4
  #
5
- # Purpose: Definition of the Xqsr3::Conversion::BoolParser module
5
+ # Purpose: Definition of the ::Xqsr3::Conversion::BoolParser module
6
6
  #
7
7
  # Created: 3rd June 2017
8
- # Updated: 11th December 2023
8
+ # Updated: 29th March 2024
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/xqsr3
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
- # Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
14
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
15
15
  # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
16
16
  # All rights reserved.
17
17
  #
@@ -57,54 +57,54 @@ module Conversion
57
57
  # +include-able module that provides Boolean parsing
58
58
  module BoolParser
59
59
 
60
- private
61
- def self.matches_to_ s, expr
62
-
63
- case expr
64
- when ::Regexp
65
- return expr =~ s
66
- else
67
- return s == expr
68
- end
69
- end
70
-
71
- public
72
-
73
- # Recognised truey values
74
- DEFAULT_TRUE_VALUES = [ /true/i, '1' ]
75
- # Recognised falsey values
76
- DEFAULT_FALSE_VALUES = [ /false/i, '0' ]
77
-
78
- # Attempts to parse the given string +s+ to a Boolean value, based on the
79
- # given +options+
80
- #
81
- # === Signature
82
- #
83
- # * *Parameters:*
84
- # - +s+ The string to be parsed
85
- # - +options+ An options hash, containing any of the following options
86
- #
87
- # * *Options:*
88
- # - +:false_values+ (::Array) An array of strings or regular expressions against which to match for false value. Defaults to +DEFAULT_FALSE_VALUES+
89
- # - +:true_values+ (::Array) An array of strings or regular expressions against which to match for true value. Defaults to +DEFAULT_TRUE_VALUES+
90
- # - +:default_value+ An object to be returned if matching fails. Defaults to +nil+
91
- # - +:false_value+ An object to be returned if matching succeeds to match against +:false_values+. Defaults to +false+
92
- # - +:true_value+ An object to be returned if matching succeeds to match against +:true_values+. Defaults to +true+
93
- def self.to_bool s, **options
94
-
95
- true_values = options[:true_values] || DEFAULT_TRUE_VALUES
96
- true_values = [ true_values ] unless true_values.is_a? ::Array
97
- false_values = options[:false_values] || DEFAULT_FALSE_VALUES
98
- false_values = [ false_values ] unless false_values.is_a? ::Array
99
- default_value = options[:default] || nil
100
- true_value = options[:true] || true
101
- false_value = options[:false] || false
102
-
103
- return true_value if true_values.any? { |v| self.matches_to_ s, v }
104
- return false_value if false_values.any? { |v| self.matches_to_ s, v }
105
-
106
- return default_value
107
- end
60
+ private
61
+ def self.matches_to_ s, expr
62
+
63
+ case expr
64
+ when ::Regexp
65
+ return expr =~ s
66
+ else
67
+ return s == expr
68
+ end
69
+ end
70
+
71
+ public
72
+
73
+ # Recognised truey values
74
+ DEFAULT_TRUE_VALUES = [ /true/i, '1' ]
75
+ # Recognised falsey values
76
+ DEFAULT_FALSE_VALUES = [ /false/i, '0' ]
77
+
78
+ # Attempts to parse the given string +s+ to a Boolean value, based on the
79
+ # given +options+
80
+ #
81
+ # === Signature
82
+ #
83
+ # * *Parameters:*
84
+ # - +s+ The string to be parsed
85
+ # - +options+ An options hash, containing any of the following options
86
+ #
87
+ # * *Options:*
88
+ # - +:false_values+ (::Array) An array of strings or regular expressions against which to match for false value. Defaults to +DEFAULT_FALSE_VALUES+
89
+ # - +:true_values+ (::Array) An array of strings or regular expressions against which to match for true value. Defaults to +DEFAULT_TRUE_VALUES+
90
+ # - +:default_value+ An object to be returned if matching fails. Defaults to +nil+
91
+ # - +:false_value+ An object to be returned if matching succeeds to match against +:false_values+. Defaults to +false+
92
+ # - +:true_value+ An object to be returned if matching succeeds to match against +:true_values+. Defaults to +true+
93
+ def self.to_bool s, **options
94
+
95
+ true_values = options[:true_values] || DEFAULT_TRUE_VALUES
96
+ true_values = [ true_values ] unless true_values.is_a? ::Array
97
+ false_values = options[:false_values] || DEFAULT_FALSE_VALUES
98
+ false_values = [ false_values ] unless false_values.is_a? ::Array
99
+ default_value = options[:default] || nil
100
+ true_value = options[:true] || true
101
+ false_value = options[:false] || false
102
+
103
+ return true_value if true_values.any? { |v| self.matches_to_ s, v }
104
+ return false_value if false_values.any? { |v| self.matches_to_ s, v }
105
+
106
+ return default_value
107
+ end
108
108
 
109
109
  end # module BoolParser
110
110
 
@@ -2,16 +2,16 @@
2
2
  # ######################################################################## #
3
3
  # File: lib/xqsr3/conversion/integer_parser.rb
4
4
  #
5
- # Purpose: Definition of the Xqsr3::Conversion::IntegerParser module
5
+ # Purpose: Definition of the ::Xqsr3::Conversion::IntegerParser module
6
6
  #
7
7
  # Created: 21st November 2017
8
- # Updated: 11th December 2023
8
+ # Updated: 29th March 2024
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/xqsr3
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
- # Copyright (c) 2019-2023, Matthew Wilson and Synesis Information Systems
14
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
15
15
  # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
16
16
  # All rights reserved.
17
17
  #
@@ -57,125 +57,125 @@ module Conversion
57
57
  # +include-able module that provides Integer parsing
58
58
  module IntegerParser
59
59
 
60
- private
61
- # @!visibility private
62
- module IntegerParser_Helper_ # :nodoc: all
60
+ private
61
+ # @!visibility private
62
+ module IntegerParser_Helper_ # :nodoc: all
63
63
 
64
- if Kernel.respond_to?(:xqsr3_Integer_original_method)
64
+ if Kernel.respond_to?(:xqsr3_Integer_original_method)
65
65
 
66
- def self.invoke_Integer_1(arg)
66
+ def self.invoke_Integer_1(arg)
67
67
 
68
- Kernel.xqsr3_Integer_original_method(arg)
69
- end
68
+ Kernel.xqsr3_Integer_original_method(arg)
69
+ end
70
70
 
71
- def self.invoke_Integer_2(arg, base)
71
+ def self.invoke_Integer_2(arg, base)
72
72
 
73
- Kernel.xqsr3_Integer_original_method(arg, base)
74
- end
75
- else
73
+ Kernel.xqsr3_Integer_original_method(arg, base)
74
+ end
75
+ else
76
76
 
77
- def self.invoke_Integer_1(arg)
77
+ def self.invoke_Integer_1(arg)
78
78
 
79
- Kernel.Integer(arg)
80
- end
79
+ Kernel.Integer(arg)
80
+ end
81
81
 
82
- def self.invoke_Integer_2(arg, base)
82
+ def self.invoke_Integer_2(arg, base)
83
83
 
84
- Kernel.Integer(arg, base)
85
- end
86
- end
84
+ Kernel.Integer(arg, base)
85
+ end
86
+ end
87
87
 
88
- def self.invoke_Integer(arg, base)
88
+ def self.invoke_Integer(arg, base)
89
89
 
90
- case arg
91
- when ::String
90
+ case arg
91
+ when ::String
92
92
 
93
- self.invoke_Integer_2 arg, base
94
- else
93
+ self.invoke_Integer_2 arg, base
94
+ else
95
95
 
96
- if $DEBUG
96
+ if $DEBUG
97
97
 
98
- case base
99
- when nil, 0
98
+ case base
99
+ when nil, 0
100
100
 
101
- ;
102
- else
101
+ ;
102
+ else
103
103
 
104
- warn "WARNING: #{self}::#{__method__}: " + 'base specified for non string value'
105
- end
106
- end
104
+ warn "WARNING: #{self}::#{__method__}: " + 'base specified for non string value'
105
+ end
106
+ end
107
107
 
108
- self.invoke_Integer_1 arg
109
- end
110
- end
108
+ self.invoke_Integer_1 arg
109
+ end
110
+ end
111
111
 
112
- def self.to_integer_ arg, base, options, &block
112
+ def self.to_integer_ arg, base, options, &block
113
113
 
114
- case options
115
- when ::Hash
116
- ;
117
- else
114
+ case options
115
+ when ::Hash
116
+ ;
117
+ else
118
118
 
119
- raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
120
- end
119
+ raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
120
+ end
121
121
 
122
- if block_given?
122
+ if block_given?
123
123
 
124
- begin
124
+ begin
125
125
 
126
- return self.invoke_Integer arg, base
127
- rescue ArgumentError, TypeError => x
126
+ return self.invoke_Integer arg, base
127
+ rescue ArgumentError, TypeError => x
128
128
 
129
- return yield x, arg, base, options
130
- end
131
- end
129
+ return yield x, arg, base, options
130
+ end
131
+ end
132
132
 
133
- if options.has_key?(:default) || options[:nil]
133
+ if options.has_key?(:default) || options[:nil]
134
134
 
135
- unless arg.nil?
135
+ unless arg.nil?
136
136
 
137
- begin
137
+ begin
138
138
 
139
- return self.invoke_Integer arg, base
140
- rescue ArgumentError, TypeError
141
- end
142
- end
139
+ return self.invoke_Integer arg, base
140
+ rescue ArgumentError, TypeError
141
+ end
142
+ end
143
143
 
144
- return options[:default] if options.has_key? :default
144
+ return options[:default] if options.has_key? :default
145
145
 
146
- return nil
147
- else
146
+ return nil
147
+ else
148
148
 
149
- self.invoke_Integer arg, base
150
- end
151
- end
152
- end # module IntegerParser_Helper_
153
- public
149
+ self.invoke_Integer arg, base
150
+ end
151
+ end
152
+ end # module IntegerParser_Helper_
153
+ public
154
154
 
155
- # Attempts to convert a variable to an integer, according to the given
156
- # options and block
157
- #
158
- # === Signature
159
- #
160
- # * *Parameters:*
161
- # - +arg+ The argument to be converted (to +Fixnum+ or +Bignum+)
162
- # - +base+ A value of 0, or between 2 and 36. Defaults to 0
163
- # - +options+ An options hash, containing any of the following options
164
- # - +block+ An optional caller-supplied 4-parameter block - taking the exception, +arg+, +base+, and +options+ - that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
165
- #
166
- # * *Options:*
167
- # - +:default+ A default value to be used when +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+
168
- # - +:nil+ Returns +nil+ if +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
169
- def self.to_integer arg, base = 0, **options, &block
155
+ # Attempts to convert a variable to an integer, according to the given
156
+ # options and block
157
+ #
158
+ # === Signature
159
+ #
160
+ # * *Parameters:*
161
+ # - +arg+ The argument to be converted (to +Fixnum+ or +Bignum+)
162
+ # - +base+ A value of 0, or between 2 and 36. Defaults to 0
163
+ # - +options+ An options hash, containing any of the following options
164
+ # - +block+ An optional caller-supplied 4-parameter block - taking the exception, +arg+, +base+, and +options+ - that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
165
+ #
166
+ # * *Options:*
167
+ # - +:default+ A default value to be used when +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+
168
+ # - +:nil+ Returns +nil+ if +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
169
+ def self.to_integer arg, base = 0, **options, &block
170
170
 
171
- IntegerParser_Helper_.to_integer_ arg, base, options, &block
172
- end
171
+ IntegerParser_Helper_.to_integer_ arg, base, options, &block
172
+ end
173
173
 
174
- # Instance form of ::Xqsr3::Conversion::IntegerParser.to_integer
175
- def to_integer base = 0, **options, &block
174
+ # Instance form of ::Xqsr3::Conversion::IntegerParser.to_integer
175
+ def to_integer base = 0, **options, &block
176
176
 
177
- IntegerParser_Helper_.to_integer_ self, base, options, &block
178
- end
177
+ IntegerParser_Helper_.to_integer_ self, base, options, &block
178
+ end
179
179
 
180
180
  end # module IntegerParser
181
181
 
@@ -1,11 +1,11 @@
1
1
 
2
2
  %w{
3
3
 
4
- bool_parser
5
- integer_parser
4
+ bool_parser
5
+ integer_parser
6
6
  }.each do |name|
7
7
 
8
- require File.join(File.dirname(__FILE__), 'conversion', name)
8
+ require File.join(File.dirname(__FILE__), 'conversion', name)
9
9
  end
10
10
 
11
11