xqsr3 0.18.1 → 0.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fdaa43c901071d88f6fe3737998e4cd6a741c69b
-  data.tar.gz: c6876d3f0814a79a4c9a37bcb313c834ebae4096
+  metadata.gz: 77b11de6b0e214ce904216d2d6c1818e4d72e3cd
+  data.tar.gz: c383a8ddaab643a4d487d0fe44f37e794ae81217
 SHA512:
-  metadata.gz: 308f153ed24f39fa50494df2099e8978b5aa55c99b5b016a48ab03e73f9cff058f00d8056364a87695fe16497a0c1b3d70225c9146b4fb1e23bd4fd2cef250ca
-  data.tar.gz: 7590f907009d95b6057aec1573d7841c39ea2bbd8ff0713fa29356ae3d3836e39121c587285144db6d6f8e05019744caf493c6ead4682d1e648354b2e66c4c46
+  metadata.gz: 64e58c0bd8362c0971340a33cf2442f3eb78f0fbe81b76e04df28ea06c2bd738383238528251f0015810c0f6586b850731b4ba62b03ac943574e627299c8cd9d
+  data.tar.gz: 7ebf55437cd838b30620d950bf0f02c202c759022ab400ea046006b138ee95816ae3527cebd00bd881948b5be0df48af5f23adceff1df08e7df66b069f105b88

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

@@ -16,3 +16,4 @@ end # class Assertions
 end # module Unit
 end # module Test
 
+

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

@@ -16,3 +16,4 @@ end # class Assertions
 end # module Unit
 end # module Test
 
+

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

@@ -16,3 +16,4 @@ end # class Assertions
 end # module Unit
 end # module Test
 
+

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

@@ -0,0 +1,21 @@
+
+module Test
+module Unit
+
+module Assertions
+
+	unless respond_to? :assert_subclass_of
+
+		def assert_subclass_of(parent_class, tested_class, failure_message = nil)
+
+			failure_message ||= "#{tested_class} is not a subclass of #{parent_class}"
+
+			assert (tested_class < parent_class), failure_message
+		end
+	end
+
+end # class Assertions
+end # module Unit
+end # module Test
+
+

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

@@ -0,0 +1,21 @@
+
+module Test
+module Unit
+
+module Assertions
+
+	unless respond_to? :assert_superclass_of
+
+		def assert_superclass_of(child_class, tested_class, failure_message = nil)
+
+			failure_message ||= "#{tested_class} is not a superclass of #{child_class}"
+
+			assert (child_class < tested_class), failure_message
+		end
+	end
+
+end # class Assertions
+end # module Unit
+end # module Test
+
+

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

@@ -17,4 +17,3 @@ end # module Unit
 end # module Test
 
 
-

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

@@ -3,5 +3,7 @@ require 'xqsr3/extensions/test/unit/assert_eql'
 require 'xqsr3/extensions/test/unit/assert_false'
 require 'xqsr3/extensions/test/unit/assert_not'
 require 'xqsr3/extensions/test/unit/assert_not_eql'
+require 'xqsr3/extensions/test/unit/assert_subclass_of'
+require 'xqsr3/extensions/test/unit/assert_superclass_of'
 require 'xqsr3/extensions/test/unit/assert_true'
 

data/lib/xqsr3/quality/parameter_checking.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ParameterChecking module
 #
 # Created:      12th February 2015
-# Updated:      16th December 2017
+# Updated:      21st December 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -53,7 +53,8 @@
 module Xqsr3
 module Quality
 
-# Parameter-checking utilities
+# Inclusion module that creates class and instance methods +check_parameter+
+# that may be used to check parameter values and types
 #
 module ParameterChecking
 
@@ -64,10 +65,13 @@ module ParameterChecking
 
 			case a.size
 			when 1
+
 				a[0]
 			when 2
+
 				"#{a[0]} or #{a[1]}"
 			else
+
 				"#{a[0...-1].join(', ')}, or #{a[-1]}"
 			end
 		end
@@ -79,36 +83,40 @@ module ParameterChecking
 		base.extend self
 	end
 
+	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+ the name of the parameter to be checked
-	# @param +options+ options
+	# @param +name+ [::String, ::Symbol] the name of the parameter to be
+	#         checked
+	# @param +options+ [::Hash] options that moderate the behaviour
 	#
