xqsr3 0.32.2 → 0.36.0

data/lib/xqsr3/hash_utilities/key_matching.rb

@@ -6,13 +6,13 @@
 #               module
 #
 # Created:      15th November 2017
-# Updated:      15th November 2017
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -56,10 +56,12 @@ require 'xqsr3/quality/parameter_checking'
 module Xqsr3
 module HashUtilities
 
+# +include+-able module that provides ::has_match?, #has_match?, ::match,
+# and #match methods
 module KeyMatching
 
 	private
-	def self.do_match_ h, re, **options
+	def self.do_match_ h, re, **options # :nodoc:
 
 		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :[], :has_key?, :each ]
 
@@ -97,7 +99,7 @@ module KeyMatching
 		nil
 	end
 
-	def self.do_has_match_ h, re, **options
+	def self.do_has_match_ h, re, **options # :nodoc:
 
 		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :[], :has_key?, :each ]
 

data/lib/xqsr3/internal_/test_unit_version_.rb

@@ -3,30 +3,47 @@
 # Test::Unit module
 
 require 'test/unit'
+
 begin
 
 	require 'test/unit/version'
 
+	# :stopdoc:
+	# @!visibility private
 	module Xqsr3
-	module Internal_
-	module TestUnitVersion_
+	# @!visibility private
+	module Internal_ # :nodoc:
+	# @!visibility private
+	module TestUnitVersion_ # :nodoc:
 
+		# @!visibility private
 		TEST_UNIT_VERSION_	=	Test::Unit::VERSION # :nodoc:
 	end # module TestUnitVersion_
 	end # module Internal_
 	end # module Xqsr3
+
+	# :startdoc:
 rescue LoadError
 
+	# :stopdoc:
+	# @!visibility private
 	module Xqsr3
-	module Internal_
-	module TestUnitVersion_
+	# @!visibility private
+	module Internal_ # :nodoc:
+	# @!visibility private
+	module TestUnitVersion_ # :nodoc:
 
+		# @!visibility private
 		TEST_UNIT_VERSION_	=	:not_found # :nodoc:
 	end # module TestUnitVersion_
 	end # module Internal_
 	end # module Xqsr3
+
+	# :startdoc:
 end
 
+# :stopdoc:
+
 module Xqsr3
 module Internal_ # :nodoc:
 module TestUnitVersion_ # :nodoc:
@@ -47,6 +64,7 @@ module TestUnitVersion_ # :nodoc:
 		TEST_UNIT_VERSION_PATCH_	=	TEST_UNIT_VERSION_PARTS_[2] # :nodoc:
 	end
 
+	# @!visibility private
 	def self.less_ a1, a2 # :nodoc:
 
 		n_common	=	a1.size < a2.size ? a1.size : a2.size
@@ -79,6 +97,7 @@ module TestUnitVersion_ # :nodoc:
 		end
 	end
 
+	# @!visibility private
 	def self.is_major_at_least? j # :nodoc:
 
 		return unless TEST_UNIT_VERSION_MAJOR_
@@ -86,6 +105,7 @@ module TestUnitVersion_ # :nodoc:
 		return j >= TEST_UNIT_VERSION_MAJOR_
 	end
 
+	# @!visibility private
 	def self.is_minor_at_least? n # :nodoc:
 
 		return unless TEST_UNIT_VERSION_MINOR_
@@ -93,6 +113,7 @@ module TestUnitVersion_ # :nodoc:
 		return n >= TEST_UNIT_VERSION_MINOR_
 	end
 
+	# @!visibility private
 	def self.is_at_least? v # :nodoc:
 
 		v	=	v.split(/\./).collect { |n| n.to_i } if String === v
@@ -100,6 +121,7 @@ module TestUnitVersion_ # :nodoc:
 		return !less_(TEST_UNIT_VERSION_PARTS_, v)
 	end
 
+	# @!visibility private
 	def self.is_less? v # :nodoc:
 
 		v	=	v.split(/\./).collect { |n| n.to_i } if String === v
@@ -111,4 +133,8 @@ end # module TestUnitVersion_
 end # module Internal_
 end # module Xqsr3
 
+# :startdoc:
+
+# ############################## end of file ############################# #
+
 

data/lib/xqsr3/io/writelines.rb

@@ -5,7 +5,7 @@
 # Purpose:      Adds a writelines() method to the IO module
 #
 # Created:      13th April 2007
-# Updated:      12th April 2019
+# Updated:      31st October 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -56,27 +56,58 @@ module Xqsr3
 module IO
 
 	private
-	module WriteLine_Constants_ #:nodoc:
+	# @!visibility private
+	module WriteLine_Constants_ #:nodoc: all
 
 		NUMBER_OF_LINES_TO_EXAMINE	=	20
-
 	end # module WriteLine_Constants_
 
 	private
 
