xqsr3 0.12.2 → 0.13.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44bdb62fca711d8ee10e0da50888cae988043f26
-  data.tar.gz: 22b017fcf0f07ef6395c123d4ed81650d27d3967
+  metadata.gz: a62fcdc4c1aa7176aa20acf04a477f9ce9e32dde
+  data.tar.gz: 9e3085307d16b630cbe34d5e7d243b4f3ec18622
 SHA512:
-  metadata.gz: 49916563cc5b10a5103716b0555d8d2dcea1b38481d8d6b7bdf951834505a10a79aac39f8e5c6bbba513966da207f2a2f57e90aef7fa28e1563a39d6a68ab453
-  data.tar.gz: 3e03a355c86b3227d7a9c5f4966c99f55c3ab5953569becc6f2d1696ff08ee1de5ab7a9fbc9c76dd598159846b48aa3e113fe211a529f1c8142980686897be77
+  metadata.gz: 947e35e638cbd5ce7bdef5811d8c3f9de6923f697aff9212f371fda83b049b4032dd7f789f7183720c53714967c13e5ce62501071dbc11c93bb85a06adea8e41
+  data.tar.gz: b458cea2b2fb99ceb8a42b5262f6556fa926aecb2c2489212ede046d503d82a60acc1fb735049bf5e4eff8815aee6caab20dc23f71abae962f560bb12b4b4f3c

data/lib/xqsr3/command_line_utilities/map_option_string.rb

@@ -2,17 +2,17 @@
 # ######################################################################## #
 # File:         lib/xqsr3/command_line_utilities/map_option_string.rb
 #
-# Purpose:      Definition of the ::Xqsr3::CommandLineUtilities::ToSymbol
-#               module
+# Purpose:      Definition of the
+#               ::Xqsr3::CommandLineUtilities::MapOptionString module
 #
 # Created:      15th April 2016
-# Updated:      10th June 2016
+# Updated:      2nd August 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2016-2017, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -45,6 +45,8 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::CommandLineUtilities::MapOptionString
 
 require 'xqsr3/string_utilities/to_symbol'
 

data/lib/xqsr3/containers/frequency_map.rb

@@ -5,13 +5,13 @@
 # Purpose:      FrequencyMap container
 #
 # Created:      28th January 2005
-# Updated:      10th June 2016
+# Updated:      30th July 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2005-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2005-2017, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -44,6 +44,9 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::Containers::FrequencyMap
+
 =begin
 =end
 

data/lib/xqsr3/containers/multi_map.rb

@@ -5,13 +5,13 @@
 # Purpose:      multimap container
 #
 # Created:      21st March 2007
-# Updated:      2nd October 2016
+# Updated:      30th July 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2017, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -44,6 +44,9 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::Containers::MultiMap
+
 =begin
 =end
 

data/lib/xqsr3/conversion/bool_parser.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      7th June 2017
+# Updated:      28th July 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -46,7 +46,7 @@
 
 
 # ##########################################################
-# ::Xqsr3::Conversion::ToBool
+# ::Xqsr3::Conversion::BoolParser
 
 =begin
 =end
@@ -116,5 +116,3 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
-
-

data/lib/xqsr3/diagnostics/exception_utilities.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ExceptionUtilities module
 #
 # Created:      12th February 2015
-# Updated:      22nd June 2017
+# Updated:      2nd August 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -44,6 +44,9 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::Diagnostics::ExceptionUtilities
+
 =begin
 =end
 

data/lib/xqsr3/hash_utilities/deep_transform.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      3rd June 2017
-# Updated:      22nd June 2017
+# Updated:      28th July 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -152,4 +152,3 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
-

data/lib/xqsr3/io/writelines.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a writelines() method to the IO module
 #
 # Created:      13th April 2007
-# Updated:      10th June 2016
+# Updated:      2nd August 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2017, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -44,6 +44,9 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::IO
+
 require 'xqsr3/quality/parameter_checking'
 
 =begin

