xqsr3 0.10.2 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 522223b0b707f9057fdafa48580809911ecd8c9d
-  data.tar.gz: 9203708c9ca41f78025c5882f72fa7f55170a095
+  metadata.gz: b23c1bd7f01f0540f8cd11ba2a619fa6d2fb334c
+  data.tar.gz: 7b79521e19d9f76bc869a83c8003cbddec3ad576
 SHA512:
-  metadata.gz: fcb1fb10938327574cb3ea10ce57a91d795d6cc524cd95aae6770daace4306ae63f17957920bb3e32932ce11f350139cc70151485a38b86f072622b7c34260e4
-  data.tar.gz: 4aef021764d9cff5977379ae18136713cbbcb346afd87014de9f2dffd31e25e03aa51899494a6940af39d44ebd637a49b4145d52e940be7556ef93035ee95665
+  metadata.gz: 1c53ef621526a41f9f47afe099d1ff8df7dc775700a2974ecab2834a317f31fd012c98c679aa1499fb2ce696daf9f257ddf64424fa232517a6df0cff3383c212
+  data.tar.gz: bc62c09071304cb569e896217f719337038c5e888882b35ecdec4df67eb4c89202e8f6d896d12d9788918428888297fc87895b2b21dd998a737fb369008e56e1

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

@@ -0,0 +1,8 @@
+
+require 'xqsr3/hash_utilities/deep_transform'
+
+class Hash
+
+	include ::Xqsr3::HashUtilities::DeepTransform
+end # class Hash
+

data/lib/xqsr3/extensions/string.rb

@@ -1,6 +1,7 @@
 
 require 'xqsr3/extensions/string/ends_with'
 require 'xqsr3/extensions/string/map_option_string'
+require 'xqsr3/extensions/string/quote_if'
 require 'xqsr3/extensions/string/starts_with'
 require 'xqsr3/extensions/string/to_symbol'
 

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

@@ -0,0 +1,9 @@
+
+require 'xqsr3/string_utilities/quote_if'
+
+class String
+
+	include ::Xqsr3::StringUtilities::QuoteIf
+end # class String
+
+

data/lib/xqsr3/hash_utilities/deep_transform.rb

@@ -0,0 +1,155 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/hash_utilities/deep_transform.rb
+#
+# Purpose:      Definition of the ::Xqsr3::HashUtilities::DeepTransform
+#               module
+#
+# Created:      3rd June 2017
+# Updated:      7th June 2017
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017, 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::HashUtilities::DeepTransform
+
+=begin
+=end
+
+module Xqsr3
+module HashUtilities
+
+module DeepTransform
+
+	private
+	def self.do_deep_transform_on_hashlike_ h, &block
+
+		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :map ]
+
+		case block.arity
+		when 1
+
+			h = 
+			Hash[h.map do |k, v|
+
+				k = k.deep_transform &block if ::Hash === k
+				v = v.deep_transform &block if ::Hash === v
+
+				[yield(k), v]
+			end]
+		when 2
+
+			h = 
+			Hash[h.map do |k, v|
+
+				k = k.deep_transform &block if ::Hash === k
+				v = v.deep_transform &block if ::Hash === v
+
+				yield(k, v)
+			end]
+		else
+
+			raise ArgumentError, "block arity must be 1 or 2"
+		end
+
+		h
+	end
+
+	def do_deep_transform_on_self_ &block
+
+		::Xqsr3::Quality::ParameterChecking.check_parameter h, 'h', responds_to: [ :[]=, :delete, :keys ]
+
+		case block.arity
+		when 1
+
+			self.keys.each do |k|
+
+				v	=	self.delete k
+
+				k	=	k.deep_transform &block if ::Hash === k
+				v	=	v.deep_transform &block if ::Hash === v
+
+				self[yield(k)] = v
+			end
+		when 2
+
+			self.keys.each do |k|
+
+				v	=	self.delete k
+
+				k	=	k.deep_transform &block if ::Hash === k
+				v	=	v.deep_transform &block if ::Hash === v
+
+				k, v	=	yield(k, v)
+			end
+		else
+
+			raise ArgumentError, "block arity must be 1 or 2"
+		end
+	end
+	public
+
+	# Executes the given mandatory 1- or 2-parameter block on the receiving
+	# instance, which must be a Hash or a type that responds to the +map+
+	# message, returning a copy of the instance in which keys (1-parameter
+	# block) or keys and values (2-parameter block) are transformed.
+	def deep_transform &block
+
+		DeepTransform.do_deep_transform_on_hashlike_ self, &block
+	end
+
+	# Executes the given mandatory 1- or 2-parameter block on the receiving
+	# instance, whihc must be a Hash or a type that responds to +[]+,
+	# +delete+, and +keys+ messages, changing the keys (1-parameter block)
+	# or keys and values (2-parameter block).
+	#
+	# @note This method is not strongly exception-safe - failure during
+	#  transformation can result in a partially transformed instance
+	def deep_transform! &block
+
+		do_deep_transform_on_self_ &block
+	end
+
+end # module DeepTransform
+
+end # module HashUtilities
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/lib/xqsr3/quality/parameter_checking.rb

