xqsr3 0.32.2 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d08b7ea53bfd21226d79bb36506890a7868ba93b
-  data.tar.gz: c4d23e493010555d8c3cfb27c515b469a47dd29f
+SHA256:
+  metadata.gz: 4e3f5e422b5b6d6f88ee0c0eb620f38ce468ef54e1cf9d55ab41f24e909c897b
+  data.tar.gz: 80f3675582a96f52a108687c4a77911691972dd0a2167138ffa0c9992c13e3ed
 SHA512:
-  metadata.gz: 34a1d293c2de8559801ec22e038a4e7fc33a7d6da5901411d84f1aa6ca67cd22295f690ecc501b166e9aa8777f5b00408473b467782ff129ebade29e0a0e15e0
-  data.tar.gz: 9e9a153905629a84437e69ea297ca7bbc843542a3ab90b35997d1e79d816ded0d90d2c2e8381c9db13ca6ffe6a4a8ae0691c2db5a7b4478a58efef4dc2e52ee4
+  metadata.gz: 41b2ac34f613f74b684223073ff61c3350b8433bda18520bb0af25db2464a22ed1be8fe53859eaf37f60d366d7053d8cab77d653b45b33a57ebd1a619b6186c6
+  data.tar.gz: 28d271b3501677420540ec6a55b1bf69bedf398dc422362ff7ca5e50e1d827d4f4fccc45c73eece170949bab755a47472d78f207a0b7c992cb942b13d368be76

data/lib/xqsr3/all_extensions.rb

@@ -0,0 +1,6 @@
+
+require File.join(File.dirname(__FILE__), 'extensions')
+
+require File.join(File.dirname(__FILE__), 'extensions', 'test', 'unit')
+
+

data/lib/xqsr3/array_utilities.rb

@@ -0,0 +1,10 @@
+
+%w{
+
+	join_with_or
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'array_utilities', name)
+end
+
+

data/lib/xqsr3/array_utilities/join_with_or.rb

@@ -56,6 +56,7 @@ require 'xqsr3/quality/parameter_checking'
 module Xqsr3
 module ArrayUtilities
 
+# +include+-able module that provides sequence-joining functionality
 module JoinWithOr
 
 	extend self
@@ -65,22 +66,14 @@ module JoinWithOr
 	# === Signature
 	#
 	# * *Parameters:*
-	#
-	# * *Required parameters*:
-	#   - +ar+:: [Array] The array whose contents are to be joined
-	#
-	# * *Options parameters*:
-	#   - +options+:: [Hash] Options that control the behaviour of the
-	#       method
+	#   - +ar+ (Array) The array whose contents are to be joined
+	#   - +options+ (Hash) Options that control the behaviour of the method
 	#
 	# * *Options:*
-	#
-	#   - +:or+:: [String] A string that is used instead of 'or'
-	#   - +:oxford_comma+:: [boolean] Determines whether an Oxford comma
-	#       will be used. Default is +true+
-	#   - +:quote_char+ [String] The quote character. Default is empty
-	#       string
-	#   - +:separator+ [String] The separator character. Default is +','+
+	#   - +:or+ (String) A string that is used instead of 'or'
+	#   - +:oxford_comma+ (boolean) Determines whether an Oxford comma will be used. Default is +true+
+	#   - +:quote_char+ (String) The quote character. Default is empty string ''
+	#   - +:separator+ (String) The separator character. Default is ','
 	def join_with_or ar, **options
 
 		::Xqsr3::Quality::ParameterChecking.check_parameter ar, 'ar', type: ::Array, allow_nil: true

data/lib/xqsr3/command_line_utilities.rb

@@ -0,0 +1,10 @@
+
+%w{
+
+	map_option_string
+}.each do |name|
+
+	require File.join(File.dirname(__FILE__), 'command_line_utilities', name)
+end
+
+

data/lib/xqsr3/command_line_utilities/map_option_string.rb

@@ -6,13 +6,13 @@
 #               ::Xqsr3::CommandLineUtilities::MapOptionString module
 #
 # Created:      15th April 2016
-# Updated:      2nd August 2017
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2016-2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -56,21 +56,21 @@ require 'xqsr3/string_utilities/to_symbol'
 module Xqsr3
 module CommandLineUtilities
 
