xqsr3 0.22.4 → 0.26.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: f9ba5e26e05f852e8093d7fad6e1ea1b3aea26e596bac32483b5a0c0ec6176a5
-  data.tar.gz: 034b29eb4f8ce8ff96bfe05d98adcdca2c255e8f54ae295daafb00bce93ee942
+SHA1:
+  metadata.gz: 7ccb3ee0c47865bb1eede2560dacd10988fe5c88
+  data.tar.gz: aa200aec397e17b577c201253faed63f4c4f31f6
 SHA512:
-  metadata.gz: 634f55ac0143b7285caf59a41b06b96f3bc4aaacaa343dc68fdad6372916de3b8d58f5adf23179948ba5bef665c4da1fe6abe285d51925655ffc920f68aa59a1
-  data.tar.gz: 90b016538c14a6d7f24e2d3b0e379eacf4b1e33be938ba5f4a7adfa016848d0482d973ab99ae24293c4fecf98839d7c8d799b371f825caef982cd5cb7302086d
+  metadata.gz: 318fcaf298a8096a4ff6ad97b9ae6522bc7997c446cde7ad5e12cf25ae0e09cb7b771d38ac900ae680299eb031359bc46d799176ccee22460d02e36adca2276d
+  data.tar.gz: 3521b7dd6621c09af7bc43d65b9af27a98fbb32ee32296ce07cdc60ca4950d1e4d5e4f1a4dacec139366a89fd90cdd618194ad6bd019d79d219d405f23b58e4a

data/lib/xqsr3/conversion/bool_parser.rb

@@ -116,3 +116,4 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
+

data/lib/xqsr3/conversion/integer_parser.rb

@@ -0,0 +1,193 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/conversion/integer_parser.rb
+#
+# Purpose:      Definition of the ::Xqsr3::Conversion::IntegerParser
+#               module
+#
+# Created:      21st November 2017
+# Updated:      1st August 2018
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+# ##########################################################
+# ::Xqsr3::Conversion::IntegerParser
+
+=begin
+=end
+
+module Xqsr3
+module Conversion
+
+module IntegerParser
+
+	private
+	module IntegerParser_Helper_ # :nodoc:
+
+		if Kernel.respond_to?(:xqsr3_Integer_original_method)
+
+			def self.invoke_Integer_1(arg)
+
+				Kernel.xqsr3_Integer_original_method(arg)
+			end
+
+			def self.invoke_Integer_2(arg, base)
+
+				Kernel.xqsr3_Integer_original_method(arg, base)
+			end
+		else
+
+			def self.invoke_Integer_1(arg)
+
+				Kernel.Integer(arg)
+			end
+
+			def self.invoke_Integer_2(arg, base)
+
+				Kernel.Integer(arg, base)
+			end
+		end
+
+		def self.invoke_Integer(arg, base)
+
+			case arg
+			when ::String
+
+				self.invoke_Integer_2 arg, base
+			else
+
+				if $DEBUG
+
+					case base
+					when nil, 0
+
+						;
+					else
+
+						warn "WARNING: #{self}::#{__method__}: " + 'base specified for non string value'
+					end
+				end
+
+				self.invoke_Integer_1 arg
+			end
+		end
+
+		def self.to_integer_ arg, base, options, &block
+
+			case	options
+			when	::Hash
+				;
+			else
+
+				raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
+			end
+
+			if block_given?
+
+				begin
+
+					return self.invoke_Integer arg, base
+				rescue ArgumentError, TypeError => x
+
+					return yield x, arg, base, options
+				end
+			end
+
+			if options.has_key?(:default) || options[:nil]
+
+				unless arg.nil?
+
+					begin
+
+						return self.invoke_Integer arg, base
+					rescue ArgumentError, TypeError
+					end
+				end
+
+				return options[:default] if options.has_key? :default
+
+				return nil
+			else
+
+				self.invoke_Integer arg, base
+			end
+		end
+	end # module IntegerParser_Helper_
+	public
+
+	# Attempts to convert a variable to an integer, according to the given
+	# options and block
+	#
+	# === Signature
+	#
+	# * *Parameters*:
+	#   - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
+	#   - +base+:: A value of 0, or between 2 and 36. Defaults to 0
+	#   - +options+:: An options hash, containing any of the following
+	#     options
+	#   - +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
+	#
+	# * *Options*:
+	#   - +:default+:: A default value to be used when +arg+ is +nil+ or
+	#     cannot be converted by (the original) +Kernel#Integer+
+	#   - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be
+	#     converted by (the original) +Kernel#Integer+. Ignored if
+	#     +:default+ is specified
+	def self.to_integer arg, base = 0, **options, &block
+
+		IntegerParser_Helper_.to_integer_ arg, base, options, &block
+	end
+
+	# Instance form of ::Xqsr3::Conversion::IntegerParser.to_integer
+	def to_integer base = 0, **options, &block
+
+		IntegerParser_Helper_.to_integer_ self, base, options, &block
+	end
+
+end # module IntegerParser
+
+end # module Conversion
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/lib/xqsr3/diagnostics/exceptions/with_cause.rb

