xqsr3 0.32.2 → 0.36.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 (59) hide show
  1. checksums.yaml +5 -5
  2. data/lib/xqsr3/all_extensions.rb +6 -0
  3. data/lib/xqsr3/array_utilities.rb +10 -0
  4. data/lib/xqsr3/array_utilities/join_with_or.rb +7 -14
  5. data/lib/xqsr3/command_line_utilities.rb +10 -0
  6. data/lib/xqsr3/command_line_utilities/map_option_string.rb +21 -8
  7. data/lib/xqsr3/containers.rb +11 -0
  8. data/lib/xqsr3/containers/frequency_map.rb +19 -2
  9. data/lib/xqsr3/containers/multi_map.rb +316 -27
  10. data/lib/xqsr3/conversion.rb +11 -0
  11. data/lib/xqsr3/conversion/bool_parser.rb +11 -14
  12. data/lib/xqsr3/conversion/integer_parser.rb +10 -16
  13. data/lib/xqsr3/diagnostics.rb +11 -0
  14. data/lib/xqsr3/diagnostics/exception_utilities.rb +2 -2
  15. data/lib/xqsr3/diagnostics/exceptions/with_cause.rb +15 -7
  16. data/lib/xqsr3/diagnostics/inspect_builder.rb +16 -16
  17. data/lib/xqsr3/doc_.rb +138 -9
  18. data/lib/xqsr3/extensions.rb +13 -0
  19. data/lib/xqsr3/extensions/array.rb +3 -0
  20. data/lib/xqsr3/extensions/array/join_with_or.rb +6 -0
  21. data/lib/xqsr3/extensions/enumerable/collect_with_index.rb +5 -4
  22. data/lib/xqsr3/extensions/enumerable/detect_map.rb +6 -7
  23. data/lib/xqsr3/extensions/hash.rb +5 -0
  24. data/lib/xqsr3/extensions/hash/has_match.rb +7 -0
  25. data/lib/xqsr3/extensions/hash/match.rb +7 -0
  26. data/lib/xqsr3/extensions/hash/slice.rb +22 -0
  27. data/lib/xqsr3/extensions/io/writelines.rb +38 -6
  28. data/lib/xqsr3/extensions/kernel/integer.rb +6 -13
  29. data/lib/xqsr3/extensions/string/to_bool.rb +4 -0
  30. data/lib/xqsr3/extensions/test/unit/assert_eql.rb +1 -0
  31. data/lib/xqsr3/extensions/test/unit/assert_false.rb +1 -0
  32. data/lib/xqsr3/extensions/test/unit/assert_not.rb +1 -0
  33. data/lib/xqsr3/extensions/test/unit/assert_not_eql.rb +1 -0
  34. data/lib/xqsr3/extensions/test/unit/assert_raise_with_message.rb +25 -4
  35. data/lib/xqsr3/extensions/test/unit/assert_subclass_of.rb +1 -0
  36. data/lib/xqsr3/extensions/test/unit/assert_superclass_of.rb +1 -0
  37. data/lib/xqsr3/extensions/test/unit/assert_true.rb +1 -0
  38. data/lib/xqsr3/extensions/test/unit/assert_type_has_instance_methods.rb +3 -12
  39. data/lib/xqsr3/hash_utilities.rb +11 -0
  40. data/lib/xqsr3/hash_utilities/deep_transform.rb +2 -2
  41. data/lib/xqsr3/hash_utilities/key_matching.rb +6 -4
  42. data/lib/xqsr3/internal_/test_unit_version_.rb +30 -4
  43. data/lib/xqsr3/io/writelines.rb +55 -19
  44. data/lib/xqsr3/quality.rb +8 -1
  45. data/lib/xqsr3/quality/parameter_checking.rb +52 -78
  46. data/lib/xqsr3/string_utilities.rb +16 -0
  47. data/lib/xqsr3/string_utilities/ends_with.rb +16 -7
  48. data/lib/xqsr3/string_utilities/nil_if_empty.rb +8 -4
  49. data/lib/xqsr3/string_utilities/nil_if_whitespace.rb +9 -4
  50. data/lib/xqsr3/string_utilities/quote_if.rb +12 -14
  51. data/lib/xqsr3/string_utilities/starts_with.rb +23 -5
  52. data/lib/xqsr3/string_utilities/to_symbol.rb +24 -5
  53. data/lib/xqsr3/string_utilities/truncate.rb +20 -4
  54. data/lib/xqsr3/version.rb +3 -2
  55. data/test/unit/containers/tc_multi_map.rb +174 -16
  56. data/test/unit/extensions/hash/tc_hash.rb +6 -0
  57. data/test/unit/extensions/hash/tc_slice.rb +31 -0
  58. data/test/unit/extensions/io/tc_writelines.rb +36 -0
  59. metadata +16 -3