-# Facilities for mapping strings to options
+# +include+-able module providing facilities for mapping strings to options
 #
 # === Components of interest
-# * ::Xqsr3::CommandLineUtilities::MapOptionString.map_option_string
+# * ::Xqsr3::CommandLineUtilities::MapOptionString.map_option_string_from_string
+# * ::Xqsr3::CommandLineUtilities::MapOptionString#map_option_string
 module MapOptionString
 
-	# :nodoc:
-	def self.included includer
+	def self.included includer # :nodoc:
 
 		raise TypeError, "module #{self} cannot be included into #{includer} because it does not respond to to_str" unless includer.method_defined? :to_str
 	end
 
 	private
-	# :nodoc:
-	module MapOptionString_Helper_ # :nodoc:
+	# @!visibility private
+	module MapOptionString_Helper_ # :nodoc: all
 
 		def self.map_option_string_with_options_ s, option_strings, options
 
@@ -117,6 +117,13 @@ module MapOptionString
 
 	# Attempts to translate the value of a given string according
 	# to a collection of options strings
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +s+ (::String) The string to be mapped
+	#   - +option_strings+ ([::String]) An array of strings against which the mapping will be performed
+	#   - +options+ (Hash) Options that control the behaviour of the method
 	def self.map_option_string_from_string s, option_strings, options = {}
 
 		MapOptionString_Helper_.map_option_string_with_options_ s, option_strings, options
@@ -124,6 +131,11 @@ module MapOptionString
 
 	# Attempts to translate the (string) value of the receiver according
 	# to a collection of options strings
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +option_strings+ ([::String]) An array of strings against which the mapping will be performed
 	def map_option_string option_strings, options = {}
 
 		s = self.kind_of?(::String) ? self : self.to_str
@@ -137,3 +149,4 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
+

data/lib/xqsr3/containers.rb

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

data/lib/xqsr3/containers/frequency_map.rb

@@ -5,7 +5,7 @@
 # Purpose:      FrequencyMap container
 #
 # Created:      28th January 2005
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -77,6 +77,7 @@ class FrequencyMap
 	#    fm[:z]    # => 0
 	ByElement = Class.new do
 
+		# Create an instance of Xqsr3::FrequencyMap from an array
 		def self.[] *args
 
 			fm = FrequencyMap.new
@@ -163,7 +164,7 @@ class FrequencyMap
 	# Pushes an element into the map, assigning it an initial count of 1
 	#
 	# * *Parameters:*
-	#   - +key+:: The element to insert
+	#   - +key+ The element to insert
 	def << key
 
 		push key, 1
@@ -180,12 +181,16 @@ class FrequencyMap
 
 		case	rhs
 		when	::NilClass
+
 			return false
 		when	::Hash
+
 			return rhs.size == @elements.size && rhs == @elements
 		when	self.class
+
 			return rhs.count == self.count && rhs == @elements
 		else
+
 			raise TypeError, "can compare #{self.class} only to instances of #{self.class} and #{::Hash}, but #{rhs.class} given"
 		end
 
@@ -407,6 +412,12 @@ class FrequencyMap
 
 	# Returns +true+ if an element with a count of the given +value+ is in the
 	# map; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +value+ (Integer) The value of the count for which to search
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +value+ is not an Integer
 	def has_value? value
 
 		case	value
@@ -437,6 +448,8 @@ class FrequencyMap
 #
 #		@elements.keep_if
 #	end
+=begin
+=end
 
 	# Returns the element that has the given count, or +nil+ if none found
 	#
@@ -540,6 +553,8 @@ class FrequencyMap
 		self
 	end
 
+	# Removes a key-value pair from the instance and return as a two-item
+	# array
 	def shift
 
 		r = @elements.shift
@@ -589,11 +604,13 @@ class FrequencyMap
 		@elements.to_hash
 	end
 
+	# A string-form of the instance
 	def to_s
 
 		@elements.to_s
 	end
 
+	# An array of all frequencies (without element keys) in the instance
 	def values
 
 		@elements.values

data/lib/xqsr3/containers/multi_map.rb