-	def self.write_to_target_ target, contents, line_separator, column_separator
-$stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}', contents(#{contents.class})='#{contents}', line_separator(#{line_separator.class})='#{line_separator}', column_separator=(#{column_separator.class})='#{column_separator}')" if $DEBUG
-		if contents.instance_of? ::Hash
+	# @!visibility private
+	def self.write_to_target_ target, contents, line_separator, column_separator, no_last_eol # :nodoc:
+
+$stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}', contents(#{contents.class})='#{contents}', line_separator(#{line_separator.class})='#{line_separator}', column_separator(#{column_separator.class})='#{column_separator}', no_last_eol(#{no_last_eol.class})=#{no_last_eol})" if $DEBUG
+
+		if no_last_eol
+
+			first = true
+
+			if contents.instance_of? ::Hash
+
+				contents.each do |k, v|
+
+					target << line_separator unless first
+
+					target << "#{k}#{column_separator}#{v}"
+
+					first = false
+				end
+			else
 
-			contents.each do |k, v|
+				contents.each do |element|
 
-				target << "#{k}#{column_separator}#{v}#{line_separator}"
+					target << line_separator unless first
+
+					target << "#{element}"
+
+					first = false
+				end
 			end
 		else
 
-			contents.each do |element|
+			if contents.instance_of? ::Hash
 
-				target << "#{element}#{line_separator}"
+				contents.each do |k, v|
+
+					target << "#{k}#{column_separator}#{v}#{line_separator}"
+				end
+			else
+
+				contents.each do |element|
+
+					target << "#{element}#{line_separator}"
+				end
 			end
 		end
 
@@ -87,7 +118,9 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 	# embedded eol, in which case the empty string is returned to force no
 	# (additional) separator will be used. Otherwise, it returns "\n" to
 	# ensure that that is used.
-	def self.deduce_line_separator_ contents, eol_lookahead_limit
+	#
+	# @!visibility private
+	def self.deduce_line_separator_ contents, eol_lookahead_limit # :nodoc:
 
 		if contents.instance_of? ::Hash
 
@@ -126,14 +159,15 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +target+:: The target of the write, which may be a string containing the path or a stream instance that supports write
-	#   - +contents+:: The contents to be write, which may be a +Hash+, or an +Array+, or a +String+ containing delimited fields
-	#   - +options+:: An options hash, containing any of the following options
+	#   - +target+ The target of the write, which may be a string containing the path or a stream instance that supports write
+	#   - +contents+ The contents to be write, which may be a +Hash+, or an +Array+, or a +String+ containing delimited fields
+	#   - +options+ An options hash, containing any of the following options
 	#
 	# * *Options:*
-	#   - +:column_separator+:: {optional} The column separator, to be applied between each field in the case where +contents+ is a +Hash+.
-	#   - +:eol_lookahead_limit+:: {optional} The number of content elements (line/pair) to inspect to determine whether element has a terminating end-of-line sequence. Defaults to 20. If 0, and +:line_separator+ is not specified, then will default to <tt>"\n"</tt>. If +nil+, then every line will be inspected.
-	#   - +:line_separator+:: {optional} The line separator, to be applied to the end of line created from each entry. When not specified, it will be deduced by inspecting +contents+ (according to +eol_lookahead_limit+).
+	#   - +:column_separator+ {optional} The column separator, to be applied between each field in the case where +contents+ is a +Hash+.
+	#   - +:eol_lookahead_limit+ {optional} The number of content elements (line/pair) to inspect to determine whether element has a terminating end-of-line sequence. Defaults to 20. If 0, and +:line_separator+ is not specified, then will default to <tt>"\n"</tt>. If +nil+, then every line will be inspected.
+	#   - +:line_separator+ {optional} The line separator, to be applied to the end of line created from each entry. When not specified, it will be deduced by inspecting +contents+ (according to +eol_lookahead_limit+).
+	#   - +:no_last_eol+ {optional} If present and _truey_, causes suppression of the addition of the +:line_separator+ on the last line.
 	#
 	# === Return
 	#
@@ -165,6 +199,7 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 		options				||=	{}
 		eol_lookahead_limit	=	options[:eol_lookahead_limit] || WriteLine_Constants_::NUMBER_OF_LINES_TO_EXAMINE
 		column_separator	=	options[:column_separator] || ''
+		no_last_eol			=	options[:no_last_eol] || false
 		line_separator		=	nil
 		line_separator		||=	options[:line_separator]
 		line_separator		||=	self.deduce_line_separator_(contents, eol_lookahead_limit) unless !eol_lookahead_limit.kind_of?(::Integer) || 0 == eol_lookahead_limit
@@ -181,11 +216,11 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 
 			File.open(target, "w") do |io|
 
-				self.write_to_target_ io, contents, line_separator, column_separator
+				self.write_to_target_ io, contents, line_separator, column_separator, no_last_eol
 			end
 		else
 
-			self.write_to_target_ target, contents, line_separator, column_separator
+			self.write_to_target_ target, contents, line_separator, column_separator, no_last_eol
 		end
 	end # writelines
 end # module IO
@@ -193,3 +228,4 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
+

data/lib/xqsr3/quality.rb

@@ -1,3 +1,10 @@
 
-require 'xqsr3/quality/parameter_checking'
+%w{
+
+	parameter_checking
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'quality', name)
+end
+
 