-	# @option +:allow_nil+ the +value+ must not be +nil+ unless this option
-	#          is true
-	# @option +:types+ 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+ a single type parameter, used only if +:types+ is not
-	#          specified
-	# @option +:values+ an array of values one of which +value+ must be
-	# @option +:responds_to+ an array of symbols specifying all messages to
-	#          which the parameter will respond
-	# @option +:reject_empty+ requires value to respond to +empty?+
+	# @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
+	#          must consist wholly of those types
+	# @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+
+	#          must be
+	# @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+ requires value to respond to +empty?+
-	#          message and to do so with true, unless +nil+
-	# @option +:nothrow+ causes failure to be indicated by a +nil+ return
-	#          rather than a thrown exception
-	# @option +:message+ specifies a message to be used in any thrown
-	#          exception, which suppresses internal message preparation
-	# @option +:treat_as_option+ if true, the value will be treated as an
-	#          option when reporting check failure
+	# @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
+	#          thrown exception, which suppresses internal message
+	#          preparation
+	# @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
-	private
 	def check_parameter value, name, options = {}, &block
 
 		Util_.check_parameter value, name, options, &block
@@ -118,40 +126,61 @@ module ParameterChecking
 	#
 	# @note This is obsolete, and will be removed in a future version.
 	# Please use +check_parameter+ instead
-	private
 	def check_param value, name, options = {}, &block
 
 		Util_.check_parameter value, name, options, &block
 	end
 
+	# 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
+	#         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
+	#         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
+	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
 	#
-	# @option +:allow_nil+ the +value+ must not be +nil+ unless this option
-	#          is true
-	# @option +:types+ 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+ a single type parameter, used only if +:types+ is not
-	#          specified
-	# @option +:values+ an array of values one of which +value+ must be
-	# @option +:responds_to+ an array of symbols specifying all messages to
-	#          which the parameter will respond
-	# @option +:reject_empty+ requires value to respond to +empty?+
+	# @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
+	#          must consist wholly of those types
+	# @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+
+	#          must be
+	# @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+ requires value to respond to +empty?+
-	#          message and to do so with true, unless +nil+
-	# @option +:nothrow+ causes failure to be indicated by a +nil+ return
-	#          rather than a thrown exception
-	# @option +:message+ specifies a message to be used in any thrown
-	#          exception, which suppresses internal message preparation
-	# @option +:treat_as_option+ if true, the value will be treated as an
-	#          option when reporting check failure
-	public
+	# @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+ [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
+	#          treated as an option when reporting check failure
+	#
 	def self.check_parameter value, name, options = {}, &block
 
 		Util_.check_parameter value, name, options, &block
@@ -161,7 +190,6 @@ module ParameterChecking
 	#
 	# @note This is obsolete, and will be removed in a future version.
 	# Please use +check_parameter+ instead
-	public
 	def self.check_param value, name, options = {}, &block
 
 		Util_.check_parameter value, name, options, &block
@@ -179,8 +207,17 @@ module ParameterChecking
 
 		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) }
 
-		name			=	name.to_s if name.is_a?(::Symbol)
-		name			=	(':' + name.to_s) if treat_as_option and name.is_a?(::String)
+		if treat_as_option
+
+			case name
+			when ::String
+				name = ':' + name if ':' != name[0]
+			when ::Symbol
+				name = ':' + name.to_s
+			else
+			end
+		end
+
 
 		# nil check
 
@@ -481,3 +518,4 @@ 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:      16th December 2017
+# Updated:      21st December 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.18.1'
+	VERSION				=	'0.19.3'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/extensions/test/ts_all.rb

@@ -0,0 +1,12 @@
+#! /usr/bin/env ruby
+#
+# executes all other tests
+
+this_dir    =   File.expand_path(File.dirname(__FILE__))
+
+# all tc_*rb in current directory
+Dir[File.join(this_dir, 'tc_*rb')].each { |file| require file }
+
+# all ts_*rb in immediate sub-directories
+Dir[File.join(this_dir, '*', 'ts_*rb')].each { |file| require file }
+

data/test/unit/extensions/test/unit/tc_assert_subclass_of.rb

@@ -0,0 +1,24 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..']*5), 'lib')
+
+require 'xqsr3/extensions/test/unit/assert_subclass_of'
+
+require 'test/unit'
+
+class Test_assert_subclass_of < Test::Unit::TestCase
+
+	class Grandparent; end
+	class Parent < Grandparent; end
+	class Child < Parent; end
+
+	def test_1
+
+		assert_subclass_of Object, Grandparent
+		assert_subclass_of Grandparent, Parent
+		assert_subclass_of Parent, Child
+		assert_subclass_of Grandparent, Child
+	end
+end
+
+