@@ -5,13 +5,13 @@
 # Purpose:      Definition of the WithCause inclusion module
 #
 # Created:      16th December 2017
-# Updated:      17th December 2017
+# Updated:      14th March 2018
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -92,7 +92,7 @@ module WithCause
 
 			@has_implicit_message = args.empty?
 
-			super *args
+			super(*args)
 
 			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
 
@@ -123,7 +123,7 @@ module WithCause
 
 			@has_implicit_message = args.empty?
 
-			super *args
+			super(*args)
 
 			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
 

data/lib/xqsr3/extensions/kernel/integer.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a Integer 'overload' to the Kernel module
 #
 # Created:      21st November 2017
-# Updated:      22nd November 2017
+# Updated:      18th May 2018
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -44,6 +44,8 @@
 # ######################################################################## #
 
 
+require 'xqsr3/conversion/integer_parser'
+
 # ##########################################################
 # ::Kernel
 
@@ -62,7 +64,11 @@ module Kernel
 	#   - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
 	#   - +base+:: A value of 0, or between 2 and 36. Defaults to 0
 	#   - +options+:: An options hash, containing any of the following
-	#   options
+	#     options
+	#   - +block+:: An optional caller-supplied block 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
 	#
 	# * *Options*:
 	#   - +:default+:: A default value to be used when +arg+ is +nil+ or
@@ -70,26 +76,9 @@ module Kernel
 	#   - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be
 	#     converted by (the original) +Kernel#Integer+. Ignored if
 	#     +:default+ is specified
-	def Integer(arg, base = 0, **options)
-
-		if options.has_key?(:default) || options[:nil]
-
-			unless arg.nil?
-
-				begin
-
-					return xqsr3_Integer_original_method arg, base
-				rescue ArgumentError
-				end
-			end
-
-			return options[:default] if options.has_key? :default
-
-			return nil
-		else
+	def Integer(arg, base = 0, **options, &block)
 
-			xqsr3_Integer_original_method arg, base
-		end
+		::Xqsr3::Conversion::IntegerParser.to_integer arg, base = 0, **options, &block
 	end
 
 	private :xqsr3_Integer_original_method

data/lib/xqsr3/extensions/string.rb

@@ -5,4 +5,5 @@ require 'xqsr3/extensions/string/quote_if'
 require 'xqsr3/extensions/string/starts_with'
 require 'xqsr3/extensions/string/to_bool'
 require 'xqsr3/extensions/string/to_symbol'
+require 'xqsr3/extensions/string/truncate'
 

data/lib/xqsr3/extensions/string/truncate.rb

@@ -0,0 +1,9 @@
+
+require 'xqsr3/string_utilities/truncate'
+
+class String
+
+	include ::Xqsr3::StringUtilities::Truncate
+end # class String
+
+

data/lib/xqsr3/extensions/test/unit/assert_raise_with_message.rb

@@ -40,12 +40,15 @@ module Assertions
 
 				yield
 
-				assert false, "expected did not throw an exception"
+				assert false, 'the block did not throw an exception as was expected'
+			rescue Test::Unit::AssertionFailedError
+
+				raise
 			rescue Exception => x
 
 				if type_spec
 
-					assert false, "exception not of any of required types (#{type_spec.join(', ')}); #{x.class} given" unless type_spec.any? { |c| x.is_a? c}
+					assert false, "exception (#{x.class}) - message: '#{x.message}' - not of any of required types (#{type_spec.join(', ')}); #{x.class} given" unless type_spec.any? { |c| x.is_a? c}
 				end
 
 				if message_spec

data/lib/xqsr3/hash_utilities/deep_transform.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      28th July 2017
+# Updated:      14th March 2018
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -45,6 +45,8 @@
 # ######################################################################## #
 
 
+require 'xqsr3/quality/parameter_checking'
+
 # ##########################################################
 # ::Xqsr3::HashUtilities::DeepTransform
 

data/lib/xqsr3/quality/parameter_checking.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ParameterChecking module
 #
 # Created:      12th February 2015
-# Updated:      2nd January 2018
+# Updated:      29th July 2018
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -75,6 +75,26 @@ module ParameterChecking
 				"#{a[0...-1].join(', ')}, or #{a[-1]}"
 			end
 		end
+
+		module Constants
+
+			RECOGNISED_OPTION_NAMES = %w{
+
+				allow_nil
+				nil
+				types
+				type
+				values
+				responds_to
+				reject_empty
+				require_empty
+				nothrow
+				message
+				strip_str_whitespace
+				treat_as_option
+			}.map { |v| v.to_sym }
+
+		end # module Constants
 	end # module Util_
 	public
 