data/lib/xqsr3/quality/parameter_checking.rb

@@ -5,13 +5,13 @@
 # Purpose:      Definition of the ParameterChecking module
 #
 # Created:      12th February 2015
-# Updated:      18th October 2018
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2015-2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2015-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -59,7 +59,8 @@ module Quality
 module ParameterChecking
 
 	private
-	module Util_ # :nodoc:
+	# @!visibility private
+	module Util_ # :nodoc: all
 
 		def self.join_with_or a
 
@@ -76,7 +77,7 @@ module ParameterChecking
 			end
 		end
 
-		module Constants
+		module Constants # :nodoc:
 
 			RECOGNISED_OPTION_NAMES = %w{
 
@@ -99,7 +100,7 @@ module ParameterChecking
 	end # module Util_
 	public
 
-	def self.included base
+	def self.included base # :nodoc:
 
 		base.extend self
 	end
@@ -107,42 +108,27 @@ 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
-	#         checked
-	# @param +options+:: (::Hash) options that moderate the behaviour
+	# === Signature
 	#
-	# @option +:allow_nil+:: (boolean) The +value+ must not be +nil+ unless
-	#          this option is true
-	# @option +:nil+:: an alias for +:allow_nil+
-	# @option +:ignore_case+:: (boolean) When +:values+ is specified,
-	#  comparisons of strings, or arrays of strings, will be carried out in
-	#  a case-insensitive manner
-	# @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+:: (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 +: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
+	# * *Parameters:*
+	#   - +value+ the parameter whose value and type is to be checked
+	#   - +name+ (::String, ::Symbol) the name of the parameter to be checked
+	#   - +options+ (::Hash) options that moderate the behaviour
+	#
+	# * *Options:*
+	#   - +:allow_nil+ (boolean) The +value+ must not be +nil+ unless this option is true
+	#   - +:nil+ an alias for +:allow_nil+
+	#   - +:ignore_case+ (boolean) When +:values+ is specified, comparisons of strings, or arrays of strings, will be carried out in a case-insensitive manner
+	#   - +: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
+	#   - +:type+ (::Class) A single type parameter, used only if +:types+ is not specified
+	#   - +:values+ (::Array) an array of values one of which +value+ must be
+	#   - +:responds_to+ (::Array) An array of symbols specifying all messages to which the parameter will respond
+	#   - +:reject_empty+ (boolean) requires value to respond to +empty?+ message and to do so with false, unless +nil+
+	#   - +:require_empty+ (boolean) requires value to respond to +empty?+ message and to do so with true, unless +nil+
+	#   - +:nothrow+ (boolean) causes failure to be indicated by a +nil+ return rather than a thrown exception
+	#   - +:message+ (::String) specifies a message to be used in any thrown exception, which suppresses internal message preparation
+	#   - +: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
+	#   - +: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
 	def check_parameter value, name, options = {}, &block
@@ -162,15 +148,14 @@ 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
-	#         to be tested. May not be +nil+
-	# @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()+
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +h+ (::Hash) The options hash from which the named element is to be tested. May not be +nil+
+	#   - +name+ (::String, ::Symbol, [ ::String, ::Symbol ]) The options key name, or an array of names. May not be +nil+
+	#   - +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()+
 	#
+	# * *Options:*
 	def check_option h, name, options = {}, &block
 
 		Util_.check_option h, name, options, &block
@@ -179,37 +164,26 @@ module ParameterChecking
 	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
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +value+ the parameter whose value and type is to be checked
+	#   - +name+ the name of the parameter to be checked
+	#   - +options+ options
 	#
-	# @option +:allow_nil+:: (boolean) The +value+ must not be +nil+ unless
-	#          this option is true
-	# @option +:nil+:: an alias for +:allow_nil+
-	# @option +:ignore_case+:: (boolean) When +:values+ is specified,
-	#  comparisons of strings, or arrays of strings, will be carried out in
-	#  a case-insensitive manner
-	# @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+:: (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
+	# * *Options:*
+	#   - +:allow_nil+ (boolean) The +value+ must not be +nil+ unless this option is true
+	#   - +:nil+ an alias for +:allow_nil+
+	#   - +:ignore_case+ (boolean) When +:values+ is specified, comparisons of strings, or arrays of strings, will be carried out in a case-insensitive manner
+	#   - +: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
+	#   - +:type+ (::Class) A single type parameter, used only if +:types+ is not specified
+	#   - +:values+ (::Array) an array of values one of which +value+ must be
+	#   - +:responds_to+ (::Array) An array of symbols specifying all messages to which the parameter will respond
+	#   - +:reject_empty+ (boolean) requires value to respond to +empty?+ message and to do so with false, unless +nil+
+	#   - +:require_empty+ (boolean) requires value to respond to +empty?+ message and to do so with true, unless +nil+
+	#   - +:nothrow+ (boolean) causes failure to be indicated by a +nil+ return rather than a thrown exception
+	#   - +:message+ (boolean) specifies a message to be used in any thrown exception, which suppresses internal message preparation
+	#   - +: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