@@ -84,6 +84,8 @@ module ParameterChecking
 	#          of types, in which case +value+ may be an array that must
 	#          consist wholly of those types
 	# @option +:values+ an array of values one of which +value+ must be
+	# @option +:responds_to+ an array of symbols specifying all messages to
+	#          which the parameter will respond
 	# @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?+
@@ -135,6 +137,8 @@ module ParameterChecking
 
 		unless value.nil?
 
+			# types
+
 			types		=	options[:types] || []
 			types		=	[value.class] if types.empty?
 			type_found	=	false
@@ -192,6 +196,25 @@ module ParameterChecking
 					raise TypeError, message
 				end
 			end
+
+
+			# messages
+
+			messages	=	options[:responds_to] || []
+
+			warn "#{self}::check_parameter: options[:responds_to] of type #{messages.class} - should be #{::Array}" unless messages.is_a?(Array)
+			warn "#{self}::check_parameter: options[:responds_to] should contain only symbols or strings" if messages.is_a?(::Array) && !messages.all? { |m| ::Symbol === m || ::String === m }
+
+			messages.each do |m|
+
+				unless value.respond_to? m
+
+					s_name		=	name.is_a?(String) ? "'#{name}' " : ''
+
+					raise TypeError, "#{param_s} #{s_name}(#{value.class}) must respond to the '#{m}' message"
+				end
+			end
+
 		end
 
 		# reject/require empty?

data/lib/xqsr3/string_utilities/quote_if.rb

@@ -0,0 +1,132 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/string_utilities/quote_if.rb
+#
+# Purpose:      Definition of the ::Xqsr3::StringUtilities::QuoteIf
+#               module
+#
+# Created:      3rd June 2017
+# Updated:      7th June 2017
+#
+# Home:         http://github.com/synesissoftware/xqsr3
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017, 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::StringUtilities::QuoteIf
+
+=begin
+=end
+
+module Xqsr3
+module StringUtilities
+
+module QuoteIf
+
+	private
+	module QuoteIf_Helper_ #:nodoc:
+
+		def self.string_quote_if_array_ s, options
+
+		#$stderr.puts "#{self}#{__method__}(s (#{s.class})='#{s}', options (#{options.class})='#{options}'"
+
+			s			=	s.to_s unless String === s
+
+			quotes		=	options[:quotes] || [ '"', '"' ]
+			quotes		=	[ quotes, quotes ] if String === quotes
+
+			quotables	=	options[:quotables] || /\s/
+
+#$stderr.puts "quotables (#{quotables.class}): [#{quotables}]"
+
+			case quotables
+			when ::String
+
+				return s unless s.include? quotables
+			when ::Array
+
+				return s unless quotables.any? { |quotable| s.include? quotable }
+			when ::Regexp
+
+				return s unless s =~ quotables
+			else
+
+				raise ArgumentError, "Invalid type (#{quotables.class}) specified for quotables parameter"
+			end
+
+			return quotes[0] + s + quotes[1]
+		end
+	end
+	public
+
+	# Converts a string to a quoted form if necessary
+	#
+	# === *Parameters*
+	#
+	# * *Required parameters*:
+	#   - +s+:: [String] The string to be evaluated
+	#
+	# * *Options parameters*:
+	#   - +options+:: [Hash] Options that control the behaviour of the
+	#       method
+	#
+	# * *Options*:
+	#
+	#   - +:quotes+:: [String, Array] A string that is used as the opening
+	#       and closing quotes, or an array whose first two elements are
+	#       used as the opening and closing quotes. Defaults to '"'
+	#   - +:quotables+:: [String, Array, Regexp] A string representing the
+	#       quotable character, or an array containing the quotable
+	#       characters, or a regular expression that determines by match
+	#       whether the string should be quoted. Defaults to the regular
+	#       expression /\s/
+	def self.quote_if s, **options
+
+		QuoteIf_Helper_.string_quote_if_array_ s, options
+	end
+
+	def quote_if **options
+
+		QuoteIf_Helper_.string_quote_if_array_ self, options
+	end
+end # module QuoteIf
+
+end # module StringUtilities
+end # module Xqsr3
+
+# ############################## end of file ############################# #
+
+