@@ -86,34 +106,38 @@ module ParameterChecking
 	private
 	# Check a given parameter (value=+value+, name=+name+) for type and value
 	#
-	# @param +value+ the parameter whose value and type is to be checked
-	# @param +name+ [::String, ::Symbol] the name of the parameter to be
+	# @param +value+:: the parameter whose value and type is to be checked
+	# @param +name+:: (::String, ::Symbol) the name of the parameter to be
 	#         checked
-	# @param +options+ [::Hash] options that moderate the behaviour
+	# @param +options+:: (::Hash) options that moderate the behaviour
 	#
-	# @option +:allow_nil+ [boolean] The +value+ must not be +nil+ unless
+	# @option +:allow_nil+:: (boolean) The +value+ must not be +nil+ unless
 	#          this option is true
-	# @option +:nil+ an alias for +:allow_nil+
-	# @option +:types+ [::Array] An array of types one of which +value+ must
-	#          be (or must be derived from). One of these types may be an
-	#          array of types, in which case +value+ may be an array that
+	# @option +:nil+:: an alias for +:allow_nil+
+	# @option +:types+:: (::Array) An array of types one of which +value+
+	#          must be (or must be derived from). One of these types may be
+	#          an array of types, in which case +value+ may be an array that
 	#          must consist wholly of those types
-	# @option +:type+ [::Class] A single type parameter, used only if
+	# @option +:type+:: (::Class) A single type parameter, used only if
 	#          +:types+ is not specified
-	# @option +:values+ [::Array] an array of values one of which +value+
+	# @option +:values+:: (::Array) an array of values one of which +value+
 	#          must be
-	# @option +:responds_to+ [::Array] An array of symbols specifying all
+	# @option +:responds_to+:: (::Array) An array of symbols specifying all
 	#          messages to which the parameter will respond
-	# @option +:reject_empty+ [boolean] requires value to respond to +empty?+
-	#          message and to do so with false, unless +nil+
-	# @option +:require_empty+ [boolean] requires value to respond to
+	# @option +:reject_empty+:: (boolean) requires value to respond to
+	#          +empty?+ message and to do so with false, unless +nil+
+	# @option +:require_empty+:: (boolean) requires value to respond to
 	#          +empty?+ message and to do so with true, unless +nil+
-	# @option +:nothrow+ [boolean] causes failure to be indicated by a +nil+
-	#          return rather than a thrown exception
-	# @option +:message+ [::String] specifies a message to be used in any
+	# @option +:nothrow+:: (boolean) causes failure to be indicated by a
+	#          +nil+ return rather than a thrown exception
+	# @option +:message+:: (::String) specifies a message to be used in any
 	#          thrown exception, which suppresses internal message
 	#          preparation
-	# @option +:treat_as_option+ [boolean] If true, the value will be
+	# @option +:strip_str_whitespace+:: (boolean) If +value+ is a string (as
+	#          determined by responding to +to_str+ message), then it will
+	#          be stripped - leading and trailing whitespace removed -
+	#          before any processing
+	# @option +:treat_as_option+:: (boolean) If true, the value will be
 	#          treated as an option when reporting check failure
 	#
 	# This method is private, because it should only be used within methods
@@ -134,51 +158,50 @@ module ParameterChecking
 	# Specific form of the +check_parameter()+ that is used to check
 	# options, taking instead the hash and the key
 	#
-	# @param +h+ [::Hash] The options hash from which the named element is
+	# @param +h+:: (::Hash) The options hash from which the named element is
 	#         to be tested. May not be +nil+
-	# @param +name+ [::String, ::Symbol] The options key name. May not be
-	#         +nil+
-	# @param +options+ [::Hash] options that moderate the behaviour in the
+	# @param +name+:: (::String, ::Symbol, [ ::String, ::Symbol ]) The
+	#         options key name, or an array of names. May not be +nil+
+	# @param +options+:: (::Hash) options that moderate the behaviour in the
 	#         same way as for +check_parameter()+ except that the
 	#         +:treat_as_option+ option (with the value +true+) is merged in
 	#         before calling +check_parameter()+
 	#
-	# 
 	def check_option h, name, options = {}, &block
 
-		Util_.check_parameter h[name], name, options.merge({ treat_as_option: true }), &block
+		Util_.check_option h, name, options, &block
 	end
 
 	public
 	# Check a given parameter (value=+value+, name=+name+) for type and value
 	#
-	# @param +value+ the parameter whose value and type is to be checked
-	# @param +name+ the name of the parameter to be checked
-	# @param +options+ options
+	# @param +value+:: the parameter whose value and type is to be checked
+	# @param +name+:: the name of the parameter to be checked
+	# @param +options+:: options
 	#
