xqsr3 0.32.2 → 0.36.0

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/array/join_with_or.rb

@@ -3,6 +3,12 @@ require 'xqsr3/array_utilities/join_with_or'
 
 class Array
 
+	# Extended method implemented by JoinWithOr
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +options+ (Hash) See Xqsr3::ArrayUtilities
 	def join_with_or **options
 
 		return ::Xqsr3::ArrayUtilities::JoinWithOr.join_with_or self, **options

data/lib/xqsr3/extensions/enumerable/collect_with_index.rb

@@ -5,13 +5,13 @@
 # Purpose:      Adds a collect_with_index() method to the Enumerable module
 #
 # Created:      24th October 2010
-# Updated:      4th April 2016
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2010-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2010-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -52,8 +52,9 @@
 
 module Enumerable
 
-	## Two-parameter #collect, where the second parameter is a #base-based
-	# index, which increments by 1 for each enumerated element.
+	# Two-parameter variant of +Enumerable+#+collect+, where the second
+	# parameter is a +base+-based index, which increments by 1 for each
+	# enumerated element.
 	def collect_with_index(base = 0)
 
 		a = []

data/lib/xqsr3/extensions/enumerable/detect_map.rb

@@ -5,13 +5,13 @@
 # Purpose:      ::Enumerable#detect_map extension
 #
 # Created:      3rd December 2017
-# Updated:      9th December 2017
+# Updated:      12th 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
@@ -49,15 +49,15 @@
 
 module Enumerable
 
-	# The +Enumerable#detect+ method provides a way to detect the presence
+	# The +Enumerable+#+detect+ method provides a way to detect the presence
 	# of a particular value in a collection. The only constraint is that you
 	# get back the object unchanged.
 	#
-	# The +Enumerable#map+ method provides a way to transform the contents of
+	# The +Enumerable+#+map+ method provides a way to transform the contents of
 	# a collection. The only constraint is that you get back another
 	# collection.
 	#
-	# This extension method, +Enumerable#detect_map+ combines the features
+	# This extension method, +Enumerable+#+detect_map+ combines the features
 	# of both, in that it detects the presence of a particular value in a
 	# collection and transform the detected value.
 	#
@@ -65,7 +65,7 @@ module Enumerable
 	#
 	#  { :ab => 'cd', :ef => 'gh' }.detect_map { |k, v| v.upcase if k == :ef } # => 'GH'
 	#
-	# @note The block is required (for technical reasons), and must have
+	# *Note:* The block is required (for technical reasons), and must have
 	# arity 1 for sequences or 2 for associations
 	def detect_map &block
 
@@ -89,7 +89,6 @@ module Enumerable
 
 		nil
 	end
-
 end # module Enumerable
 
 # ############################## end of file ############################# #

data/lib/xqsr3/extensions/hash.rb

@@ -3,3 +3,8 @@ require 'xqsr3/extensions/hash/deep_transform'
 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/has_match.rb

@@ -3,6 +3,13 @@ require 'xqsr3/hash_utilities/key_matching'
 
 class Hash
 
+	# Extended method implemented by Xqsr3::HashUtilities::KeyMatching
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +re+ (Regexp) The regular expression
+	#   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
 	def has_match? re, **options
 
 		return ::Xqsr3::HashUtilities::KeyMatching.has_match? self, re, **options

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

@@ -3,6 +3,13 @@ require 'xqsr3/hash_utilities/key_matching'
 
 class Hash
 
+	# Extended method implemented by Xqsr3::HashUtilities::KeyMatching
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +re+ (Regexp) The regular expression
+	#   - +options+ (Hash) See Xqsr3::HashUtilities::KeyMatching
 	def match re, **options
 
 		return ::Xqsr3::HashUtilities::KeyMatching.match self, re, **options

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/kernel/integer.rb

@@ -61,21 +61,14 @@ module Kernel
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +arg+:: The argument to be converted (to +Fixnum+ or +Bignum+)
-	#   - +base+:: A value of 0, or between 2 and 36. Defaults to 0
-	#   - +options+:: An options hash, containing any of the following
-	#     options
-	#   - +block+:: An optional caller-supplied block that will be invoked
-	#     with the +ArgumentError+ exception, allowing the caller to take
-	#     additional action. If the block returns then its return value will
-	#     be returned to the caller
+	#   - +arg+ The argument to be converted (to +Fixnum+ or +Bignum+)
+	#   - +base+ A value of 0, or between 2 and 36. Defaults to 0
+	#   - +options+ An options hash, containing any of the following options
+	#   - +block+ An optional caller-supplied block that will be invoked with the +ArgumentError+ exception, allowing the caller to take additional action. If the block returns then its return value will be returned to the caller
 	#
 	# * *Options:*
-	#   - +:default+:: A default value to be used when +arg+ is +nil+ or
-	#     cannot be converted by (the original) +Kernel#Integer+
-	#   - +:nil+:: Returns +nil+ if +arg+ is +nil+ or cannot be
-	#     converted by (the original) +Kernel#Integer+. Ignored if
-	#     +:default+ is specified
+	#   - +:default+ A default value to be used when +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+
+	#   - +:nil+ Returns +nil+ if +arg+ is +nil+ or cannot be converted by (the original) +Kernel#Integer+. Ignored if +:default+ is specified
 	def Integer(arg, base = 0, **options, &block)
 
 		::Xqsr3::Conversion::IntegerParser.to_integer arg, base = 0, **options, &block