@@ -0,0 +1,11 @@
1
+
2
+ %w{
3
+
4
+ bool_parser
5
+ integer_parser
6
+ }.each do |name|
7
+
8
+ require File.join(File.dirname(__FILE__), 'conversion', name)
9
+ end
10
+
11
+
@@ -54,6 +54,7 @@
54
54
  module Xqsr3
55
55
  module Conversion
56
56
 
57
+ # +include-able module that provides Boolean parsing
57
58
  module BoolParser
58
59
 
59
60
  private
@@ -69,30 +70,26 @@ module BoolParser
69
70
 
70
71
  public
71
72
 
73
+ # Recognised truey values
72
74
  DEFAULT_TRUE_VALUES = [ /true/i, '1' ]
75
+ # Recognised falsey values
73
76
  DEFAULT_FALSE_VALUES = [ /false/i, '0' ]
74
77
 
75
- # Attempts to parse the given String to a Boolean value, based on the
78
+ # Attempts to parse the given string +s+ to a Boolean value, based on the
76
79
  # given +options+
77
80
  #
78
81
  # === Signature
79
82
  #
80
83
  # * *Parameters:*
81
- # - +options+:: An options hash, containing any of the following options
84
+ # - +s+ The string to be parsed
85
+ # - +options+ An options hash, containing any of the following options
82
86
  #
83
87
  # * *Options:*
84
- # - +:false_values+:: [::Array] An array of strings or regular
85
- # expressions against which to match for false value. Defaults to
86
- # +DEFAULT_FALSE_VALUES+
87
- # - +:true_values+:: [::Array] An array of strings or regular
88
- # expressions against which to match for true value. Defaults to
89
- # +DEFAULT_TRUE_VALUES+
90
- # - +:default_value+:: An object to be returned if matching fails.
91
- # Defaults to +nil+
92
- # - +:false_value+:: An object to be returned if matching succeeds to
93
- # match against +:false_values+.
94
- # - +:true_value+:: An object to be returned if matching succeeds to
95
- # match against +:true_values+.
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+
96
93
  def self.to_bool s, **options
97
94
 
98
95
  true_values = options[:true_values] || DEFAULT_TRUE_VALUES
@@ -6,7 +6,7 @@
6
6
  # module
7
7
  #
8
8
  # Created: 21st November 2017
9
- # Updated: 12th April 2019
9
+ # Updated: 15th April 2019
10
10
  #
11
11
  # Home: http://github.com/synesissoftware/xqsr3
12
12
  #
@@ -54,10 +54,12 @@
54
54
  module Xqsr3
55
55
  module Conversion
56
56
 
57
+ # +include-able module that provides Integer parsing
57
58
  module IntegerParser
58
59
 
59
60
  private
60
- module IntegerParser_Helper_ # :nodoc:
61
+ # @!visibility private
62
+ module IntegerParser_Helper_ # :nodoc: all
61
63
 
62
64
  if Kernel.respond_to?(:xqsr3_Integer_original_method)
63
65
 
@@ -156,22 +158,14 @@ module IntegerParser
156
158
  # === Signature
157
159
  #
158
160
  # * *Parameters:*
159
- # - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
160
- # - +base+:: A value of 0, or between 2 and 36. Defaults to 0
161
- # - +options+:: An options hash, containing any of the following
162
- # options
163
- # - +block+:: An optional caller-supplied 4-parameter block -
164
- # taking the exception, +arg+, +base+, and +options+ - that will be
165
- # invoked with the +ArgumentError+ exception, allowing the caller to
166
- # take additional action. If the block returns then its return value
167
- # will be returned to the caller
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
168
165
  #
169
166
  # * *Options:*
170
- # - +:default+:: A default value to be used when +arg+ is +nil+ or
171
- # cannot be converted by (the original) +Kernel#Integer+
172
- # - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be
173
- # converted by (the original) +Kernel#Integer+. Ignored if
174
- # +:default+ is specified
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
175
169
  def self.to_integer arg, base = 0, **options, &block
176
170
 
177
171
  IntegerParser_Helper_.to_integer_ arg, base, options, &block