@@ -5,7 +5,7 @@
 # Purpose:      multimap container
 #
 # Created:      21st March 2007
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -53,10 +53,12 @@
 module Xqsr3
 module Containers
 
+# Hash-like class that stores as mapped values in arrays
 class MultiMap < ::Hash
 
 	include Enumerable
 
+	# Creates an instance from the given arguments
 	def self.[] *args
 
 		return self.new if 0 == args.length
@@ -71,16 +73,16 @@ class MultiMap < ::Hash
 				return self.new
 			when	::Hash
 
-				fm = self.new
+				mm = self.new
 
 				arg.each do |k, v|
 
 					raise ArgumentError, "mapped elements in hashes must be arrays, #{v.class} given" unless v.kind_of? ::Array
 
-					fm.store k, *v
+					mm.store k, *v
 				end
 
-				return fm
+				return mm
 			when	::Array
 
 				# accepted forms:
@@ -128,16 +130,31 @@ class MultiMap < ::Hash
 		end
 	end
 
+	# Initialises an instance
 	def initialize
 
+		@merge_is_multi = true
+
 		@inner	=	Hash.new
 	end
 
+	# Obtains the values, if any, for the given key; returns +nil+ if no
+	# values are stored
 	def [] key
 
 		return @inner[key]
 	end
 
+	# Adds/assigns a new key+values pair. Equivalent to
+	#
+	#   store(key, *values)
+	#
+	# * *Parameters:*
+	#   - +key+ The element key
+	#   - +values+ (Array) The values to be associated with the key
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +values+ is not an array
 	def []= key, values
 
 		values = [] if values.nil?
@@ -147,6 +164,13 @@ class MultiMap < ::Hash
 		store key, *values
 	end
 
+	# Compares the instance for equality against +rhs+
+	#
+	# * *Parameters:*
+	#   - +rhs+ (+nil+, +::Hash+, +MultiMap+) The instance to compare against
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +rhs+ is not of the required type(s)
 	def == rhs
 
 		case	rhs
@@ -163,29 +187,45 @@ class MultiMap < ::Hash
 		false
 	end
 
+	# Searches the instance comparing each element with +key+, returning the
+	# mapped values array if found, or +nil+ if not
 	def assoc key
 
 		@inner.assoc key
 	end
 
+	# Removes all elements from the instance
 	def clear
 
 		@inner.clear
 	end
 
+	# The total number of instances recorded
 	def count
 
 		@inner.each_value.map { |ar| ar.size}.inject(0, :+)
 	end
 
+	# Deletes all values mapped with the given +key+
+	#
+	# * *Parameters:*
+	#   - +key+ The key to delete
 	def delete key
 
 		@inner.delete key
 	end
 
+	# Calls _block_ once for each key-value pair, passing the key and each
+	# of its values in turn. If the values for a given key are empty and
+	# +defaults+ is not empty, the block is invoked for that key (with
+	# +defaults[0]+) once
+	#
+	# * *Exceptions:*
+	#   - +ArgumentError+ if more than 1 +defaults+ is provided, or no block is given
 	def each *defaults
 
 		raise ArgumentError, "may only supply 0 or 1 defaults" if defaults.size > 1
+		raise ArgumentError, 'block is required' unless block_given?
 
 		@inner.each do |key, values|
 
@@ -200,6 +240,8 @@ class MultiMap < ::Hash
 		end
 	end
 
+	# Calls _block_ once for each key in the instance, passing the key. If no
+	# block is provided, an enumerator is returned
 	def each_key
 
 		return @inner.each_key unless block_given?
@@ -207,26 +249,46 @@ class MultiMap < ::Hash
 		@inner.each_key { |key| yield key }
 	end
 
+	# Calls _block_ once for each key-values pair, passing the key and its
+	# values array. If no block is provided, an enumerator is returned
 	def each_unflattened
 
+		return @inner.each unless block_given?
+
 		@inner.each { |key, value| yield key, value }
 	end
 
+	# Calls _block_ once for each key-values pair, passing the key and its
+	# values array and a key index. If no block is provided, an enumerator
+	# is returned
 	def each_unflattened_with_index
 
+		return @inner.each_with_index unless block_given?
+
 		@inner.each_with_index { |kv, index| yield kv, index }
 	end
 
