xqsr3 0.32.3 → 0.37.0

data/lib/xqsr3/conversion.rb

@@ -0,0 +1,11 @@
+
+%w{
+
+	bool_parser
+	integer_parser
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'conversion', name)
+end
+
+

data/lib/xqsr3/conversion/integer_parser.rb

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      21st November 2017
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -58,7 +58,8 @@ module Conversion
 module IntegerParser
 
 	private
-	module IntegerParser_Helper_ # :nodoc:
+	# @!visibility private
+	module IntegerParser_Helper_ # :nodoc: all
 
 		if Kernel.respond_to?(:xqsr3_Integer_original_method)
 

data/lib/xqsr3/diagnostics.rb

@@ -0,0 +1,11 @@
+
+%w{
+
+	exception_utilities
+	inspect_builder
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'diagnostics', name)
+end
+
+

data/lib/xqsr3/diagnostics/inspect_builder.rb

@@ -54,8 +54,10 @@ module Diagnostics
 
 module InspectBuilder
 
-	module InspectBuilder_Utilities
+	# @!visibility private
+	module InspectBuilder_Utilities # :nodoc: all
 
+		# @!visibility private
 		NORMALISE_FUNCTION	=	lambda { |ar| ar.map { |v| v.to_s }.map { |v| '@' == v[0] ? v : "@#{v}" } }
 	end # module InspectBuilder_Utilities
 
@@ -157,6 +159,8 @@ module InspectBuilder
 	end
 
 	# Creates an inspect string from self
+	#
+	# see InspectBuilder::make_inspect
 	def make_inspect **options
 
 		::Xqsr3::Diagnostics::InspectBuilder.make_inspect self, **options

data/lib/xqsr3/extensions.rb

@@ -0,0 +1,13 @@
+
+%w{
+
+	array
+	enumerable
+	hash
+	io
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'extensions', name)
+end
+
+

data/lib/xqsr3/extensions/array.rb

@@ -0,0 +1,3 @@
+
+require 'xqsr3/extensions/array/join_with_or'
+

data/lib/xqsr3/extensions/hash.rb

@@ -1,5 +1,11 @@
 
 require 'xqsr3/extensions/hash/deep_transform'
+require 'xqsr3/extensions/hash/except'
 require 'xqsr3/extensions/hash/has_match'
 require 'xqsr3/extensions/hash/match'
 
+unless (RUBY_VERSION.split('.').map { |v| v.to_i } <=> [ 2, 5, 0 ]) > 0
+
+	require 'xqsr3/extensions/hash/slice'
+end
+

data/lib/xqsr3/extensions/hash/except.rb

@@ -0,0 +1,26 @@
+
+unless Hash.instance_methods.include? :except
+
+	class Hash
+
+		# Removes from the instance any key-value pairs matching the
+		# keys specified in +keys_to_delete+
+		def except!(*keys_to_delete)
+
+			keys_to_delete.each do |key|
+
+				self.delete key
+			end
+
+			self
+		end
+
+		# Obtains a copy of the instance wherein any key-value pairs
+		# matching the keys specified in +keys_to_delete+ are removed
+		def except(*keys_to_delete)
+
+			self.dup.except!(*keys_to_delete)
+		end
+	end
+end
+

data/lib/xqsr3/extensions/hash/slice.rb

@@ -0,0 +1,22 @@
+
+unless Hash.instance_methods.include? :slice
+
+	class Hash
+
+		def slice(*args)
+
+			r = {}
+
+			args.each do |arg|
+
+				if self.has_key? arg
+
+					r[arg] = self[arg]
+				end
+			end
+
+			r
+		end
+	end
+end
+

data/lib/xqsr3/extensions/io/writelines.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a writelines() method to the IO class
 #
 # Created:      13th April 2007
-# Updated:      10th June 2016
+# Updated:      31st October 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2007-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -54,13 +54,45 @@ require 'xqsr3/io/writelines'
 
 class IO
 
-	# Extends +IO+ class with the ::Xqsr3::IO::write_lines
-	# method
-	def self.writelines(path, contents, lineSep = nil, columnSep = nil)
+	# Extends +IO+ class with the +::Xqsr3::IO::write_lines+ method
+	#
+	#
+	#def self.writelines(path, contents, lineSep = nil, columnSep = nil)
+	def self.writelines(path, contents, *args)
 
-		::Xqsr3::IO.writelines path, contents, line_separator: lineSep, column_separator: columnSep, eol_lookahead_limit: 20
+		options = {}
+
+		case args.size
+		when 0
+
+			;
+		when 1
+
+			arg3 = args[0]
+
+			if arg3.respond_to?(:to_hash)
+
+				options.merge! arg3.to_hash
+			else
+
+				options[:line_separator] = arg3
+			end
+		when 2
+
+			arg3 = args[0]
+			arg4 = args[1]
+
+			options[:line_separator] = arg2
+			options[:column_separator] = arg2
+		else
+
+			raise ArgumentError, "wrong number of arguments (given #{2 + args.size}, expected 2..4)"
+		end
+
+		::Xqsr3::IO.writelines path, contents, **options
 	end
 end # class IO
 
 # ############################## end of file ############################# #
 
+

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

@@ -1,15 +1,21 @@
 
 require 'xqsr3/internal_/test_unit_version_'
 
+# :stopdoc:
+
 module Xqsr3
-module Internal_ # :nodoc:
-module X_assert_raise_with_message_ # :nodoc:
+# @!visibility private
+module Internal_ # :nodoc: all
+# @!visibility private
+module X_assert_raise_with_message_ # :nodoc: all
 
 	if TestUnitVersion_.is_at_least? [ 3, 0, 8 ]
 
+		# @!visibility private
 		AssertionFailedError_	=	Test::Unit::AssertionFailedError # :nodoc:
 	else
 
+		# @!visibility private
 		class AssertionFailedError_	< ArgumentError; end # :nodoc:
 	end
 
@@ -17,6 +23,8 @@ end # module X_assert_raise_with_message_
 end # module Internal_
 end # module Xqsr3
 
+# :startdoc:
+
 module Test
 module Unit
 
@@ -27,6 +35,16 @@ module Assertions
 	# Asserts that the attached block raises an exception of one of the
 	# exceptions defined by +type_spec+ and/or has a message matching
 	# +message_spec+
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +type_spec+ (String, Regexp, [String], [Regexp], nil) Specification of type expectation(s)
+	#   - +message_spec+ (String, Regexp, [String], [Regexp], nil) Specification of message expectation(s)
+	#   - +failure_message+ (String, nil) Optional message to be used if the matching fails
+	#
+	# * *Block*
+	# A required block containing code that is expected to raise an exception
 	def assert_raise_with_message(type_spec, message_spec, failure_message = nil, &block)
 
 		unless block_given?
@@ -97,4 +115,6 @@ end # class Assertions
 end # module Unit
 end # module Test
 
+# ############################## end of file ############################# #
+
 

data/lib/xqsr3/hash_utilities.rb

@@ -0,0 +1,11 @@
+
+%w{
+
+	deep_transform
+	key_matching
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'hash_utilities', name)
+end
+
+

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
+	# @!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
+	# @!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
 
@@ -134,6 +167,7 @@ $stderr.puts "#{self.class}.write_to_target_(target(#{target.class})='#{target}'
 	#   - +: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 ############################# #
 
+