@@ -0,0 +1,11 @@
1
+
2
+ %w{
3
+
4
+ exception_utilities
5
+ inspect_builder
6
+ }.each do |name|
7
+
8
+ require File.join(File.dirname(__FILE__), 'diagnostics', name)
9
+ end
10
+
11
+
@@ -100,8 +100,8 @@ module ExceptionUtilities
100
100
  #
101
101
  # === Parameters
102
102
  #
103
- # * +args+:: 0 or more arguments
104
- # * +options+:: An options hash
103
+ # * +args+ 0 or more arguments
104
+ # * +options+ An options hash
105
105
  #
106
106
  # === Parameter Interpretation
107
107
  #
@@ -5,13 +5,13 @@
5
5
  # Purpose: Definition of the WithCause inclusion module
6
6
  #
7
7
  # Created: 16th December 2017
8
- # Updated: 5th September 2018
8
+ # Updated: 12th April 2019
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/xqsr3
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
- # Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
14
+ # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
15
15
  # All rights reserved.
16
16
  #
17
17
  # Redistribution and use in source and binary forms, with or without
@@ -66,6 +66,7 @@ module Exceptions
66
66
  #
67
67
  module WithCause
68
68
 
69
+ # Array of hidden fields
69
70
  INSPECT_HIDDEN_FIELDS = [ 'has_implicit_message', 'uses_cause_message' ]
70
71
 
71
72
  # Defines an initializer for an exception class that allows a cause (aka
@@ -75,13 +76,11 @@ module WithCause
75
76
  # === Signature
76
77
  #
77
78
  # * *Parameters:*
78
- # -
79
- # - +option+::
79
+ # - +args+ 0+ arguments passed through to the +include+-ing class' initialiser
80
+ # - +options+ Options hash
80
81
  #
81
82
  # * *Options:*
82
- # - +:cause+ - The exception to be used as a cause, and ensures that
83
- # that is not inferred from the arguments. May be +nil+ to ensure
84
- # that no cause is inferred
83
+ # - +:cause+ - The exception to be used as a cause, and ensures that that is not inferred from the arguments. May be +nil+ to ensure that no cause is inferred
85
84
  def initialize(*args, **options)
86
85
 
87
86
  @uses_cause_message = false
@@ -143,6 +142,15 @@ module WithCause
143
142
  # present
144
143
  attr_reader :options
145
144
 
145
+ # Message obtained by concatenation of all chained exceptions' messages
146
+ #
147
+ # === Signature
148
+ #
149
+ # * *Parameters:*
150
+ # - +options+ Options hash
151
+ #
152
+ # * *Options:*
153
+ # - +:separator+ (String) A string used to separate each chained exception message. Defaults to ": "
146
154
  def chained_message **options
147
155
 
148
156
  return message unless cause
@@ -5,13 +5,13 @@
5
5
  # Purpose: ::Xqsr3::Diagnostics::InspectBuilder module
6
6
  #
7
7
  # Created: 4th September 2018
8
- # Updated: 5th September 2018
8
+ # Updated: 12th April 2019
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/xqsr3
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
- # Copyright (c) 2018, Matthew Wilson and Synesis Software
14
+ # Copyright (c) 2018-2019, Matthew Wilson and Synesis Software
15
15
  # All rights reserved.
16
16
  #
17
17
  # Redistribution and use in source and binary forms, with or without
@@ -54,30 +54,28 @@ module Diagnostics
54
54
 
55
55
  module InspectBuilder
56
56
 
57
- module InspectBuilder_Utilities
57
+ # @!visibility private
58
+ module InspectBuilder_Utilities # :nodoc: all
58
59
 
60
+ # @!visibility private
59
61
  NORMALISE_FUNCTION = lambda { |ar| ar.map { |v| v.to_s }.map { |v| '@' == v[0] ? v : "@#{v}" } }
60
62
  end # module InspectBuilder_Utilities
61
63
 
64
+ # Generates an inspect string for the +include+-ing class
62
65
  #
63
66
  # === Signature
64
67
  #
65
68
  # * *Parameters:*
66
- # @param +o+:: The target of the +inspect+ message for which a message
67
- # will be built
69
+ # - +o+ The target of the +inspect+ message for which a message will be built
68
70
  #
69
71
  # * *Options:*