-	# @option +:allow_nil+ [boolean] The +value+ must not be +nil+ unless
+	# @option +:allow_nil+:: (boolean) The +value+ must not be +nil+ unless
 	#          this option is true
-	# @option +:nil+ an alias for +:allow_nil+
-	# @option +:types+ [::Array] An array of types one of which +value+ must
+	# @option +:nil+:: an alias for +:allow_nil+
+	# @option +:types+:: (::Array) An array of types one of which +value+ must
 	#          be (or must be derived from). One of these types may be an
 	#          array of types, in which case +value+ may be an array that
 	#          must consist wholly of those types
-	# @option +:type+ [::Class] A single type parameter, used only if
+	# @option +:type+:: (::Class) A single type parameter, used only if
 	#          +:types+ is not specified
-	# @option +:values+ [::Array] an array of values one of which +value+
+	# @option +:values+:: (::Array) an array of values one of which +value+
 	#          must be
-	# @option +:responds_to+ [::Array] An array of symbols specifying all
+	# @option +:responds_to+:: (::Array) An array of symbols specifying all
 	#          messages to which the parameter will respond
-	# @option +:reject_empty+ [boolean] requires value to respond to +empty?+
+	# @option +:reject_empty+:: (boolean) requires value to respond to +empty?+
 	#          message and to do so with false, unless +nil+
-	# @option +:require_empty+ [boolean] requires value to respond to
+	# @option +:require_empty+:: (boolean) requires value to respond to
 	#          +empty?+ message and to do so with true, unless +nil+
-	# @option +:nothrow+ [boolean] causes failure to be indicated by a +nil+
+	# @option +:nothrow+:: (boolean) causes failure to be indicated by a +nil+
 	#          return rather than a thrown exception
-	# @option +:message+ [boolean] specifies a message to be used in any
+	# @option +:message+:: (boolean) specifies a message to be used in any
 	#          thrown exception, which suppresses internal message
 	#          preparation
-	# @option +:treat_as_option+ [boolean] If true, the value will be
+	# @option +:treat_as_option+:: (boolean) If true, the value will be
 	#          treated as an option when reporting check failure
 	#
 	def self.check_parameter value, name, options = {}, &block
@@ -196,14 +219,74 @@ module ParameterChecking
 	end
 
 	private
+	def Util_.check_option h, names, options = {}, &block
+
+		warn "#{self}::#{__method__}: given parameter h - value '#{h.inspect}' - must be a #{::Hash} but is a #{h.class}" unless ::Hash === h
+
+		case names
+		when ::Array
+
+			allow_nil	=	options[:allow_nil] || options[:nil]
+
+			# find the first item whose name is in the hash ...
+
+			found_name	=	names.find { |name| h.has_key?(name) }
+
+			if found_name.nil? && allow_nil
+
+				return nil
+			end
+
+			# ... or use the first (just to get a name for reporting)
+
+			found_name	||=	names[0]
+
+			Util_.check_parameter h[found_name], found_name, options.merge({ treat_as_option: true }), &block
+		else
+
+			name	=	names
+
+			Util_.check_parameter h[name], name, options.merge({ treat_as_option: true }), &block
+		end
+	end
+
 	def Util_.check_parameter value, name, options, &block
 
+		if $DEBUG
+
+			unrecognised_option_names	=	options.keys - Util_::Constants::RECOGNISED_OPTION_NAMES
+
+			unless unrecognised_option_names.empty?
+
+				s	=	"#{self}::check_parameter: the following options are not recognised:"
+
+				unrecognised_option_names.each { |n| s += "\n\t'#{n}'" }
+
+				warn s
+			end
+		end
+
+		# strip whitespace
+
+		if !value.nil? && options[:strip_str_whitespace]
+
+			if value.respond_to? :to_str
+
+				value = value.to_str.strip
+			else
+
+				warn "#{self}::#{__method__}: options[:strip_str_whitespace] specified but value - '#{value}' (#{value.class}) - does not respond to to_str" unless value.respond_to? :to_str
+			end
+		end
+
+
 		failed_check	=	false
 		options			||=	{}
 		message			=	options[:message]
 		treat_as_option	=	options[:treat_as_option]
 		return_value	=	value
 		param_s			=	treat_as_option	? 'option' : 'parameter'
+		allow_nil		=	options[:allow_nil] || options[:nil]
 
 		warn "#{self}::check_parameter: invoked with non-string/non-symbol name: name.class=#{name.class}" unless name && [ ::String, ::Symbol ].any? { |c| name.is_a?(c) }
 
@@ -211,8 +294,10 @@ module ParameterChecking
 
 			case name
 			when ::String
-				name = ':' + name if ':' != name[0]
+
+				;
 			when ::Symbol
+
 				name = ':' + name.to_s
 			else
 			end