+	# Calls _block_ once for each value in the instance, passing the value.
+	# If no block is provided, an enumerator is returned
 	def each_value
 
+		return @inner.each_value unless block_given?
+
 		@inner.each do |key, values|
 
 			values.each { |value| yield value }
 		end
 	end
 
+	# Calls _block_ once for each key-values, passing the key and each of its
+	# values and a value index
+	#
+	# * *Exceptions:*
+	#   - +ArgumentError+ if no block is given
 	def each_with_index
 
+		raise ArgumentError, 'block is required' unless block_given?
+
 		index = 0
 		self.each do |key, value|
 
@@ -236,11 +298,14 @@ class MultiMap < ::Hash
 		end
 	end
 
+	# Returns +true+ if instance contains no elements; +false+ otherwise
 	def empty?
 
 		@inner.empty?
 	end
 
+	# Returns +true+ if +rhs+ is an instance of +MultiMap+ and contains
+	# the same elements and their counts; +false+ otherwise
 	def eql? rhs
 
 		case	rhs
@@ -251,18 +316,26 @@ class MultiMap < ::Hash
 		end
 	end
 
-	def fetch key, default = nil, &block
+	# Returns the values associated with the given key
+	#
+	# * *Parameters:*
+	#   - +key+ The key
+	#   - +default+ The default value
+	def fetch key, default = (default_parameter_defaulted_ = true; nil), &block
 
-		case	default
-		when	::NilClass, ::Array
-			;
-		else
-			raise TypeError, "default parameter ('#{default}') must be of type #{::Array}, but was of type #{default.class}"
+		unless default_parameter_defaulted_
+
+			case	default
+			when	::NilClass, ::Array
+				;
+			else
+				raise TypeError, "default parameter ('#{default}') must be of type #{::Array}, but was of type #{default.class}"
+			end
 		end
 
 		unless @inner.has_key? key
 
-			return default unless default.nil?
+			return default unless default_parameter_defaulted_
 
 			if block_given?
 
@@ -295,6 +368,7 @@ class MultiMap < ::Hash
 		@inner.fetch key
 	end
 
+	# Returns the equivalent flattened form of the instance
 	def flatten
 
 		r = []
@@ -316,36 +390,134 @@ class MultiMap < ::Hash
 		r
 	end
 
+	# Returns +true+ if an element with the given +key+ is in the map; +false+
+	# otherwise
 	def has_key? key
 
 		@inner.has_key? key
 	end
 
+	# Returns +true+ if any key has the given +value+; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +value+ The value for which to search
 	def has_value? value
 
-		@inner.has_value? value
+		@inner.each do |k, vals|
+
+			return true if vals.include? value
+		end
+
+		false
 	end
 
-	def key value
+	# Returns +true+ if any key has the given +values+; +false+ otherwise
+	#
+	# * *Parameters:*
+	#   - +values+ (Array) The values for which to search
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ if +value+ is not an Array
+	def has_values? values
 
-		@inner.key value
+		raise TypeError, "'values' parameter must be of type #{::Array}" unless Array === values
+
+		@inner.has_value? values
 	end
 
-	def merge fm
+	# Returns the key for the given value(s)
+	#
+	# * *Parameters:*
+	#   - +values+ (Array) The value(s) for which to search
+	#
+	# If a single value is specified, the entries in the instance are
+	# searched first for an exact match to all (1) value(s); if that fails,
+	# then the first key with a values containing the given value is
+	# returned
+	def key *values
+
+		case values.size
+		when 0
+
+			return nil
+		when 1
 
-		raise TypeError, "parameter must be an instance of type #{self.class}" unless fm.instance_of? self.class
+			i = nil
 
-		fm_new = self.class.new
+			@inner.each do |k, vals|
 
-		fm_new.merge! self
-		fm_new.merge! fm
+				return k if vals == values
 
-		fm_new
+				if i.nil?
+
+					i = k if vals.include? values[0]
+				end
+			end
+
+			return i
+		else
+
+			@inner.each do |key, vals|
+
+				return key if vals == values
+			end
+
+			return nil
+		end
 	end
 
-	def merge! fm
+	# The number of elements in the map
+	def length
 