data/lib/xqsr3/version.rb

@@ -5,7 +5,7 @@
 # Purpose:      Version for Xqsr3 library
 #
 # Created:      3rd April 2016
-# Updated:      26th February 2017
+# Updated:      7th June 2017
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.10.2'
+	VERSION				=	'0.11.1'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/extensions/hash/tc_deep_transform.rb

@@ -0,0 +1,49 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
+
+require 'xqsr3/extensions/hash/deep_transform'
+
+require 'xqsr3/extensions/test/unit'
+require 'test/unit'
+
+require 'stringio'
+
+class Test_Hash_deep_transform < Test::Unit::TestCase
+
+	def test_Hash_has_method
+
+		assert Hash.new.respond_to? :deep_transform
+	end
+
+	def test_with_empty
+
+		assert_equal Hash.new, Hash.new.deep_transform { |k| k }
+		assert_equal Hash.new, Hash.new.deep_transform { |k, v| [ k, v ] }
+	end
+
+	def test_transform_to_same
+
+		jkl	=	12
+		h	=	{ 'abc' => 'def', ghi: jkl, mno: { p: 'q', 'r' => 'st' } }
+
+		assert_equal h, h.deep_transform { |k| k }
+		assert_equal h, h.deep_transform { |k, v| [ k, v ] }
+	end
+
+	def test_transform_to_symbolise_keys
+
+		jkl	=	12
+		h	=	{ 'abc' => 'def', ghi: jkl, mno: { p: 'q', 'r' => 'st' } }
+
+		h_1	=	{ abc: 'def', ghi: jkl, mno: { p: 'q', r: 'st' } }
+		h_2	=	{ abc: :def, ghi: jkl, mno: { p: :q, r: :st } }
+
+		assert_equal h_1, h.deep_transform { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+		assert_equal h_1, h.deep_transform { |k, v| [ k.respond_to?(:to_sym) ? k.to_sym : k, v ] }
+		assert_equal h_2, h.deep_transform { |k, v| [ k.respond_to?(:to_sym) ? k.to_sym : k, v.respond_to?(:to_sym) ? v.to_sym : v ] }
+	end
+end
+
+
+

data/test/unit/extensions/hash/ts_all.rb

@@ -0,0 +1,13 @@
+#! /usr/bin/env ruby
+#
+# executes all other tests
+
+this_file   =   File.expand_path(__FILE__)
+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/extensions/string/tc_quote_if.rb

@@ -0,0 +1,42 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
+
+require 'xqsr3/extensions/string/quote_if'
+
+require 'xqsr3/extensions/test/unit'
+require 'test/unit'
+
+require 'stringio'
+
+class Test_String_quote_if < Test::Unit::TestCase
+
+	def test_String_has_method
+
+		assert ''.respond_to? :quote_if
+	end
+
+	def test_with_no_options
+
+		assert_equal '', ''.quote_if
+		assert_equal 'a', 'a'.quote_if
+		assert_equal 'ab', 'ab'.quote_if
+		assert_equal '"a b"', 'a b'.quote_if
+	end
+
+	def test_with_quotables
+
+		assert_equal 'a b', 'a b'.quote_if(quotables: '-')
+		assert_equal '"a-b"', 'a-b'.quote_if(quotables: '-')
+	end
+
+	def test_with_quotes
+
+		assert_equal '"a b"', 'a b'.quote_if
+		assert_equal '|a b|', 'a b'.quote_if(quotes: '|')
+		assert_equal '[a b]', 'a b'.quote_if(quotes: [ '[', ']' ])
+	end
+end
+
+
+

data/test/unit/quality/tc_parameter_checking.rb

@@ -221,7 +221,23 @@ end
 
 			assert(false, "wrong exception type #{x.class}) (with message '#{x.message}'")
 		end
+	end
+
+
+	# responds_to
 
+	def check_responds_to a, messages, options = {}, &block
+
+		self.class.check_param a, 'a', options.merge({ responds_to: messages }), &block
+	end
+
+	def test_responds_to
+
+		assert check_responds_to Hash.new, [ :[], :map, :to_s ]
+		assert_raise ::TypeError do
+
+			check_responds_to Hash.new, [ :this_is_not_a_Hash_method ]
+		end
 	end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.1
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-27 00:00:00.000000000 Z
+date: 2017-06-07 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -29,6 +29,7 @@ files:
 - lib/xqsr3/extensions/enumerable.rb
 - lib/xqsr3/extensions/enumerable/collect_with_index.rb
 - lib/xqsr3/extensions/enumerable/unique.rb
+- lib/xqsr3/extensions/hash/deep_transform.rb
 - lib/xqsr3/extensions/io.rb
 - lib/xqsr3/extensions/io/writelines.rb
 - lib/xqsr3/extensions/kernel.rb
@@ -36,16 +37,19 @@ files:
 - lib/xqsr3/extensions/string.rb
 - lib/xqsr3/extensions/string/ends_with.rb
 - lib/xqsr3/extensions/string/map_option_string.rb
+- lib/xqsr3/extensions/string/quote_if.rb
 - lib/xqsr3/extensions/string/starts_with.rb
 - lib/xqsr3/extensions/string/to_symbol.rb
 - lib/xqsr3/extensions/test/unit.rb
 - lib/xqsr3/extensions/test/unit/assert_eql.rb
 - lib/xqsr3/extensions/test/unit/assert_not.rb
 - lib/xqsr3/extensions/test/unit/assert_not_eql.rb
+- lib/xqsr3/hash_utilities/deep_transform.rb
 - lib/xqsr3/io/writelines.rb
 - lib/xqsr3/quality.rb
 - lib/xqsr3/quality/parameter_checking.rb
 - lib/xqsr3/string_utilities/ends_with.rb
+- lib/xqsr3/string_utilities/quote_if.rb
 - lib/xqsr3/string_utilities/starts_with.rb
 - lib/xqsr3/string_utilities/to_symbol.rb
 - lib/xqsr3/version.rb
@@ -59,12 +63,15 @@ files:
 - test/unit/extensions/enumerable/tc_collect_with_index.rb
 - test/unit/extensions/enumerable/tc_unique.rb
 - test/unit/extensions/enumerable/ts_all.rb
+- test/unit/extensions/hash/tc_deep_transform.rb
+- test/unit/extensions/hash/ts_all.rb
 - test/unit/extensions/io/tc_writelines.rb
 - test/unit/extensions/io/ts_all.rb
 - test/unit/extensions/kernel/tc_raise_with_options.rb
 - test/unit/extensions/kernel/ts_all.rb
 - test/unit/extensions/string/tc_ends_with.rb
 - test/unit/extensions/string/tc_map_option_string.rb
+- test/unit/extensions/string/tc_quote_if.rb
 - test/unit/extensions/string/tc_starts_with.rb
 - test/unit/extensions/string/tc_to_symbol.rb
 - test/unit/extensions/string/ts_all.rb