@@ -221,7 +306,7 @@ module ParameterChecking
 
 		# nil check
 
-		if value.nil? && !options[:allow_nil]
+		if value.nil? && !allow_nil
 
 			failed_check	=	true
 
@@ -256,7 +341,7 @@ module ParameterChecking
 			types		=	[value.class] if types.empty?
 
 			warn "#{self}::check_parameter: options[:types] of type #{types.class} - should be #{::Array}" unless types.is_a?(Array)
-			warn "#{self}::check_parameter: options[:types] - '#{options[:types]}' - should contain only classes or arrays of classes" if types.is_a?(::Array) && !types.all? { |c| ::Class === c || (::Array === c && c.all? { |c2| ::Class === c2 }) }
+			warn "#{self}::check_parameter: options[:types] - '#{types}' - should contain only classes or arrays of classes" if types.is_a?(::Array) && !types.all? { |c| ::Class === c || (::Array === c && c.all? { |c2| ::Class === c2 }) }
 
 			unless types.any? do |t|
 
@@ -330,44 +415,47 @@ module ParameterChecking
 
 		# reject/require empty?
 
-		if options[:reject_empty]
+		unless value.nil?
 
-			warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
+			if options[:reject_empty]
 
-			if value.empty?
+				warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
 
-				failed_check	=	true
+				if value.empty?
 
-				unless options[:nothrow]
+					failed_check	=	true
 
-					unless message
-						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+					unless options[:nothrow]
 
-						message		=	"#{param_s} #{s_name}must not be empty"
-					end
+						unless message
+							s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+							message		=	"#{param_s} #{s_name}must not be empty"
+						end
 
-					raise ArgumentError, message
+						raise ArgumentError, message
+					end
 				end
 			end
-		end
 
-		if options[:require_empty]
+			if options[:require_empty]
 
-			warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
+				warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
 
-			unless value.empty?
+				unless value.empty?
 
-				failed_check	=	true
+					failed_check	=	true
 
-				unless options[:nothrow]
+					unless options[:nothrow]
 
-					unless message
-						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+						unless message
+							s_name		=	name.is_a?(String) ? "'#{name}' " : ''
 
-						message		=	"#{param_s} #{s_name}must be empty"
-					end
+							message		=	"#{param_s} #{s_name}must be empty"
+						end
 
-					raise ArgumentError, message
+						raise ArgumentError, message
+					end
 				end
 			end
 		end

data/lib/xqsr3/string_utilities/truncate.rb

@@ -0,0 +1,121 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/string_utilities/truncate.rb
+#
+# Purpose:      Definition of the ::Xqsr3::StringUtilities::Truncate
+#               module
+#
+# Created:      12th April 2018
+# Updated:      12th April 2018
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+# ##########################################################
+# ::Xqsr3::StringUtilities::Truncate
+
+=begin
+=end
+
+module Xqsr3
+module StringUtilities
+
+# To-symbol conversion facilities
+#
+module Truncate
+
+	private
+	module Truncate_Helper_ #:nodoc:
+
+		def self.string_truncate_with_options_ s, width, options
+
+			case	s
+			when	::String
+				;
+			else
+
+				if s.respond_to? :to_str
+
+					s = s.to_str
+				else
+
+					raise TypeError, "string argument must be of type #{::String} or a type that will respond to to_str"
+				end
+			end
+
+			case	options
+			when	::Hash
+				;
+			else
+
+				raise TypeError, "options must be of type #{::Hash}, #{options.class} given"
+			end
+
+			len	=	s.size
+
+			return s if len <= width
+
+			omission	=	options[:omission] || '...'
+
+			if width < omission.size
+
+				return omission[0...width]
+			else
+
+				return s[0...(width - omission.size)] + omission
+			end
+		end
+	end
+	public
+
+	def self.string_truncate s, width, options = {}
+
+		Truncate_Helper_.string_truncate_with_options_ s, width, options
+	end
+
+	def truncate width, options = {}
+
+		Truncate_Helper_.string_truncate_with_options_ self, width, options
+	end
+end # module Truncate
+
+end # module StringUtilities
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/lib/xqsr3/version.rb

@@ -5,7 +5,7 @@
 # Purpose:      Version for Xqsr3 library
 #
 # Created:      3rd April 2016
-# Updated:      28th February 2018
+# Updated:      1st August 2018
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.22.4'
+	VERSION				=	'0.26.4'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
@@ -66,3 +66,4 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
+