70
- # @option +:no_class+:: (boolean) Elides the class qualification
71
- # @option +:no_object_id+:: (boolean) Elides the object id
72
- # @option +:show_fields+:: (boolean) Shows (all) object fields
73
- # @option +:hidden_fields+:: ([ String ]) Names of fields to be omitted
74
- # (when +:show_fields+ is specified). Overridden by +:shown_fields+
75
- # @option +:shown_fields+:: ([ String ]) Names of fields to be shown
76
- # (when +:show_fields+ is specified). Overrides +:hidden_fields+
77
- # @option +:truncate_width+:: (Integer) Specifies a maximum width for
78
- # the values of fields
79
- # @option +:deep_inspect+:: (boolean) Causes fields' values to be
80
- # obtained via their own +inspect+ methods
72
+ # - +:no_class+ (boolean) Elides the class qualification
73
+ # - +:no_object_id+ (boolean) Elides the object id
74
+ # - +:show_fields+ (boolean) Shows (all) object fields
75
+ # - +:hidden_fields+ ([ String ]) Names of fields to be omitted (when +:show_fields+ is specified). Overridden by +:shown_fields+
76
+ # - +:shown_fields+ ([ String ]) Names of fields to be shown (when +:show_fields+ is specified). Overrides +:hidden_fields+
77
+ # - +:truncate_width+ (Integer) Specifies a maximum width for the values of fields
78
+ # - +:deep_inspect+ (boolean) Causes fields' values to be obtained via their own +inspect+ methods
81
79
  def self.make_inspect o, **options
82
80
 
83
81
  r = ''
@@ -161,6 +159,8 @@ module InspectBuilder
161
159
  end
162
160
 
163
161
  # Creates an inspect string from self
162
+ #
163
+ # see InspectBuilder::make_inspect
164
164
  def make_inspect **options
165
165
 
166
166
  ::Xqsr3::Diagnostics::InspectBuilder.make_inspect self, **options
@@ -5,13 +5,13 @@
5
5
  # Purpose: Documentation of the ::Xqsr3 modules
6
6
  #
7
7
  # Created: 10th June 2016
8
- # Updated: 10th June 2016
8
+ # Updated: 12th April 2019
9
9
  #
10
10
  # Home: http://github.com/synesissoftware/xqsr3
11
11
  #
12
12
  # Author: Matthew Wilson
13
13
  #
14
- # Copyright (c) 2016, Matthew Wilson and Synesis Software
14
+ # Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
15
15
  # All rights reserved.
16
16
  #
17
17
  # Redistribution and use in source and binary forms, with or without
@@ -58,24 +58,36 @@
58
58
  # * ::Xqsr3::StringUtilities
59
59
  module Xqsr3
60
60
 
61
+ # Array utilities
62
+ #
63
+ # === Subordinate modules of interest
64
+ # * ::Xqsr3::ArrayUtilities::JoinWithOr
65
+ module ArrayUtilities
66
+ end # module ArrayUtilities
67
+
61
68
  # Command-line Utilities
62
69
  #
63
70
  # === Subordinate modules of interest
64
71
  # * ::Xqsr3::CommandLineUtilities::MapOptionString
65
72
  module CommandLineUtilities
66
-
67
73
  end # module CommandLineUtilities
68
74
 
69
75
  # Containers
70
76
  #
71
77
  module Containers
72
-
73
78
  end # module Containers
74
79
 
80
+ # Conversion
81
+ #
82
+ module Conversion
83
+ end # module Conversion
84
+
75
85
  # Diagnostic facilities
76
86
  #
77
87
  # === Subordinate modules of interest
78
88
  # * ::Xqsr3::Diagnostics::ExceptionUtilities
89
+ # * ::Xqsr3::Diagnostics::InspectBuilder
90
+ # * ::Xqsr3::Diagnostics::Exceptions::WithCause
79
91
  #
80
92
  module Diagnostics
81
93
 
@@ -86,31 +98,148 @@ module Xqsr3
86
98
  #
87
99
  module ExceptionUtilities
88
100
  end # module ExceptionUtilities
101
+
102
+ # Inspect builder
103
+ #
104
+ module InspectBuilder
105
+ end # module InspectBuilder
106
+
107
+ # Exception-related utilities
108
+ #
109
+ # === Components of interest
110
+ # * ::Xqsr3::Diagnostics::Exceptions::WithCause
111
+ #
112
+ module Exceptions
113
+ end # module Exceptions
89
114
  end # module Diagnostics
90
115
 
91
- # IO
116
+ # Hash utilities
92
117
  #