-		fm.each do |k, v|
+		@inner.size
+	end
+
+	# Returns a new instance containing a merging of the current instance and
+	# the +other+ instance
+	#
+	# NOTE: where any key is found in both merging instances the values
+	# resulting will be a concatenation of the sets of values
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def multi_merge other
+
+		mm = self.class.new
+
+		mm.merge! self
+		mm.merge! other
+
+		mm
+	end
+
+	# Merges the contents of +other+ into the current instance
+	#
+	# NOTE: where any key is found in both merging instances the values
+	# resulting will be a concatenation of the sets of values
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def multi_merge! other
+
+		case other
+		when self.class
+
+			;
+		when ::Hash
+
+			;
+		else
+
+			raise TypeError, "parameter must be an instance of #{self.class} or #{Hash}"
+		end
+
+		other.each do |k, v|
 
 			self.push k, v
 		end
@@ -353,6 +525,96 @@ class MultiMap < ::Hash
 		self
 	end
 
+	# Returns a new instance containing a merging of the current instance and
+	# the +other+ instance
+	#
+	# NOTE: where any key is found in both merging instances the values from
+	# +other+ will be used
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def strict_merge other
+
+		mm = self.class.new
+
+		mm.strict_merge! self
+		mm.strict_merge! other
+
+		mm
+	end
+
+	# Merges the contents of +other+ into the current instance
+	#
+	# NOTE: where any key is found in both merging instances the values from
+	# +other+ will be used
+	#
+	# * *Parameters:*
+	#   - +other+ (MultiMap, Hash) The instance from which to merge
+	#
+	# * *Exceptions:*
+	#   - +TypeError+ Raised if +other+ is not a MultiMap or a Hash
+	def strict_merge! other
+
+		case other
+		when self.class
+
+			other.each_unflattened do |k, vals|
+
+				self.store k, *vals
+			end
+		when ::Hash
+
+			other.each do |k, v|
+
+				self.store k, v
+			end
+		else
+
+			raise TypeError, "parameter must be an instance of #{self.class} or #{Hash}"
+		end
+
+		self
+	end
+
+	# See #merge
+	def merge other
+
+		if @merge_is_multi
+
+			multi_merge other
+		else
+
+			strict_merge other
+		end
+	end
+
+	# See #merge!
+	def merge! other
+
+		if @merge_is_multi
+
+			multi_merge! other
+		else
+
+			strict_merge! other
+		end
+	end
+
+	# Pushes the given +key+ and +values+. If the +key+ is already in the
+	# map then the +values+ will be concatenated with those already present
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +key+ The element key
+	#   - +values+ (*Array) The value(s) to be pushed
+	#
+	# === Exceptions
+	#  - +::RangeError+ raised if the value of +count+ results in a negative count for the given element
+	#  - +::TypeError+ if +count+ is not an +::Integer+
 	def push key, *values
 
 		@inner[key] = [] unless @inner.has_key? key
@@ -360,33 +622,60 @@ class MultiMap < ::Hash
 		@inner[key].push(*values)
 	end
 
+	# Removes a key-value pair from the instance and return as a two-item
+	# array
 	def shift
 
 		@inner.shift
 	end
 
-	def size
-
-		@inner.size
-	end
+	alias size length
 
+	# Causes an element with the given +key+ and +values+ to be stored. If an
+	# element with the given +key+ already exists, its values will b
+	# replaced
 	def store key, *values
 
 		@inner[key] = values
 	end
 
+	# Converts instance to an array of +[key,value]+ pairs
 	def to_a
 
 		self.flatten
 	end
 
+	# Obtains reference to internal hash instance (which must *not* be modified)
 	def to_h
 
-		@inner.dup
+		@inner.to_h
 	end
 
+	# Obtains equivalent hash to instance
+	def to_hash
+
+		@elements.to_hash
+	end
+
+	# A string-form of the instance
+	def to_s
+
+		@inner.to_s
+	end
+
+	# An array of all values in the instance
 	def values
 
+		r	=	[]
+
+		@inner.values.each  { |vals| r += vals }
+
+		r
+	end
+
+	# An array of all sets of values in the instance
+	def values_unflattened
+
 		@inner.values
 	end
 end # class MultiMap