data/test/unit/extensions/test/unit/tc_assert_superclass_of.rb

@@ -0,0 +1,24 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..']*5), 'lib')
+
+require 'xqsr3/extensions/test/unit/assert_superclass_of'
+
+require 'test/unit'
+
+class Test_assert_superclass_of < Test::Unit::TestCase
+
+	class Grandparent; end
+	class Parent < Grandparent; end
+	class Child < Parent; end
+
+	def test_1
+
+		assert_superclass_of Grandparent, Object
+		assert_superclass_of Parent, Grandparent
+		assert_superclass_of Child, Parent
+		assert_superclass_of Child, Grandparent
+	end
+end
+
+

data/test/unit/extensions/test/unit/ts_all.rb

@@ -0,0 +1,12 @@
+#! /usr/bin/env ruby
+#
+# executes all other tests
+
+this_dir    =   File.expand_path(File.dirname(__FILE__))
+
+# all tc_*rb in current directory
+Dir[File.join(this_dir, 'tc_*rb')].each { |file| require file }
+
+# all ts_*rb in immediate sub-directories
+Dir[File.join(this_dir, '*', 'ts_*rb')].each { |file| require file }
+

data/test/unit/quality/tc_parameter_checking.rb

@@ -327,5 +327,116 @@ end
 			self.class.check_method_type_class :sym, ::String
 		end
 	end
+
+
+	# test treat_as_option
+
+	def check_method_tao_1 h, o, options = {}, &block
+
+		check_parameter h[o], o, options.merge({ treat_as_option: true }), &block
+	end
+
+	def test_tao_1
+
+		assert_true check_method_tao_1({ thing: true }, :thing)
+		assert_false check_method_tao_1({ thing: false }, :thing)
+		assert_equal [], check_method_tao_1({ thing: [] }, :thing)
+
+		begin
+			check_method_tao_1({ thing: true }, :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
+
+		begin
+			check_method_tao_1({ thing: true }, '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
+
+		begin
+			check_method_tao_1({ thing: true }, ':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
+	end
+
+
+	# test treat_as_option
+
+	def check_method_tao_2 h, o, options = {}, &block
+
+		check_option h, o, options.merge({ }), &block
+	end
+
+	def check_method_tao_class_2 h, o, options = {}, &block
+
+		check_option h, o, options.merge({ }), &block
+	end
+
+	def test_tao_2
+
+		assert_true check_method_tao_2({ thing: true }, :thing)
+		assert_false check_method_tao_2({ thing: false }, :thing)
+		assert_equal [], check_method_tao_2({ thing: [] }, :thing)
+
+		assert_true check_method_tao_class_2({ thing: true }, :thing)
+		assert_false check_method_tao_class_2({ thing: false }, :thing)
+		assert_equal [], check_method_tao_class_2({ thing: [] }, :thing)
+
+		begin
+			check_method_tao_2({ thing: true }, :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
+
+		begin
+			check_method_tao_2({ thing: true }, '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
+
+		begin
+			check_method_tao_2({ thing: true }, ':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
+	end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.19.3
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-17 00:00:00.000000000 Z
+date: 2017-12-21 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -52,6 +52,8 @@ files:
 - lib/xqsr3/extensions/test/unit/assert_false.rb
 - lib/xqsr3/extensions/test/unit/assert_not.rb
 - lib/xqsr3/extensions/test/unit/assert_not_eql.rb
+- lib/xqsr3/extensions/test/unit/assert_subclass_of.rb
+- lib/xqsr3/extensions/test/unit/assert_superclass_of.rb
 - lib/xqsr3/extensions/test/unit/assert_true.rb
 - lib/xqsr3/extensions/test/unit.rb
 - lib/xqsr3/hash_utilities/deep_transform.rb
@@ -96,6 +98,10 @@ files:
 - test/unit/extensions/string/tc_starts_with.rb
 - test/unit/extensions/string/tc_to_symbol.rb
 - test/unit/extensions/string/ts_all.rb
+- test/unit/extensions/test/ts_all.rb
+- test/unit/extensions/test/unit/tc_assert_subclass_of.rb
+- test/unit/extensions/test/unit/tc_assert_superclass_of.rb
+- test/unit/extensions/test/unit/ts_all.rb
 - test/unit/extensions/ts_all.rb
 - test/unit/hash_utilities/tc_has_match.rb
 - test/unit/hash_utilities/tc_match.rb