data/lib/xqsr3/quality/parameter_checking.rb

@@ -5,7 +5,7 @@
 # Purpose:      Definition of the ParameterChecking module
 #
 # Created:      12th February 2015
-# Updated:      26th February 2017
+# Updated:      1st November 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -44,6 +44,9 @@
 # ######################################################################## #
 
 
+# ##########################################################
+# ::Xqsr3::Quality::ParameterChecking
+
 =begin
 =end
 
@@ -69,8 +72,32 @@ module ParameterChecking
 			end
 		end
 	end # module Util_
-
 	public
+
+	def self.included base
+
+		base.extend self
+
+		base.class_eval do
+
+			public
+			def self.check_parameter value, name, options = {}, &block
+
+				Util_.check_parameter value, name, options, &block
+			end
+
+			# @see check_parameter
+			#
+			# @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
+			end
+		end
+	end
+
 	# Check a given parameter (value=+value+, name=+name+) for type and value
 	#
 	# @param +value+ the parameter whose value and type is to be checked
@@ -83,6 +110,8 @@ module ParameterChecking
 	#          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
@@ -96,8 +125,70 @@ module ParameterChecking
 	#          exception, which suppresses internal message preparation
 	# @option +:treat_as_option+ 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
+	end
+
+	# @see check_parameter
+	#
+	# @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
+
+	# 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?+
+	#          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
+	def self.check_parameter value, name, options = {}, &block
+
+		Util_.check_parameter value, name, options, &block
+	end
+
+	# @see check_parameter
+	#
+	# @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
+	end
+
+	private
+	def Util_.check_parameter value, name, options, &block
+
 		failed_check	=	false
 		options			||=	{}
 		message			=	options[:message]
@@ -140,6 +231,10 @@ module ParameterChecking
 			# types
 
 			types		=	options[:types] || []
+			if options.has_key? :type
+
+				types	<<	options[:type] if types.empty?
+			end
 			types		=	[value.class] if types.empty?
 
 			warn "#{self}::check_parameter: options[:types] of type #{types.class} - should be #{::Array}" unless types.is_a?(Array)
@@ -311,13 +406,19 @@ module ParameterChecking
 
 		if value and block
 
-			warn "#{self}::check_parameter: block arity must be 1" unless block.arity == 1
+			warn "#{self}::check_parameter: block arity must be 1 or 2" unless (1..2).include? block.arity
 
 			r	=	nil
 
 			begin
 
-				r = block.call(value)
+				if 1 == block.arity
+
+					r = block.call(value)
+				else
+
+					r = block.call(value, options)
+				end
 
 			rescue StandardError => x
 
@@ -392,10 +493,6 @@ module ParameterChecking
 		failed_check ? nil : return_value
 	end
 
-	alias check_param check_parameter
-
-	module_function :check_parameter
-
 end # module ParameterChecking
 
 end # module Quality

data/lib/xqsr3/version.rb

@@ -5,7 +5,7 @@
 # Purpose:      Version for Xqsr3 library
 #
 # Created:      3rd April 2016
-# Updated:      22nd June 2017
+# Updated:      1st November 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.12.2'
+	VERSION				=	'0.13.3'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/lib/xqsr3/xml/utilities/compare.rb

