xqsr3-xml 0.1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1995665f234ee13f105bf6316a5ff88c91d49a22
+  data.tar.gz: f75620b304904ff142f92ef8576cc32b7ce1bba1
+SHA512:
+  metadata.gz: 9719a1c7e803abf401646f4934d06231ff06cb0f371921d1cae3e442fd7408d7197e0ea3bafa03524f230a71638ff7f2ded0beabdfb449befe7e31c3aff0ed76
+  data.tar.gz: 9fad44e02ea4784441a2e170f476e7f593799339354ab05d7cb861b89c355b8d1a376c7b3b345457a1c69f408e6c10b146da60e90107140abbad9fc39d82e01f

data/LICENSE

@@ -0,0 +1,29 @@
+xqsr3-xml
+
+Copyright (c) 2005-2016, 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 xqsr3 and xqsr3-xml 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.

data/README.md

@@ -0,0 +1,60 @@
+# xqsr3-xml
+e**X**tensions by fine **Q**uantum for **S**tandard **R**uby and **3**rd-party libraries, for **XML**
+
+[![Gem Version](https://badge.fury.io/rb/xqsr3-xml.svg)](https://badge.fury.io/rb/xqsr3-xml)
+
+## Introduction
+
+[**xqsr3**](https://github.com/synesissoftware/xqsr3/) is a lightweight, low-coupling library of assorted extensions to standard ruby and 3rd-party libraries. As of version **0.31** of **xqsr3**, the **XML Utilites** components were moved out into **xqsr3-xml** in order that the core **xqsr** can be independent of any non-standard libraries.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Components](#components)
+4. [Project Information](#project-information)
+
+## Installation
+
+Install using `gem install xqsr3-xml` or add it to your `Gemfile`.
+
+## Components
+
+**xqsr3** provides components in the following categories:
+
+* Array Utilities
+* Command-line Utilities
+* Containers
+* Conversion
+* Diagnostics
+* Hash Utilities
+* IO
+* Quality
+* String Utilities
+
+**xqsr3-xml** provides components in the following categories:
+
+* XML Utilities
+
+## Project Information
+
+### Where to get help
+
+[GitHub Page](https://github.com/synesissoftware/xqsr3-xml "GitHub Page")
+
+### Contribution guidelines
+
+Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/xqsr3-xml.
+
+### Dependencies
+
+* [**Nokogiri**](http://nokogiri.org/)
+* [**xqsr3**](https://github.com/synesissoftware/xqsr3/)
+
+### Related projects
+
+* [**xqsr3**](https://github.com/synesissoftware/xqsr3/)
+
+### License
+
+**xqsr3-xml** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.

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

@@ -0,0 +1,544 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/xml/_utilities/compare.rb
+#
+# Purpose:      Definition of the ::Xqsr3::XML::Utilities::Compare
+#               module
+#
+# Created:      30th July 2017
+# Updated:      16th 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::XML::Utilities::Compare
+
+=begin
+=end
+
+require 'xqsr3/xml/utilities/navigation'
+
+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
+
+			@call_stack	=	caller(2)
+
+			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 :call_stack
+		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
+
+		def to_s
+
+			return 'same' if same?
+
+			"different, because: #{details}"
+		end
+	end
+
+	module Internal_Compare_
+
+		include ::Xqsr3::XML::Utilities::Navigation
+
+		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,
+			ignore_content: false,
+			ignore_content_case: false,
+			ignore_xml_declarations: true,
+			normalise_whitespace: true,
+#			normalize_whitespace: true,
+			validate_params: true,
+		}
+
+		ORDER_OPTIONS_SYMBOLS = [
+
+			:element_order,
+			:ignore_attribute_order,
+			:ignore_child_node_order,
+			:ignore_content,
+			:ignore_content_case,
+		]
+
+		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+
+		# +:ignore_xml_declarations+
+		# +: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
+
+
+
+			# deal with XML Declaration(s)
+
+			if options[:ignore_xml_declarations]
+
+				if ::Nokogiri::XML::Document === lhs
+
+					lhs_root	=	lhs.root
+					lhs			=	lhs_root if lhs_root
+				end
+
+				if ::Nokogiri::XML::Document === rhs
+
+					rhs_root	=	rhs.root
+					rhs			=	rhs_root if rhs_root
+				end
+			end
+
+
+			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
+
+			unless options[:ignore_content]
+
+				lhs_texts		=	self.get_descendants(lhs).select { |el| el.text? }.map { |el| el.content }
+				rhs_texts		=	self.get_descendants(rhs).select { |el| el.text? }.map { |el| el.content }
+
+				content_same	=	lhs_texts == rhs_texts
+
+				unless content_same
+
+					if options[:normalise_whitespace]
+
+						lhs_texts		=	lhs_texts.reject { |s| s.strip.empty? }
+						rhs_texts		=	rhs_texts.reject { |s| s.strip.empty? }
+
+						content_same	=	lhs_texts == rhs_texts
+					end
+				end
+
+				unless content_same
+
+					if options[:ignore_content_case]
+
+						lhs_texts		=	lhs_texts.reject { |s| s.downcase }
+						rhs_texts		=	rhs_texts.reject { |s| s.downcase }
+
+						content_same	=	lhs_texts == rhs_texts
+					end
+				end
+
+				unless content_same
+
+					if options[:ignore_child_node_order]
+
+						lhs_texts		=	lhs_texts.sort
+						rhs_texts		=	rhs_texts.sort
+
+						content_same	=	lhs_texts == rhs_texts
+					end
+				end
+
+				return Result.different :different_node_contents, lhs_node: lhs, rhs_node: rhs unless content_same
+			end
+
+
+			# ##########################
+			# 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
+
+# ############################## end of file ############################# #
+
+

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

@@ -0,0 +1,108 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/xml/_utilities/navigation.rb
+#
+# Purpose:      Definition of the ::Xqsr3::XML::Utilities::Navigation
+#               module
+#
+# Created:      7th August 2018
+# Updated:      7th August 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::XML::Utilities::Navigation
+
+=begin
+=end
+
+require 'xqsr3/quality/parameter_checking'
+
+require 'nokogiri'
+
+module Xqsr3
+module XML
+module Utilities
+
+module Navigation
+
+	module Internal_Compare_
+
+		extend ::Xqsr3::Quality::ParameterChecking
+
+		def self.get_descendants node
+
+			descendants	=	[]
+
+			node.children.each do |child|
+
+				descendants	<<	child
+
+				descendants	+=	self.get_descendants child
+			end
+
+			descendants
+		end
+	end # module Internal_Compare_
+
+	def self.included receiver
+
+		def receiver.get_descendants node
+
+			Internal_Compare_.get_descendants node
+		end
+	end
+
+	def self.get_descendants node
+
+		Internal_Compare_.get_descendants node
+	end
+
+	def get_descendants
+
+		Internal_Compare_.get_descendants self
+	end
+end # module Navigation
+
+end # module Utilities
+end # module XML
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/lib/xqsr3/xml/version.rb

@@ -0,0 +1,71 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/xml/version.rb
+#
+# Purpose:      Version for xqsr3-xml library
+#
+# Created:      1st March 2019
+# Updated:      2nd March 2019
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2019, 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.
+#
+# ######################################################################## #
+
+
+=begin
+=end
+
+module Xqsr3
+module XML
+
+	# Current version of the Xqsr3 library
+	VERSION				=	'0.1.0.1'
+
+	private
+	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
+	public
+	# Major version of the Xqsr3 library
+	VERSION_MAJOR		=	VERSION_PARTS_[0] # :nodoc:
+	# Minor version of the Xqsr3 library
+	VERSION_MINOR		=	VERSION_PARTS_[1] # :nodoc:
+	# Revision version of the Xqsr3 library
+	VERSION_REVISION	=	VERSION_PARTS_[2] # :nodoc:
+
+end # module XML
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/test/unit/tc_version.rb

@@ -0,0 +1,36 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../lib')
+
+require 'xqsr3/xml/version'
+
+require 'test/unit'
+
+class Test_version < Test::Unit::TestCase
+
+	def test_has_VERSION
+
+		assert defined? Xqsr3::XML::VERSION
+	end
+
+	def test_has_VERSION_MAJOR
+
+		assert defined? Xqsr3::XML::VERSION_MAJOR
+	end
+
+	def test_has_VERSION_MINOR
+
+		assert defined? Xqsr3::XML::VERSION_MINOR
+	end
+
+	def test_has_VERSION_REVISION
+
+		assert defined? Xqsr3::XML::VERSION_REVISION
+	end
+
+	def test_VERSION_has_consistent_format
+
+		assert_equal Xqsr3::XML::VERSION, "#{Xqsr3::XML::VERSION_MAJOR}.#{Xqsr3::XML::VERSION_MINOR}.#{Xqsr3::XML::VERSION_REVISION}"
+	end
+end
+

data/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/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,256 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..'] * 4), '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
+
+	def test_different_declarations_and_dont_ignore
+
+		lhs_str	=	<<END_OF_lhs_doc
+<?xml version="1.0"?>
+<outer>
+ <mid>
+  <inner>some text</inner>
+ </mid>
+</outer>
+END_OF_lhs_doc
+
+		rhs_str	=	<<END_OF_rhs_doc
+<?xml version="1.0"?>
+ <mid>
+  <inner>some text</inner>
+ </mid>
+END_OF_rhs_doc
+
+		lhs_doc		=	Nokogiri::XML lhs_str
+		rhs_doc		=	Nokogiri::XML rhs_str
+
+		expected	=	rhs_doc
+		actual		=	lhs_doc.at_xpath('/outer/mid')
+
+		r			=	xml_compare expected, actual, normalise_whitespace: true, ignore_xml_declarations: false
+
+		assert !r.same?
+	end
+
+	def test_different_declarations_and_do_ignore
+
+		lhs_str	=	<<END_OF_lhs_doc
+<?xml version="1.0"?>
+<outer>
+ <mid>
+  <inner>some text</inner>
+ </mid>
+</outer>
+END_OF_lhs_doc
+
+		rhs_str	=	<<END_OF_rhs_doc
+<?xml version="1.0"?>
+ <mid>
+  <inner>some text</inner>
+ </mid>
+END_OF_rhs_doc
+
+		lhs_doc		=	Nokogiri::XML lhs_str
+		rhs_doc		=	Nokogiri::XML rhs_str
+
+		expected	=	rhs_doc
+		actual		=	lhs_doc.at_xpath('/outer/mid')
+
+		r			=	xml_compare expected, actual, normalise_whitespace: true, ignore_xml_declarations: true
+
+		assert r.same?, "#{r.details}"
+	end
+
+	def test_different_node_contents_by_child_node_order
+
+		lhs_str	=	<<END_OF_lhs_doc
+<?xml version="1.0"?>
+<outer>
+ <mid_1>
+  <inner>some text</inner>
+ </mid_1>
+ <mid_2>
+  <inner>some more text</inner>
+ </mid_2>
+</outer>
+END_OF_lhs_doc
+
+		rhs_str	=	<<END_OF_rhs_doc
+<?xml version="1.0"?>
+<outer>
+ <mid_2>
+  <inner>some more text</inner>
+ </mid_2>
+ <mid_1>
+  <inner>some text</inner>
+ </mid_1>
+</outer>
+END_OF_rhs_doc
+
+		lhs_doc		=	Nokogiri::XML lhs_str
+		rhs_doc		=	Nokogiri::XML rhs_str
+
+		expected	=	rhs_doc
+		actual		=	lhs_doc
+
+		r			=	xml_compare expected, actual, ignore_child_node_order: true, normalise_whitespace: true, ignore_xml_declarations: true
+
+		assert r.same?, "#{r.details}"
+	end
+
+	def test_different_node_contents_by_child_node_order_and_whitespace
+
+		lhs_str	=	<<END_OF_lhs_doc
+<?xml version="1.0"?>
+<outer><mid_1><inner>some text</inner></mid_1><mid_2><inner>some more text</inner></mid_2></outer>
+END_OF_lhs_doc
+
+		rhs_str	=	<<END_OF_rhs_doc
+<?xml version="1.0"?>
+<outer>
+ <mid_2>
+  <inner>some more text</inner>
+ </mid_2>
+ <mid_1>
+  <inner>some text</inner>
+ </mid_1>
+</outer>
+END_OF_rhs_doc
+
+		lhs_doc		=	Nokogiri::XML lhs_str
+		rhs_doc		=	Nokogiri::XML rhs_str
+
+		expected	=	rhs_doc
+		actual		=	lhs_doc
+
+		r			=	xml_compare expected, actual, ignore_child_node_order: true, normalise_whitespace: true, ignore_xml_declarations: true
+
+		assert r.same?, "#{r.details}"
+	end
+end
+
+

data/test/unit/xml/utilities/tc_navigation.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..'] * 4), 'lib')
+
+require 'xqsr3/xml/utilities/navigation'
+
+require 'xqsr3/extensions/test/unit'
+require 'test/unit'
+
+require 'nokogiri'
+
+class Test_Xqsr3_XML_Utilities_Navigation < Test::Unit::TestCase
+
+	include ::Xqsr3::XML::Utilities::Navigation
+
+	def test_get_descendants_1
+
+		xml_s	=	<<END_OF_rhs_doc
+<?xml version="1.0"?>
+<document>
+ <outer>
+  <mid_2>
+   <inner>some more text</inner>
+  </mid_2>
+  <mid_1>
+   <inner>some text</inner>
+  </mid_1>
+ </outer>
+</document>
+END_OF_rhs_doc
+
+		xml		=	::Nokogiri.XML(xml_s)
+		doc		=	xml.children.first
+
+		descs	=	self.class.get_descendants xml.children.first
+
+		assert_not_nil descs
+		assert_kind_of ::Array, descs
+
+		assert_operator 7, :<=, descs.size
+		%w{ outer mid_1 mid_2 }.each do |name|
+
+			assert(descs.find { |el| name == el.name }, "did not find an element named '#{name}' in the collection #{descs}")
+		end
+
+		texts	=	descs.select { |el| el.text? }
+
+		[ 'some text', 'some more text' ].each do |text|
+
+			assert(texts.find { |el| text == el.text }, "did not find an element with the text '#{text}' in the collection #{texts}")
+		end
+	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

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: xqsr3-xml
+version: !ruby/object:Gem::Version
+  version: 0.1.0.1
+platform: ruby
+authors:
+- Matt Wilson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-03-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: xqsr3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.31.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.31.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |
+  xqsr3 - eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries
+  - is a lightweight, low-coupling library of assorted extensions to standard
+  ruby and 3rd-party libraries.
+
+  xqsr3-xml contains the XML-related components for xqsr3, so that the core
+  library remains independent of any non-standard libraries.
+email: matthew@synesis.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/xqsr3/xml/utilities/compare.rb
+- lib/xqsr3/xml/utilities/navigation.rb
+- lib/xqsr3/xml/version.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/tc_navigation.rb
+- test/unit/xml/utilities/ts_all.rb
+- README.md
+- LICENSE
+homepage: http://github.com/synesissoftware/xqsr3-xml
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ~>
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: xqsr3-xml
+test_files: []