data/test/unit/conversion/tc_integer_parser.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../lib')
+
+require 'xqsr3/conversion/integer_parser'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+class Test_IntegerParser < Test::Unit::TestCase
+
+	IP = ::Xqsr3::Conversion::IntegerParser
+
+	class SomeRandomException < Exception; end
+
+	def test_show_base_being_ignored
+
+		assert_equal -100, IP.to_integer(-100)
+		assert_equal -100, IP.to_integer(-100, 0)
+		assert_equal -100, IP.to_integer(-100.0, 0)
+		assert_equal -100, IP.to_integer(-100.0, 10)
+
+		assert_equal -100, IP.to_integer('-100')
+		assert_equal -100, IP.to_integer('-100', 0)
+		assert_equal -100, IP.to_integer('-100', 10)
+		assert_equal -4, IP.to_integer('-100', 2)
+	end
+
+	def test_default_for_invalid_type
+
+		assert_equal 12345, IP.to_integer(12..345, default: 12345)
+	end
+
+	def test_to_integer_with_valid_values
+
+		assert_equal 0, IP.to_integer(0)
+		assert_equal +1, IP.to_integer(1)
+		assert_equal +1, IP.to_integer(+1)
+		assert_equal -1, IP.to_integer(-1)
+
+		assert_equal 0, IP.to_integer('0')
+		assert_equal +1, IP.to_integer('1')
+		assert_equal +1, IP.to_integer('+1')
+		assert_equal -1, IP.to_integer('-1')
+	end
+
+	def test_to_integer_with_invalid_values
+
+		assert_raise(TypeError) { IP.to_integer nil }
+		assert_raise(ArgumentError) { IP.to_integer '' }
+		assert_raise(ArgumentError) { IP.to_integer 'abc' }
+		assert_raise(ArgumentError) { IP.to_integer 'zero' }
+		assert_raise(ArgumentError) { IP.to_integer 'plus 1' }
+		assert_raise(ArgumentError) { IP.to_integer '/0' }
+	end
+
+	def test_to_integer_with_invalid_values_returning_nil
+
+		assert_nil IP.to_integer(nil, nil: true)
+		assert_nil IP.to_integer('', nil: true)
+		assert_nil IP.to_integer('abc', nil: true)
+		assert_nil IP.to_integer('zero', nil: true)
+		assert_nil IP.to_integer('plus 1', nil: true)
+		assert_nil IP.to_integer('/0', nil: true)
+	end
+
+	def test_to_integer_with_invalid_values_returning_0
+
+		assert_equal 0, IP.to_integer(nil, default: 0)
+		assert_equal 0, IP.to_integer('', default: 0)
+		assert_equal 0, IP.to_integer('abc', default: 0)
+		assert_equal 0, IP.to_integer('zero', default: 0)
+		assert_equal 0, IP.to_integer('plus 1', default: 0)
+		assert_equal 0, IP.to_integer('/0', default: 0)
+	end
+
+	def test_to_integer_with_invalid_values_returning_sentinel
+
+		assert_equal :sentinel, IP.to_integer(nil, default: :sentinel)
+		assert_equal :sentinel, IP.to_integer('', default: :sentinel)
+		assert_equal :sentinel, IP.to_integer('abc', default: :sentinel)
+		assert_equal :sentinel, IP.to_integer('zero', default: :sentinel)
+		assert_equal :sentinel, IP.to_integer('plus 1', default: :sentinel)
+		assert_equal :sentinel, IP.to_integer('/0', default: :sentinel)
+	end
+
+	def test_to_integer_with_invalid_values_returning_sentinel_of_nil
+
+		assert_equal nil, IP.to_integer(nil, default: nil)
+		assert_equal nil, IP.to_integer('', default: nil)
+		assert_equal nil, IP.to_integer('abc', default: nil)
+		assert_equal nil, IP.to_integer('zero', default: nil)
+		assert_equal nil, IP.to_integer('plus 1', default: nil)
+		assert_equal nil, IP.to_integer('/0', default: nil)
+	end
+
+	def test_to_integer_with_invalid_values_and_block
+
+		assert_equal nil, IP.to_integer(nil) { nil }
+		assert_equal nil, IP.to_integer('blah') { nil }
+
+		assert_equal 'one', IP.to_integer(nil) { 'one' }
+		assert_equal 'one', IP.to_integer('blah') { 'one' }
+
+		assert_raise(SomeRandomException) { IP.to_integer(nil) { raise SomeRandomException.new } }
+	end
+end
+
+

data/test/unit/conversion/tc_to_bool.rb

@@ -7,10 +7,10 @@ require 'xqsr3/conversion/bool_parser'
 require 'xqsr3/extensions/test/unit'
 require 'test/unit'
 
-include ::Xqsr3::Conversion
-
 class Test_Xqsr3_ConversionMultiMap < Test::Unit::TestCase
 
+	include ::Xqsr3::Conversion
+
 	def test_parse_normal
 
 		assert_true BoolParser.to_bool 'true'

data/test/unit/extensions/kernel/tc_integer.rb

@@ -4,10 +4,14 @@ $:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
 
 require 'xqsr3/extensions/kernel/integer'
 