@@ -0,0 +1,466 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/xml/_utilities/compare.rb
+#
+# Purpose:      Definition of the ::Xqsr3::XML::Utilities::Compare
+#               module
+#
+# Created:      30th July 2017
+# Updated:      1st November 2017
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017, 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::XML::Utilities::Compare
+
+=begin
+=end
+
+require 'xqsr3/quality/parameter_checking'
+
+require 'nokogiri'
+
+module Xqsr3
+module XML
+module Utilities
+
+module Compare
+
+	# Class that represents the result of an XML comparison
+	#
+	# NOTE: Sadly, we cannot create instances of +FalseClass+/+TrueClass+,
+	# to which we could then add a +reason+ attribute, so instead we must
+	# have a results class
+	class Result
+
+		include ::Xqsr3::Quality::ParameterChecking
+
+		protected :check_parameter
+
+		#
+		# Options:
+		#
+		# +:different_attributes+
+		# +:different_attribute_count+
+		# +:different_attribute_order+
+		# +:different_child_node_count+
+		# +:different_child_node_order+
+		# +:different_child_nodes+
+		# +:different_node_names+
+		# +:different_node_contents+
+		# +:parameter_is_empty+
+		# +:parameter_is_nil+
+		# +:+
+
+		def initialize status, reason, **options
+
+			check_parameter status, 'status', types: [ ::FalseClass, ::TrueClass ]
+			check_parameter reason, 'reason', type: ::Symbol, allow_nil: true
+
+			@status		=	status
+			@reason		=	reason
+
+			@lhs_node	=	options[:lhs_node]
+			@rhs_node	=	options[:rhs_node]
+		end
+
+		def self.return status, reason, **options
+
+			return self.new status, reason, **options
+		end
+
+		def self.same reason = nil, **options
+
+			return self.new true, reason, **options
+		end
+
+		def self.different reason, **options
+
+			return self.new false, reason, **options
+		end
+
+		attr_reader	:status
+		attr_reader	:reason
+
+		def different?
+
+			!status
+		end
+
+		def same?
+
+			status
+		end
+
+		def details
+
+			r	=	reason.to_s.gsub /_/, ' '
+
+			qualifying	=	''
+
+			if @lhs_node
+
+				qualifying	+=	'; ' unless qualifying.empty?
+				qualifying	+=	"lhs-node=#{@lhs_node}"
+			end
+
+			if @rhs_node
+
+				qualifying	+=	'; ' unless qualifying.empty?
+				qualifying	+=	"rhs-node=#{@rhs_node}"
+			end
+
+			r = "#{r}: #{qualifying}" unless qualifying.empty?
+
+			r
+		end
+	end
+
+	module Internal_Compare_
+
+		extend ::Xqsr3::Quality::ParameterChecking
+
+		DEFAULT_OPTIONS = {
+
+			debug: false,
+#			element_order: false,
+			equate_nil_and_empty: false,
+			ignore_attributes: false,
+			ignore_attribute_order: true,
+			ignore_child_node_order: true,
+			normalise_whitespace: true,
+#			normalize_whitespace: true,
+			validate_params: true,
+		}
+
+		ORDER_OPTIONS_SYMBOLS = [
+
+			:element_order,
+			:ignore_attribute_order,
+			:ignore_child_node_order,
+		]
+
+		WHITESPACE_OPTIONS_SYMBOLS = [
+
+			:normalise_whitespace,
+			:normalize_whitespace,
+		]
+
+		def self.derive_options_ given_options
+
+			default_options	=	DEFAULT_OPTIONS
+			derived_options	=	{}.merge given_options
+
+
+			# sort whitespace
+
+			if WHITESPACE_OPTIONS_SYMBOLS.any? { |sym| given_options.has_key? sym }
+
+				default_options	=	default_options.reject { |k, v| WHITESPACE_OPTIONS_SYMBOLS.include? k }
+			end
+
+			if given_options.has_key? :normalise_whitespace
+
+				derived_options.delete :normalize_whitespace
+			elsif given_options.has_key? :normalize_whitespace
+
+				derived_options[:normalise_whitespace] = given_options[:normalize_whitespace]
+
+				derived_options.delete :normalize_whitespace
+			end
+
+
+			# sort element-order
+
+			if ORDER_OPTIONS_SYMBOLS.any? { |sym| given_options.has_key? sym }
+
+				default_options	=	default_options.reject { |k, v| ORDER_OPTIONS_SYMBOLS.include? k }
+			end
+
+			if given_options.has_key? :element_order
+
+				element_order	=	given_options[:element_order]
+
+				derived_options[:ignore_attribute_order]	=	!element_order
+				derived_options[:ignore_child_node_order]	=	!element_order
+			end
+
+			derived_options[:ignore_attribute_order]	=	given_options[:ignore_attribute_order] if given_options.has_key? :ignore_attribute_order
+			derived_options[:ignore_child_node_order]	=	given_options[:ignore_child_node_order] if given_options.has_key? :ignore_child_node_order
+
+			default_options.merge derived_options
+		end
+
+		def self.one_line_ s
+
+			s = s.to_s.gsub(/\s+/, ' ')
+		end
+
+		#
+		# +:debug+
+		# +:element_order+
+		# +:equate_nil_and_empty+
+		# +:ignore_attributes+
+		# +:ignore_attribute_order+
+		# +:normalise_whitespace+
+		# +:normalize_whitespace+
+		# +:validate_params+
+		#
+
+		def self.xml_compare_ lhs, rhs, options
+
+			$stderr.puts "#{self}#{__method__}(lhs (#{lhs.class})=#{self.one_line_ lhs}, rhs (#{rhs.class})=#{self.one_line_ rhs}, options (#{options.class})=#{options})" if $DEBUG
+
+			# validate parameter(s)
+
+			check_parameter options, 'options', type: ::Hash if $DEBUG
+
+			validate_params	=	$DEBUG || options[:debug] || options[:validate_params]
+
+			check_parameter lhs, 'lhs', types: [ ::String, ::Nokogiri::XML::Node ], allow_nil: true if validate_params
+			check_parameter rhs, 'rhs', types: [ ::String, ::Nokogiri::XML::Node ], allow_nil: true if validate_params
+
+			options			=	self.derive_options_ options
+
+			# deal with nil(s)
+
+			return Result.same if lhs.nil? && rhs.nil?
+
+			if lhs.nil?
+
+				return Result.same if options[:equate_nil_and_empty] && ::String === rhs && rhs.empty?
+
+				return Result.different :parameter_is_nil
+			end
+
+			if rhs.nil?
+
+				return Result.same if options[:equate_nil_and_empty] && ::String === lhs && lhs.empty?
+
+				return Result.different :parameter_is_nil
+			end
+
+
+			# deal with string(s)
+
+			lhs	=	Nokogiri::XML(lhs) if ::String === lhs
+			rhs	=	Nokogiri::XML(rhs) if ::String === rhs
+
+
+			self.xml_compare_nodes_ lhs, rhs, options
+		end
+
+		def self.xml_compare_nodes_ lhs, rhs, options
+
+			$stderr.puts "#{self}#{__method__}(lhs (#{lhs.class})=#{self.one_line_ lhs}, rhs (#{rhs.class})=#{self.one_line_ rhs}, options (#{options.class})=#{options})" if $DEBUG
+
+
+			# Compare:
+			#
+			# - name
+			# - attributes
+			# - content
+			# - children
+			# - 
+
+
+			# ##########################
+			# name
+
+			lhs_name	=	lhs.name
+			rhs_name	=	rhs.name
+
+			return Result.different :different_node_names, lhs_node: lhs, rhs_node: rhs if lhs_name != rhs_name
+
+
+			# ##########################
+			# attributes
+
+			unless options[:ignore_attributes]
+
+				lhs_attributes	=	lhs.attribute_nodes
+				rhs_attributes	=	rhs.attribute_nodes
+
+				return Result.different :different_attribute_count, lhs_node: lhs, rhs_node: rhs if lhs_attributes.count != rhs_attributes.count
+
+
+				lhs_attr_list	=	lhs_attributes.map { |attr| [ attr.name, attr.content ] }
+				rhs_attr_list	=	rhs_attributes.map { |attr| [ attr.name, attr.content ] }
+
+				if lhs_attr_list != rhs_attr_list
+
+					# do the sort first
+
+					lhs_attr_list.sort! { |l, r| l[0] <=> r[0] }
+					rhs_attr_list.sort! { |l, r| l[0] <=> r[0] }
+
+					# Now there are four possibiliies:
+					#
+					# 1. Different attributes
+					# 2. Different attribute order
+					# 3. Same (when reordered)
+
+					if lhs_attr_list == rhs_attr_list
+
+						if options[:ignore_attribute_order]
+
+							# 3
+						else
+
+							# 2
+
+							return Result.different :different_attribute_order, lhs_node: lhs, rhs_node: rhs
+						end
+					else
+
+						return Result.different :different_attributes, lhs_node: lhs, rhs_node: rhs
+					end
+				end
+			end
+
+			# ##########################
+			# content
+
+			normalise_ws	=	options[:normalise_whitespace]
+
+			lhs_content	=	normalise_ws ? lhs.content.gsub(/\s+/, ' ').strip : lhs.content
+			rhs_content	=	normalise_ws ? rhs.content.gsub(/\s+/, ' ').strip : rhs.content
+
+			return Result.different :different_node_contents, lhs_node: lhs, rhs_node: rhs if lhs_content != rhs_content
+
+
+			# ##########################
+			# children (preparation)
+
+			lhs_children		=	lhs.children.to_a
+			rhs_children		=	rhs.children.to_a
+
+			lhs_children.reject! { |child| child.text? && child.content.strip.empty? }
+			rhs_children.reject! { |child| child.text? && child.content.strip.empty? }
+
+
+			# ##########################
+			# children - count
+
+			lhs_children_count	=	lhs_children.count
+			rhs_children_count	=	rhs_children.count
+
+			return Result.different :different_child_node_count, lhs_node: lhs, rhs_node: rhs if lhs_children_count != rhs_children_count
+
+
+			# ##########################
+			# children - names
+
+			lhs_children_names	=	lhs_children.map { |ch| ch.name }
+			rhs_children_names	=	rhs_children.map { |ch| ch.name }
+
+			if lhs_children_names != rhs_children_names
+
+				# At this point, the lists of names of child elements are
+				# different. This may be because there are different
+				# elements or because they are in a different order. Either
+				# way, in order to provide detailed reasons for
+				# inequivalency, we must do an order-independent comparison
+
+				children_sorted_lhs	=	lhs_children.sort { |x, y| x.name <=> y.name }
+				children_sorted_rhs	=	rhs_children.sort { |x, y| x.name <=> y.name }
+
+				ch_names_sorted_lhs	=	children_sorted_lhs.map { |ch| ch.name }
+				ch_names_sorted_rhs	=	children_sorted_rhs.map { |ch| ch.name }
+
+				ignore_order		=	options[:ignore_child_node_order]
+
+				if ignore_order
+
+					return Result.different :different_child_nodes, lhs_node: lhs, rhs_node: rhs if ch_names_sorted_lhs != ch_names_sorted_rhs
+
+					# Since they are the same (when reordered), we need to
+					# adopt the ordered sequences so that the comparison of
+					# the children are meaningful
+
+					lhs_children	=	children_sorted_lhs
+					rhs_children	=	children_sorted_rhs
+				else
+
+					# failed, so need to determine whether it's due to
+					# different nodes or different order
+
+					if ch_names_sorted_lhs == ch_names_sorted_rhs
+
+						return Result.different :different_child_node_order, lhs_node: lhs, rhs_node: rhs
+					else
+
+						return Result.different :different_child_nodes, lhs_node: lhs, rhs_node: rhs
+					end
+				end
+			end
+
+			(0 ... lhs_children.count).each do |index|
+
+				ch_lhs	=	lhs_children[index]
+				ch_rhs	=	rhs_children[index]
+
+				r = self.xml_compare_nodes_ ch_lhs, ch_rhs, options
+
+				return r unless r.status
+			end
+
+			return Result.same
+		end
+	end
+
+	def self.xml_compare lhs, rhs, **options
+
+		$stderr.puts "#{self}#{__method__}(lhs (#{lhs.class})=#{Internal_Compare_.one_line_ lhs}, rhs (#{rhs.class})=#{Internal_Compare_.one_line_ rhs}, options (#{options.class})=#{options})" if $DEBUG
+
+		Internal_Compare_.xml_compare_ lhs, rhs, options
+	end
+
+	def xml_compare lhs, rhs, **options
+
+		$stderr.puts "#{self}#{__method__}(lhs (#{lhs.class})=#{Internal_Compare_.one_line_ lhs}, rhs (#{rhs.class})=#{Internal_Compare_.one_line_ rhs}, options (#{options.class})=#{options})" if $DEBUG
+
+		Internal_Compare_.xml_compare_ lhs, rhs, options
+	end
+
+end # module Compare
+
+end # module Utilities
+end # module XML
+end # module Xqsr3
+

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

