xqsr3 0.8.3

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

@@ -0,0 +1,8 @@
+
+require 'xqsr3/string_utilities/ends_with'
+
+class String
+
+	include ::Xqsr3::StringUtilities::EndsWith
+end # class String
+

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

@@ -0,0 +1,8 @@
+
+require 'xqsr3/command_line_utilities/map_option_string'
+
+class String
+
+	include ::Xqsr3::CommandLineUtilities::MapOptionString
+end # class String
+

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

@@ -0,0 +1,8 @@
+
+require 'xqsr3/string_utilities/starts_with'
+
+class String
+
+	include ::Xqsr3::StringUtilities::StartsWith
+end # class String
+

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

@@ -0,0 +1,8 @@
+
+require 'xqsr3/string_utilities/to_symbol'
+
+class String
+
+	include ::Xqsr3::StringUtilities::ToSymbol
+end # class String
+

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

@@ -0,0 +1,5 @@
+
+require 'xqsr3/extensions/test/unit/assert_eql'
+require 'xqsr3/extensions/test/unit/assert_not'
+require 'xqsr3/extensions/test/unit/assert_not_eql'
+

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

@@ -0,0 +1,18 @@
+
+module Test
+module Unit
+
+module Assertions
+
+	unless respond_to? :assert_eql
+
+		def assert_eql(expected, actual, failure_message = '')
+
+			assert expected.eql?(actual), failure_message
+		end
+	end
+
+end # class Assertions
+end # module Unit
+end # module Test
+

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

@@ -0,0 +1,18 @@
+
+module Test
+module Unit
+
+module Assertions
+
+	unless respond_to? :assert_not
+
+		def assert_not(test, failure_message = '')
+
+			assert !(test), failure_message
+		end
+	end
+
+end # class Assertions
+end # module Unit
+end # module Test
+

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

@@ -0,0 +1,18 @@
+
+module Test
+module Unit
+
+module Assertions
+
+	unless respond_to? :assert_not_eql
+
+		def assert_not_eql(expected, actual, failure_message = '')
+
+			assert !(expected.eql?(actual)), failure_message
+		end
+	end
+
+end # class Assertions
+end # module Unit
+end # module Test
+

data/lib/xqsr3/io/writelines.rb

@@ -0,0 +1,192 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/io/writelines.rb
+#
+# Purpose:      Adds a writelines() method to the IO module
+#
+# Created:      13th April 2007
+# Updated:      10th June 2016
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2007-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 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.
+#
+# ######################################################################## #
+
+
+require 'xqsr3/quality/parameter_checking'
+
+=begin
+=end
+
+module Xqsr3
+module IO
+
+	private
+	module WriteLine_Constants_ #:nodoc:
+
+		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
+
+			contents.each do |k, v|
+
+				target << "#{k}#{column_separator}#{v}#{line_separator}"
+			end
+		else
+
+			contents.each do |element|
+
+				target << "#{element}#{line_separator}"
+			end
+		end
+
+		contents.size
+	end
+
+	# This function checks to see if any part of the entries contains an
+	# 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
+
+		if contents.instance_of? ::Hash
+
+			contents.each_with_index do |k, v, index|
+
+				if eol_lookahead_limit && eol_lookahead_limit == index
+
+					break
+				else
+
+					return '' if v.to_s.include? "\n"
+					return '' if k.to_s.include? "\n"
+				end
+			end
+		else
+
+			contents.each_with_index do |element, index|
+
+				if eol_lookahead_limit && eol_lookahead_limit == index
+
+					break
+				else
+
+					return '' if element.to_s.include? "\n"
+				end
+			end
+		end
+
+		"\n"
+	end
+
+	public
+
+	# Writes the contents to the target, subject to the options
+	#
+	# === 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
+	#
+	# * *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+).
+	#
+	# === Return
+	#
+	# The number of entries in +contents+
+	def self.writelines target, contents, options = {}
+
+		# validate parameters
+
+		::Xqsr3::Quality::ParameterChecking.check_parameter(target, 'target', allow_nil: false) do |v|
+
+			raise TypeError, "#{self}#writeline() 'target' parameter must be a #{::String} or respond to <<" unless ::String === v || v.respond_to?(:<<)
+			true
+		end
+		::Xqsr3::Quality::ParameterChecking.check_parameter(contents, 'contents', allow_nil: false, types: [ ::String, ::Hash, ::Array ])
+
+		# process parameters
+
+		if contents.instance_of? String
+
+			if contents.include? "\n"
+
+				contents = contents.split(/\r?\n/, -1)
+			else
+
+				contents = [ contents ]
+			end
+		end
+
+		options				||=	{}
+		eol_lookahead_limit	=	options[:eol_lookahead_limit] || WriteLine_Constants_::NUMBER_OF_LINES_TO_EXAMINE
+		column_separator	=	options[:column_separator] || ''
+		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
+		line_separator		||=	"\n"
+
+		if not contents.kind_of? ::Enumerable and not contents.instance_of? ::Hash
+
+			raise ArgumentError, "writelines() must be passed a #{::String}, or a #{::Hash}, or an #{::Enumerable} (or derived)"
+		end
+
+		# do the writing
+
+		if ::String === target
+
+			File.open(target, "w") do |io|
+
+				self.write_to_target_ io, contents, line_separator, column_separator
+			end
+		else
+
+			self.write_to_target_ target, contents, line_separator, column_separator
+		end
+	end # writelines
+end # module IO
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+