+require 'xqsr3/extensions/test/unit'
+
 require 'test/unit'
 
 class Test_X_Kernel_Integer < Test::Unit::TestCase
 
+	class SomeRandomException < Exception; end
+
 	def test_Integer_with_valid_values
 
 		assert_equal 0, Integer(0)
@@ -70,6 +74,17 @@ class Test_X_Kernel_Integer < Test::Unit::TestCase
 		assert_equal nil, Integer('plus 1', default: nil)
 		assert_equal nil, Integer('/0', default: nil)
 	end
+
+	def test_Integer_with_invalid_values_and_block
+
+		assert_equal nil, Integer(nil) { nil }
+		assert_equal nil, Integer('blah') { nil }
+
+		assert_equal 'one', Integer(nil) { 'one' }
+		assert_equal 'one', Integer('blah') { 'one' }
+
+		assert_raise(SomeRandomException) { Integer(nil) { raise SomeRandomException.new } }
+	end
 end
 
 

data/test/unit/extensions/string/tc_truncate.rb

@@ -0,0 +1,37 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
+
+require 'xqsr3/extensions/string/truncate'
+
+require 'xqsr3/extensions/test/unit'
+require 'test/unit'
+
+class Test_String_truncate < Test::Unit::TestCase
+
+	def test_empty_string
+
+		assert_equal '', ''.truncate(0)
+		assert_equal '', ''.truncate(1)
+		assert_equal '', ''.truncate(10)
+	end
+
+	def test_short_string
+
+		assert_equal '.', 'ab'.truncate(1)
+		assert_equal 'ab', 'ab'.truncate(2)
+		assert_equal 'ab', 'ab'.truncate(10)
+	end
+
+	def test_shortish_string
+
+		assert_equal '.', 'abcde'.truncate(1)
+		assert_equal '..', 'abcde'.truncate(2)
+		assert_equal '...', 'abcde'.truncate(3)
+		assert_equal 'a...', 'abcde'.truncate(4)
+		assert_equal 'abcde', 'abcde'.truncate(5)
+		assert_equal 'abcde', 'abcde'.truncate(10)
+	end
+end
+
+

data/test/unit/quality/tc_parameter_checking.rb

@@ -391,7 +391,7 @@ end
 			assert(false, 'should not get here')
 		rescue ArgumentError => ax
 
-			assert_equal "option ':thingy' may not be nil", ax.message
+			assert_equal "option 'thingy' may not be nil", ax.message
 		rescue => x
 
 			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
@@ -451,7 +451,7 @@ end
 			assert(false, 'should not get here')
 		rescue ArgumentError => ax
 
-			assert_equal "option ':thingy' may not be nil", ax.message
+			assert_equal "option 'thingy' may not be nil", ax.message
 		rescue => x
 
 			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
@@ -469,5 +469,103 @@ end
 			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
 		end
 	end