data/lib/xqsr3/extensions/string/to_bool.rb

@@ -3,6 +3,10 @@ require 'xqsr3/conversion/bool_parser'
 
 class String
 
+	# Attempts to convert instance to a Boolean value, based on the given
+	# +options+
+	#
+	# See Xqsr3::Conversion::BoolParser
 	def to_bool **options
 
 		return ::Xqsr3::Conversion::BoolParser.to_bool self, **options

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_eql
 
+		# Assert that +expected+ and +actual+ have the same hash key
 		def assert_eql(expected, actual, failure_message = '')
 
 			assert expected.eql?(actual), failure_message

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_false
 
+		# Assert that +expression+ is +false+
 		def assert_false(expression, failure_message = '')
 
 			assert ::FalseClass === (expression), failure_message

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_not
 
+		# Assert that +expression+ is _falsey_
 		def assert_not(expression, failure_message = '')
 
 			assert !(expression), failure_message

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_not_eql
 
+		# Assert that +expected+ and +actual+ have different hash keys
 		def assert_not_eql(expected, actual, failure_message = '')
 
 			assert !(expected.eql?(actual)), failure_message

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

@@ -1,22 +1,28 @@
 
 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 ]
 
-		AssertionFailedError_	=	Test::Unit::AssertionFailedError
+		AssertionFailedError_	=	Test::Unit::AssertionFailedError # :nodoc:
 	else
 
-		class AssertionFailedError_	< ArgumentError; end
+		class AssertionFailedError_	< ArgumentError; end # :nodoc:
 	end
 
 end # module X_assert_raise_with_message_
 end # module Internal_
 end # module Xqsr3
 
+# :startdoc:
+
 module Test
 module Unit
 
@@ -24,6 +30,19 @@ module Assertions
 
 	undef :assert_raise_with_message if respond_to? :assert_raise_with_message
 
+	# 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?
@@ -94,4 +113,6 @@ end # class Assertions
 end # module Unit
 end # module Test
 
+# ############################## end of file ############################# #
+
 

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_subclass_of
 
+		# Assert that +tested_class+ is a sub-class of +parent_class+
 		def assert_subclass_of(parent_class, tested_class, failure_message = nil)
 
 			failure_message ||= "#{tested_class} is not a subclass of #{parent_class}"

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_superclass_of
 
+		# Assert that +tested_class+ is a super-class of +child_class+
 		def assert_superclass_of(child_class, tested_class, failure_message = nil)
 
 			failure_message ||= "#{tested_class} is not a superclass of #{child_class}"

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

@@ -6,6 +6,7 @@ module Assertions
 
 	unless respond_to? :assert_true
 
+		# Assert that +expression+ is +true+
 		def assert_true(expression, failure_message = '')
 
 			assert ::TrueClass === (expression), failure_message

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

@@ -12,18 +12,9 @@ module Assertions
 		# === Signature
 		#
 		# * *Parameters:*
-		#   - +type+:: [::Class] The type
-		#   - +message_spec+:: [::Symbol, ::Array, ::Hash] A specification
-		#     of message(s) received by the instances of +type+. If a
-		#     ::Symbol, then instances must respond to this single message.
-		#     If an ::Array (all elements of which must be ::Symbol), then
-		#     instances must respond to _all_ messages. If a ::Hash, then
-		#     instances must respond to _all_ messages represented by the
-		#     keys; the values are available for specifying a custom failure
-		#     message (or value is +nil+ for stock message)
-		#  - +failure_message+:: [::String] If specified, is used when
-		#     instances of +type+ do not respond to a message and no custom
-		#     failure message is provided for it
+		#   - +type+ (::Class) The type
+		#   - +message_spec+ (::Symbol, ::Array, ::Hash) A specification of message(s) received by the instances of +type+. If a ::Symbol, then instances must respond to this single message.  If an ::Array (all elements of which must be ::Symbol), then instances must respond to _all_ messages. If a ::Hash, then instances must respond to _all_ messages represented by the keys; the values are available for specifying a custom failure message (or value is +nil+ for stock message)
+		#  - +failure_message+ (::String) If specified, is used when instances of +type+ do not respond to a message and no custom failure message is provided for it
 		def assert_type_has_instance_methods(type, message_spec, failure_message = nil)
 
 			warn "type parameter - '#{type} (#{type.class})' - should be a Class" unless type.is_a?(::Class)

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/deep_transform.rb

@@ -59,7 +59,7 @@ module HashUtilities
 module DeepTransform
 
 	private
-	def self.do_deep_transform_on_hashlike_ h, &block
+	def self.do_deep_transform_on_hashlike_ h, &block # :nodoc:
 
 		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :map ]
 
@@ -92,7 +92,7 @@ module DeepTransform
 		h
 	end
 
-	def do_deep_transform_on_self_ &block
+	def do_deep_transform_on_self_ &block # :nodoc:
 
 		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :[]=, :delete, :keys ]