@@ -58,8 +58,7 @@ class Test_String_ends_with < Test::Unit::TestCase
 		prefixes = %w{ a c def }
 
 		assert_not ''.ends_with?(*prefixes)
-		assert_nil ''.ends_with?(*prefixes)
-		assert ''.ends_with?(*prefixes), ''
+		assert_nil ''.ends_with?(*prefixes), 'empty string does not yield nil with given non-empty prefix(es)'
 		assert 'abc'.ends_with?(*prefixes)
 		assert_not 'd'.ends_with?(*prefixes)
 		assert_nil 'd'.ends_with?(*prefixes)

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

@@ -59,7 +59,6 @@ class Test_String_starts_with < Test::Unit::TestCase
 
 		assert_not ''.starts_with?(*prefixes)
 		assert_nil ''.starts_with?(*prefixes)
-		assert ''.starts_with?(*prefixes), ''
 		assert 'abc'.starts_with?(*prefixes)
 		assert_not 'd'.starts_with?(*prefixes)
 		assert_nil 'd'.starts_with?(*prefixes)

data/test/unit/quality/tc_parameter_checking.rb

@@ -12,7 +12,7 @@ class Test_parameter_checks_as_separate_module < Test::Unit::TestCase
 	end
 	include TestConstants
 
-	extend ::Xqsr3::Quality::ParameterChecking
+	include ::Xqsr3::Quality::ParameterChecking
 
 
 	# test 1