+
+	# test multiple option names
+
+	def check_method_multiple_option_names h, o, options = {}, &block
+
+		check_option h, o, options.merge({ }), &block
+	end
+
+	def test_multiple_option_names
+
+		# normal cases
+
+		thing	=	check_method_multiple_option_names({ thing: 123 }, :thing)
+		assert_equal 123, thing
+
+
+		thing	=	check_method_multiple_option_names({ thing: 123 }, :thingy, allow_nil: true)
+		assert_nil thing
+
+
+		begin
+			check_method_multiple_option_names({ thing: 123 }, :thingy)
+
+			assert(false, 'should not get here')
+		rescue ArgumentError => ax
+
+			assert_equal "option ':thingy' may not be nil", ax.message
+		rescue => x
+
+			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
+		end
+
+
+		# multiple-name cases
+
+
+		thing	=	check_method_multiple_option_names({ thing: 123 }, [ :thingy, :thing ])
+		assert_equal 123, thing
+
+
+		thing	=	check_method_multiple_option_names({ thing: 123 }, [ :thingy, :Thingy ], allow_nil: true)
+		assert_nil thing
+
+
+		begin
+			check_method_multiple_option_names({ thing: 123 }, [ :thingy, :Thingy ])
+
+			assert(false, 'should not get here')
+		rescue ArgumentError => ax
+
+			assert_equal "option ':thingy' may not be nil", ax.message
+		rescue => x
+
+			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
+		end
+
+		assert_raise_with_message(::ArgumentError, "option ':thingy' may not be nil") { check_option({ thing: 123 }, [ :thingy, :Thingy ]) }
+		assert_raise_with_message(::ArgumentError, "option ':Thingy' may not be nil") { check_option({ thing: 123 }, [ :Thingy, :thingy ]) }
+
+		# multiple-name cases where several present
+
+		assert_equal 123, check_method_multiple_option_names({ thing: 123, thingy: 45 }, [ :thing, :thingy ])
+		assert_equal 45, check_method_multiple_option_names({ thing: 123, thingy: 45 }, [ :thingy, :thing ])
+
+		assert_equal 123, check_method_multiple_option_names({ thing: 123, thingy: 45 }, [ :Thingy, :thing, :thingy ])
+		assert_equal 45, check_method_multiple_option_names({ thing: 123, thingy: 45 }, [ :Thingy, :thingy, :thing ])
+	end
+
+	# test strip_str_whitespace
+
+	def check_method_strip_str_whitespace v, name, options = {}, &block
+
+		check_parameter v, name, options, &block
+	end
+
+	def test_strip_str_whitespace
+
+		assert_equal ' ', check_method_strip_str_whitespace(' ', 's')
+		assert_equal ' ', check_method_strip_str_whitespace(' ', 's', strip_str_whitespace: false)
+		assert_equal ' ', check_method_strip_str_whitespace(' ', 's', reject_empty: true, strip_str_whitespace: false)
+		assert_equal '', check_method_strip_str_whitespace(' ', 's', strip_str_whitespace: true)
+		assert_equal 'abc', check_method_strip_str_whitespace("\tabc     ", 's', strip_str_whitespace: true)
+
+		assert_raise_with_message(::ArgumentError, /param.*s.*(?:may|must) not be empty/) { check_method_strip_str_whitespace('', 's', reject_empty: true) }
+		assert_raise_with_message(::ArgumentError, /param.*s.*(?:may|must) not be empty/) { check_method_strip_str_whitespace(' ', 's', reject_empty: true, strip_str_whitespace: true) }
+	end
+
+
+	# test_allow_nil
+
+	def test_allow_nil
+
+		assert_raise_with_message(::ArgumentError, /parameter .*the_param.* may not be nil/) { check_parameter(nil, 'the_param') }
+
+		assert_nil(check_parameter(nil, 'the_param', allow_nil: true))
+
+		assert_nil(check_parameter(nil, 'the_param', nil: true))
+	end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.22.4
+  version: 0.26.4
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-28 00:00:00.000000000 Z
+date: 2019-02-28 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -26,6 +26,7 @@ files:
 - lib/xqsr3/containers/frequency_map.rb
 - lib/xqsr3/containers/multi_map.rb
 - lib/xqsr3/conversion/bool_parser.rb
+- lib/xqsr3/conversion/integer_parser.rb
 - lib/xqsr3/diagnostics/exception_utilities.rb
 - lib/xqsr3/diagnostics/exceptions/with_cause.rb
 - lib/xqsr3/doc_.rb
@@ -52,6 +53,7 @@ files:
 - lib/xqsr3/extensions/string/starts_with.rb
 - lib/xqsr3/extensions/string/to_bool.rb
 - lib/xqsr3/extensions/string/to_symbol.rb
+- lib/xqsr3/extensions/string/truncate.rb
 - lib/xqsr3/extensions/test/unit.rb
 - lib/xqsr3/extensions/test/unit/assert_eql.rb
 - lib/xqsr3/extensions/test/unit/assert_false.rb
@@ -73,6 +75,7 @@ files:
 - lib/xqsr3/string_utilities/quote_if.rb
 - lib/xqsr3/string_utilities/starts_with.rb
 - lib/xqsr3/string_utilities/to_symbol.rb
+- lib/xqsr3/string_utilities/truncate.rb
 - lib/xqsr3/version.rb
 - lib/xqsr3/xml/utilities/compare.rb
 - test/unit/array_utilities/tc_join_with_or.rb
@@ -82,6 +85,7 @@ files:
 - test/unit/containers/tc_frequency_map.rb
 - test/unit/containers/tc_multi_map.rb
 - test/unit/containers/ts_all.rb
+- test/unit/conversion/tc_integer_parser.rb
 - test/unit/conversion/tc_to_bool.rb
 - test/unit/conversion/ts_all.rb
 - test/unit/diagnostics/exceptions/tc_with_cause.rb
@@ -107,6 +111,7 @@ files:
 - test/unit/extensions/string/tc_quote_if.rb
 - test/unit/extensions/string/tc_starts_with.rb
 - test/unit/extensions/string/tc_to_symbol.rb
+- test/unit/extensions/string/tc_truncate.rb
 - test/unit/extensions/string/ts_all.rb
 - test/unit/extensions/test/ts_all.rb
 - test/unit/extensions/test/unit/tc_assert_raise_with_message.rb
@@ -128,7 +133,7 @@ files:
 - test/unit/xml/utilities/ts_all.rb
 homepage: http://github.com/synesissoftware/xqsr3
 licenses:
-- BSD-3-Clause
+- BSD-3-clause
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -146,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.5
+rubygems_version: 2.6.14.3
 signing_key: 
 specification_version: 4
 summary: xqsr3