data/lib/xqsr3/quality/parameter_checking.rb

@@ -0,0 +1,343 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/quality/parameter_checking.rb
+#
+# Purpose:      Definition of the ParameterChecking module
+#
+# Created:      12th February 2015
+# Updated:      10th June 2016
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2015-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 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 Quality
+
+# Parameter-checking utilities
+#
+module ParameterChecking
+
+	# 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)
+	# @option +:values+ an array of values one of which +value+ must be
+	# @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
+	def check_parameter value, name, options = {}, &block
+
+		failed_check	=	false
+		options			||=	{}
+		message			=	options[:message]
+		treat_as_option	=	options[:treat_as_option]
+		return_value	=	value
+		param_s			=	treat_as_option	? 'option' : 'parameter'
+
+		warn "#{self}::check_parameter: invoked with non-string/non-symbol name: name.class=#{name.class}" unless name && [ ::String, ::Symbol ].any? { |c| name.is_a?(c) }
+
+		name			=	name.to_s if name.is_a?(::Symbol)
+		name			=	(':' + name.to_s) if treat_as_option and name.is_a?(::String)
+
+		# nil check
+
+		if value.nil? && !options[:allow_nil]
+
+			failed_check	=	true
+
+			unless options[:nothrow]
+
+				unless message
+
+					if name.nil?
+
+						message	=	"#{param_s} may not be nil"
+					else
+
+						message	=	"#{param_s} '#{name}' may not be nil"
+					end
+				end
+
+				raise ArgumentError, message
+			end
+		end
+
+		# check type(s)
+
+		unless value.nil?
+
+			types		=	options[:types] || []
+			types		=	[value.class] if types.empty?
+			type_found	=	false
+
+			warn "#{self}::check_parameter: options[:types] of type #{types.class} - should be #{::Array}" unless types.is_a?(Array)
+			warn "#{self}::check_parameter: options[:types] should contain only classes" if types.is_a?(Array) && !types.all? { |c| ::Class === c }
+
+			unless types.any? { |t| value.is_a?(t) }
+
+				failed_check	=	true
+
+				unless options[:nothrow]
+
+					unless message
+
+						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+						case	types.size
+						when	1
+
+							s_types	=	"#{types[0]}"
+						when	2
+
+							s_types	=	"#{types[0]} or #{types[1]}"
+						else
+
+							s_types	=	"#{types[0...-1].join(', ')}, or #{types[-1]}"
+						end
+
+						message		=	"#{param_s} #{s_name}(#{value.class}) must be an instance of #{s_types}"
+					end
+
+					raise TypeError, message
+				end
+			end
+		end
+
+		# reject/require empty?
+
+		if options[:reject_empty]
+
+			warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
+
+			if value.empty?
+
+				failed_check	=	true
+
+				unless options[:nothrow]
+
+					unless message
+						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+						message		=	"#{param_s} #{s_name}must not be empty"
+					end
+
+					raise ArgumentError, message
+				end
+			end
+		end
+
+		if options[:require_empty]
+
+			warn "#{self}::check_parameter: value '#{value}' of type #{value.class} does not respond to empty?" unless value.respond_to? :empty?
+
+			unless value.empty?
+
+				failed_check	=	true
+
+				unless options[:nothrow]
+
+					unless message
+						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+						message		=	"#{param_s} #{s_name}must be empty"
+					end
+
+					raise ArgumentError, message
+				end
+			end
+		end
+
+		# check value(s)
+
+		unless value.nil?
+
+			values	=	options[:values] || [ value ]
+
+			warn "#{self}::check_parameter: options[:values] of type #{values.class} - should be #{::Array}" unless values.is_a?(Array)
+
+			found	=	false
+
+			values.each do |v|
+
+				if ::Range === v && !(::Range === value) && v.cover?(value)
+
+					found = true
+					break
+				end
+
+				if value == v
+
+					found = true
+					break
+				end
+			end
+
+			unless found
+
+				failed_check	=	true
+
+				unless options[:nothrow]
+
+					unless message
+						s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+						message		=	"#{param_s} #{s_name}value '#{value}' not found equal/within any of required values or ranges"
+					end
+
+					if value.is_a?(::Numeric)
+
+						raise RangeError, message
+					else
+
+						raise ArgumentError, message
+					end
+				end
+			end
+		end
+
+		# run block
+
+		if value and block
+
+			warn "#{self}::check_parameter: block arity must be 1" unless block.arity == 1
+
+			r	=	nil
+
+			begin
+
+				r = block.call(value)
+
+			rescue StandardError => x
+
+				xmsg	=	x.message || ''
+
+				if xmsg.empty?
+
+					xmsg	||=	message
+
+					if xmsg.empty?
+
+						s_name	=	name.is_a?(String) ? "'#{name}' " : ''
+						xmsg	=	"#{param_s} #{s_name}failed validation against caller-supplied block"
+					end
+
+					raise $!, xmsg, $!.backtrace
+				end
+
+				raise
+			end
+
+			if r.is_a?(::Exception)
+
+				# An exception returned from the block, so raise it, with
+				# its message or a custom message
+
+				x		=	r
+				xmsg	=	x.message || ''
+
+				if xmsg.empty?
+
+					xmsg	||=	message
+
+					if xmsg.empty?
+
+						s_name	=	name.is_a?(String) ? "'#{name}' " : ''
+						xmsg	=	"#{param_s} #{s_name}failed validation against caller-supplied block"
+					end
+
+					raise x, xmsg
+				end
+
+				raise x
+
+			elsif !r
+
+				failed_check	=	true
+
+				unless options[:nothrow]
+
+					s_name	=	name.is_a?(String) ? "'#{name}' " : ''
+					xmsg	=	"#{param_s} #{s_name}failed validation against caller-supplied block"
+
+					if value.is_a?(::Numeric)
+
+						raise RangeError, xmsg
+					else
+
+						raise ArgumentError, xmsg
+					end
+				end
+
+			elsif r.is_a?(::TrueClass)
+
+				;
+			else
+
+				return_value	=	r
+			end
+		end
+
+		failed_check ? nil : return_value
+	end
+
+	alias check_param check_parameter
+
+	module_function :check_parameter
+
+end # module ParameterChecking
+
+end # module Quality
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+