@@ -239,5 +239,24 @@ end
 			check_responds_to Hash.new, [ :this_is_not_a_Hash_method ]
 		end
 	end
+
+
+
+	# test type:
+
+	def check_method_type a, type
+
+		self.class.check_parameter a, 'a', type: type
+	end
+
+	def test_type
+
+		check_method_type '', ::String
+
+		assert_raise TypeError do
+
+			check_method_type :sym, ::String
+		end
+	end
 end
 

data/test/unit/xml/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/xml/utilities/tc_compare.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
+
+require 'xqsr3/xml/utilities/compare'
+
+require 'xqsr3/extensions/test/unit'
+require 'test/unit'
+
+class Test_Xqsr3_XML_Utilities_Compare < Test::Unit::TestCase
+
+	include ::Xqsr3::XML::Utilities::Compare
+
+	def test_compare_nil
+
+		assert xml_compare(nil, nil).same?
+
+		assert_false xml_compare('', nil).same?
+		assert_false xml_compare(nil, '').same?
+
+		assert xml_compare('', nil, equate_nil_and_empty: true).same?
+		assert xml_compare(nil, '', equate_nil_and_empty: true).same?
+	end
+
+	def test_compare_empty
+
+		assert xml_compare('', '').same?
+
+		assert_false xml_compare('<abc/>', '').same?
+		assert_false xml_compare('', '<abc/>').same?
+	end
+
+	def test_compare_one_level_1
+
+		assert xml_compare('<abc/>', '<abc/>').same?
+		assert xml_compare('<abc/>', '<abc></abc>').same?
+		assert_false xml_compare('<abc/>', '<def/>').same?
+	end
+
+	def test_compare_two_level_1
+
+		assert xml_compare('<parent><child1></child1></parent>', '<parent><child1></child1></parent>').same?
+		assert xml_compare('<parent><child1/></parent>', '<parent><child1></child1></parent>').same?
+
+		r = xml_compare('<parent><child1/></parent>', '<parent><child2/></parent>')
+
+		assert_false r.same?
+	end
+
+	def test_compare_attributes_1
+
+		lhs		=	<<END_OF_lhs
+<node name="John Smith" age="21" />
+END_OF_lhs
+
+		rhs_same	=	<<END_OF_lhs
+<node age="21" name="John Smith" />
+END_OF_lhs
+
+		rhs_diff	=	<<END_OF_lhs
+<node name="John Smith" age="22" />
+END_OF_lhs
+
+		r			=	xml_compare lhs, rhs_same, ignore_attribute_order: false
+
+		assert r.different?, r.details
+		assert_equal :different_attribute_order, r.reason
+
+		r			=	xml_compare lhs, rhs_same, ignore_attribute_order: true
+
+		assert r.same?
+
+		r			=	xml_compare lhs, rhs_same, element_order: false
+
+		assert r.same?
+
+		r			=	xml_compare lhs, rhs_diff
+
+		assert r.different?
+		assert_equal :different_attributes, r.reason
+	end
+
+	def test_compare_two_level_2
+
+		lhs		=	<<END_OF_lhs
+<parent>
+ <child1/>
+</parent>
+END_OF_lhs
+		rhs		=	<<END_OF_rhs
+<parent>
+ <child1>
+ </child1>
+</parent>
+END_OF_rhs
+
+		r		=	xml_compare lhs, rhs, normalize_whitespace: false
+
+		assert r.different?, "#{r.details}"
+		assert_equal :different_node_contents, r.reason
+
+		r		=	xml_compare(lhs, rhs, normalize_whitespace: true)
+
+		assert r.same?, "#{r.details}"
+	end
+
+	def test_compare_two_level_3
+
+		lhs		=	<<END_OF_lhs
+<parent>
+ <child1/>
+ <child2>
+  <grandchild2a/>
+ </child2>
+</parent>
+END_OF_lhs
+		rhs		=	<<END_OF_rhs
+<parent>
+ <child2><grandchild2a/></child2>
+ <child1>
+ </child1>
+</parent>
+END_OF_rhs
+
+		r		=	xml_compare lhs, rhs, normalize_whitespace: true
+
+		assert r.same?, "#{r.details}"
+	end
+
+end
+

data/test/unit/xml/utilities/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 }
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.3
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-22 00:00:00.000000000 Z
+date: 2017-11-15 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -57,6 +57,7 @@ files:
 - lib/xqsr3/string_utilities/starts_with.rb
 - lib/xqsr3/string_utilities/to_symbol.rb
 - lib/xqsr3/version.rb
+- lib/xqsr3/xml/utilities/compare.rb
 - test/unit/command_line_utilities/tc_map_option_string.rb
 - test/unit/command_line_utilities/ts_all.rb
 - test/unit/containers/tc_frequency_map.rb
@@ -89,6 +90,9 @@ files:
 - test/unit/quality/ts_all.rb
 - test/unit/tc_version.rb
 - test/unit/ts_all.rb
+- test/unit/xml/ts_all.rb
+- test/unit/xml/utilities/tc_compare.rb
+- test/unit/xml/utilities/ts_all.rb
 homepage: http://github.com/synesissoftware/xqsr3
 licenses:
 - 3-clause BSD