93
- module IO
118
+ # === Subordinate modules of interest
119
+ # * ::Xqsr3::HashUtilities::DeepTransform
120
+ # * ::Xqsr3::HashUtilities::KeyMatching
121
+ module HashUtilities
94
122
 
95
- end # module IO
123
+ # Exception-related utilities
124
+ #
125
+ # === Components of interest
126
+ # * ::Xqsr3::Diagnostics::HashUtilities::deep_transform
127
+ # * ::Xqsr3::Diagnostics::HashUtilities::deep_transform!
128
+ #
129
+ module DeepTransform
130
+ end # module DeepTransform
131
+ end # module HashUtilities
132
+
133
+ # IO
134
+ #
135
+ class IO
136
+ end # class IO
96
137
 
97
138
  # Quality
98
139
  #
99
140
  # === Subordinate modules of interest
100
141
  # * ::Xqsr3::Quality::ParameterChecking
101
142
  module Quality
102
-
103
143
  end # module Quality
104
144
 
105
145
  # String utilities
106
146
  #
107
147
  # === Subordinate modules of interest
148
+ # * ::Xqsr3::StringUtilities::EndsWith
149
+ # * ::Xqsr3::StringUtilities::NilIfEmpty
150
+ # * ::Xqsr3::StringUtilities::NilIfWhitespace
151
+ # * ::Xqsr3::StringUtilities::QuoteIf
152
+ # * ::Xqsr3::StringUtilities::StartsWith
108
153
  # * ::Xqsr3::StringUtilities::ToSymbol
154
+ # * ::Xqsr3::StringUtilities::Truncate
109
155
  module StringUtilities
110
156
 
157
+ =begin
158
+ module EndsWith
159
+ end # module EndsWith
160
+ module NilIfEmpty
161
+ end # module NilIfEmpty
162
+ module NilIfWhitespace
163
+ end # module NilIfWhitespace
164
+ module QuoteIf
165
+ end # module QuoteIf
166
+ module StartsWith
167
+ end # module StartsWith
168
+ module ToSymbol
169
+ end # module ToSymbol
170
+ module Truncate
171
+ end # module Truncate
172
+ =end
111
173
  end # module StringUtilities
112
-
113
174
  end # module Xqsr3
114
175
 
176
+ # Standard class, extended with methods:
177
+ #
178
+ # - Array#join_with_or
179
+ class Array; end
180
+
181
+ # Standard module, extended with methods:
182
+ #
183
+ # - Enumerable#collect_with_index
184
+ # - Enumerable#detect_map
185
+ # - Enumerable#unique
186
+ module Enumerable; end
187
+
188
+ # Standard class, extended with methods:
189
+ #
190
+ # - Hash#deep_transform
191
+ # - Hash#has_match?
192
+ # - Hash#match
193
+ class Hash; end
194
+
195
+ # Standard class, extended with methods:
196
+ #
197
+ # - IO#writelines
198
+ class IO; end
199
+
200
+ # Standard module, extended with methods:
201
+ #
202
+ # - Kernel::Integer
203
+ # - Kernel#raise_with_options
204
+ module Kernel; end
205
+
206
+ # Standard class, extended with methods:
207
+ #
208
+ # - String#ends_with?
209
+ # - String#map_option_string
210
+ # - String#nil_if_empty
211
+ # - String#nil_if_whitespace
212
+ # - String#quote_if
213
+ # - String#starts_with?
214
+ # - String#to_bool
215
+ # - String#to_symbol
216
+ # - String#truncate
217
+ class String; end
218
+
219
+ # Standard module
220
+ module Test
221
+
222
+ # Standard module
223
+ module Unit
224
+
225
+ # Standard module
226
+ #
227
+ # === Components of interest
228
+ # * ::Test::Unit::Assertions#assert_eql
229
+ # * ::Test::Unit::Assertions#assert_false
230
+ # * ::Test::Unit::Assertions#assert_not
231
+ # * ::Test::Unit::Assertions#assert_not_eql
232
+ # * ::Test::Unit::Assertions#assert_raise_with_message
233
+ # * ::Test::Unit::Assertions#assert_subclass_of
234
+ # * ::Test::Unit::Assertions#assert_superclass_of
235
+ # * ::Test::Unit::Assertions#assert_true
236
+ # * ::Test::Unit::Assertions#assert_type_has_instance_methods
237
+ module Assertions
238
+ end # module Assertions
239
+ end # module Unit
240
+ end # module Test
241
+
242
+
115
243
  # ############################## end of file ############################# #
116
244
 
245
+