xqsr3 0.32.2 → 0.32.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d08b7ea53bfd21226d79bb36506890a7868ba93b
-  data.tar.gz: c4d23e493010555d8c3cfb27c515b469a47dd29f
+  metadata.gz: 5362a61770df81001025713c2465c5ed9bea6a49
+  data.tar.gz: 70f643bccc5e09b76acf3a4944e02dbe0e763d6a
 SHA512:
-  metadata.gz: 34a1d293c2de8559801ec22e038a4e7fc33a7d6da5901411d84f1aa6ca67cd22295f690ecc501b166e9aa8777f5b00408473b467782ff129ebade29e0a0e15e0
-  data.tar.gz: 9e9a153905629a84437e69ea297ca7bbc843542a3ab90b35997d1e79d816ded0d90d2c2e8381c9db13ca6ffe6a4a8ae0691c2db5a7b4478a58efef4dc2e52ee4
+  metadata.gz: 8cc83e03876a54224a4f4a28ea3ebf4ff289b2a4f8b11d1c727c41716a3ef68e670d10dd0f796d5b3273124b9308a0e4701fae02a030856f1183a2dafae3b2cb
+  data.tar.gz: 3b12d249383fddfde861575e9ed42a329220aba5b47f22204afdf0b5a3317290460004071e3c2d3a4c9590231b5eb61a01c38e1ca6f093ed2cd696ea7095469f

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

@@ -6,13 +6,13 @@
 #               ::Xqsr3::CommandLineUtilities::MapOptionString module
 #
 # Created:      15th April 2016
-# Updated:      2nd August 2017
+# Updated:      12th 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,20 +56,19 @@ 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:
 
 		def self.map_option_string_with_options_ s, option_strings, options
@@ -117,6 +116,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 +130,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 +148,4 @@ end # module Xqsr3
 
 # ############################## end of file ############################# #
 
+

data/lib/xqsr3/containers/frequency_map.rb

@@ -163,7 +163,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

data/lib/xqsr3/containers/multi_map.rb

@@ -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
@@ -128,11 +130,14 @@ class MultiMap < ::Hash
 		end
 	end
 
+	# Initialises an instance
 	def initialize
 
 		@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]
@@ -147,6 +152,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,21 +175,29 @@ 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
@@ -200,6 +220,8 @@ class MultiMap < ::Hash
 		end
 	end
 
+	# Calls _block_ once for each element 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?
@@ -236,11 +258,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
@@ -295,6 +320,7 @@ class MultiMap < ::Hash
 		@inner.fetch key
 	end
 
+	# Returns the equivalent flattened form of the instance
 	def flatten
 
 		r = []
@@ -316,6 +342,8 @@ 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

data/lib/xqsr3/conversion/bool_parser.rb

@@ -54,6 +54,7 @@
 module Xqsr3
 module Conversion
 
+# +include-able module that provides Boolean parsing
 module BoolParser
 
 	private
@@ -69,30 +70,26 @@ module BoolParser
 
 	public
 
+	# Recognised truey values
 	DEFAULT_TRUE_VALUES		=	[ /true/i, '1' ]
+	# Recognised falsey values
 	DEFAULT_FALSE_VALUES	=	[ /false/i, '0' ]
 
-	# Attempts to parse the given String to a Boolean value, based on the
+	# Attempts to parse the given string +s+ to a Boolean value, based on the
 	# given +options+
 	#
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +options+:: An options hash, containing any of the following options
+	#   - +s+ The string to be parsed
+	#   - +options+ An options hash, containing any of the following options
 	#
 	# * *Options:*
-	#   - +:false_values+:: [::Array] An array of strings or regular
-	#     expressions against which to match for false value. Defaults to
-	#     +DEFAULT_FALSE_VALUES+
-	#   - +:true_values+:: [::Array] An array of strings or regular
-	#     expressions against which to match for true value. Defaults to
-	#     +DEFAULT_TRUE_VALUES+
-	#   - +:default_value+:: An object to be returned if matching fails.
-	#     Defaults to +nil+
-	#   - +:false_value+:: An object to be returned if matching succeeds to
-	#     match against +:false_values+.
-	#   - +:true_value+:: An object to be returned if matching succeeds to
-	#     match against +:true_values+.
+	#   - +:false_values+ (::Array) An array of strings or regular expressions against which to match for false value. Defaults to +DEFAULT_FALSE_VALUES+
+	#   - +:true_values+ (::Array) An array of strings or regular expressions against which to match for true value. Defaults to +DEFAULT_TRUE_VALUES+
+	#   - +:default_value+ An object to be returned if matching fails.  Defaults to +nil+
+	#   - +:false_value+ An object to be returned if matching succeeds to match against +:false_values+. Defaults to +false+
+	#   - +:true_value+ An object to be returned if matching succeeds to match against +:true_values+. Defaults to +true+
 	def self.to_bool s, **options
 
 		true_values		=	options[:true_values] || DEFAULT_TRUE_VALUES

data/lib/xqsr3/conversion/integer_parser.rb

@@ -54,6 +54,7 @@
 module Xqsr3
 module Conversion
 
+# +include-able module that provides Integer parsing
 module IntegerParser
 
 	private
@@ -156,22 +157,14 @@ module IntegerParser
 	# === 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 4-parameter block -
-	#     taking the exception, +arg+, +base+, and +options+ - 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 4-parameter block - taking the exception, +arg+, +base+, and +options+ - 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 self.to_integer arg, base = 0, **options, &block
 
 		IntegerParser_Helper_.to_integer_ arg, base, options, &block

data/lib/xqsr3/diagnostics/exception_utilities.rb

@@ -100,8 +100,8 @@ module ExceptionUtilities
 	#
 	# === Parameters
 	#
-	# * +args+:: 0 or more arguments
-	# * +options+:: An options hash
+	# * +args+ 0 or more arguments
+	# * +options+ An options hash
 	#
 	# === Parameter Interpretation
 	#

data/lib/xqsr3/diagnostics/exceptions/with_cause.rb

@@ -5,13 +5,13 @@
 # Purpose:      Definition of the WithCause inclusion module
 #
 # Created:      16th December 2017
-# Updated:      5th September 2018
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2017-2018, 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
@@ -66,6 +66,7 @@ module Exceptions
 #
 module WithCause
 
+	# Array of hidden fields
 	INSPECT_HIDDEN_FIELDS = [ 'has_implicit_message', 'uses_cause_message' ]
 
 	# Defines an initializer for an exception class that allows a cause (aka
@@ -75,13 +76,11 @@ module WithCause
 	# === Signature
 	#
 	# * *Parameters:*
-	#  - 
-	#  - +option+:: 
+	#  - +args+ 0+ arguments passed through to the +include+-ing class' initialiser
+	#  - +options+ Options hash
 	#
 	# * *Options:*
-	#  - +:cause+ - The exception to be used as a cause, and ensures that
-	#    that is not inferred from the arguments. May be +nil+ to ensure
-	#    that no cause is inferred
+	#  - +:cause+ - The exception to be used as a cause, and ensures that that is not inferred from the arguments. May be +nil+ to ensure that no cause is inferred
 	def initialize(*args, **options)
 
 		@uses_cause_message = false
@@ -143,6 +142,15 @@ module WithCause
 	# present
 	attr_reader :options
 
+	# Message obtained by concatenation of all chained exceptions' messages
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#    - +options+ Options hash
+	#
+	# * *Options:*
+	#    - +:separator+ (String) A string used to separate each chained exception message. Defaults to ": "
 	def chained_message **options
 
 		return message unless cause

data/lib/xqsr3/diagnostics/inspect_builder.rb

@@ -5,13 +5,13 @@
 # Purpose:      ::Xqsr3::Diagnostics::InspectBuilder module
 #
 # Created:      4th September 2018
-# Updated:      5th September 2018
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2018-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -59,25 +59,21 @@ module InspectBuilder
 		NORMALISE_FUNCTION	=	lambda { |ar| ar.map { |v| v.to_s }.map { |v| '@' == v[0] ? v : "@#{v}" } }
 	end # module InspectBuilder_Utilities
 
+	# Generates an inspect string for the +include+-ing class
 	#
 	# === Signature
 	#
 	# * *Parameters:*
-	#  @param +o+:: The target of the +inspect+ message for which a message
-	#   will be built
+	#   - +o+ The target of the +inspect+ message for which a message will be built
 	#
 	# * *Options:*
-	#  @option +:no_class+:: (boolean) Elides the class qualification
-	#  @option +:no_object_id+:: (boolean) Elides the object id
-	#  @option +:show_fields+:: (boolean) Shows (all) object fields
-	#  @option +:hidden_fields+:: ([ String ]) Names of fields to be omitted
-	#   (when +:show_fields+ is specified). Overridden by +:shown_fields+
-	#  @option +:shown_fields+:: ([ String ]) Names of fields to be shown
-	#   (when +:show_fields+ is specified). Overrides +:hidden_fields+
-	#  @option +:truncate_width+:: (Integer) Specifies a maximum width for
-	#   the values of fields
-	#  @option +:deep_inspect+:: (boolean) Causes fields' values to be
-	#   obtained via their own +inspect+ methods
+	#   - +:no_class+ (boolean) Elides the class qualification
+	#   - +:no_object_id+ (boolean) Elides the object id
+	#   - +:show_fields+ (boolean) Shows (all) object fields
+	#   - +:hidden_fields+ ([ String ]) Names of fields to be omitted (when +:show_fields+ is specified). Overridden by +:shown_fields+
+	#   - +:shown_fields+ ([ String ]) Names of fields to be shown (when +:show_fields+ is specified). Overrides +:hidden_fields+
+	#   - +:truncate_width+ (Integer) Specifies a maximum width for the values of fields
+	#   - +:deep_inspect+ (boolean) Causes fields' values to be obtained via their own +inspect+ methods
 	def self.make_inspect o, **options
 
 		r	=	''

data/lib/xqsr3/doc_.rb

@@ -5,13 +5,13 @@
 # Purpose:      Documentation of the ::Xqsr3 modules
 #
 # Created:      10th June 2016
-# Updated:      10th June 2016
+# Updated:      12th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2016, 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
@@ -58,24 +58,36 @@
 # * ::Xqsr3::StringUtilities
 module Xqsr3
 
+	# Array utilities
+	#
+	# === Subordinate modules of interest
+	# * ::Xqsr3::ArrayUtilities::JoinWithOr
+	module ArrayUtilities
+	end # module ArrayUtilities
+
 	# Command-line Utilities
 	#
 	# === Subordinate modules of interest
 	# * ::Xqsr3::CommandLineUtilities::MapOptionString
 	module CommandLineUtilities
-
 	end # module CommandLineUtilities
 
 	# Containers
 	#
 	module Containers
-
 	end # module Containers
 
+	# Conversion
+	#
+	module Conversion
+	end # module Conversion
+
 	# Diagnostic facilities
 	#
 	# === Subordinate modules of interest
 	# * ::Xqsr3::Diagnostics::ExceptionUtilities
+	# * ::Xqsr3::Diagnostics::InspectBuilder
+	# * ::Xqsr3::Diagnostics::Exceptions::WithCause
 	#
 	module Diagnostics
 
@@ -86,31 +98,148 @@ module Xqsr3
 		#
 		module ExceptionUtilities
 		end # module ExceptionUtilities
+
+		# Inspect builder
+		#
+		module InspectBuilder
+		end # module InspectBuilder
+
+		# Exception-related utilities
+		#
+		# === Components of interest
+		# * ::Xqsr3::Diagnostics::Exceptions::WithCause
+		#
+		module Exceptions
+		end # module Exceptions
 	end # module Diagnostics
 
-	# IO
+	# Hash utilities
 	#
-	module IO
+	# === Subordinate modules of interest
+	# * ::Xqsr3::HashUtilities::DeepTransform
+	# * ::Xqsr3::HashUtilities::KeyMatching
+	module HashUtilities
 
-	end # module IO
+		# Exception-related utilities
+		#
+		# === Components of interest
+		# * ::Xqsr3::Diagnostics::HashUtilities::deep_transform
+		# * ::Xqsr3::Diagnostics::HashUtilities::deep_transform!
+		#
+		module DeepTransform
+		end # module DeepTransform
+	end # module HashUtilities
+
+	# IO
+	#
+	class IO
+	end # class IO
 
 	# Quality
 	#
 	# === Subordinate modules of interest
 	# * ::Xqsr3::Quality::ParameterChecking
 	module Quality
-
 	end # module Quality
 
 	# String utilities
 	#
 	# === Subordinate modules of interest
+	# * ::Xqsr3::StringUtilities::EndsWith
+	# * ::Xqsr3::StringUtilities::NilIfEmpty
+	# * ::Xqsr3::StringUtilities::NilIfWhitespace
+	# * ::Xqsr3::StringUtilities::QuoteIf
+	# * ::Xqsr3::StringUtilities::StartsWith
 	# * ::Xqsr3::StringUtilities::ToSymbol
+	# * ::Xqsr3::StringUtilities::Truncate
 	module StringUtilities
 
+=begin
+		 module EndsWith
+		 end # module EndsWith
+		 module NilIfEmpty
+		 end # module NilIfEmpty
+		 module NilIfWhitespace
+		 end # module NilIfWhitespace
+		 module QuoteIf
+		 end # module QuoteIf
+		 module StartsWith
+		 end # module StartsWith
+		 module ToSymbol
+		 end # module ToSymbol
+		 module Truncate
+		 end # module Truncate
+=end
 	end # module StringUtilities
-
 end # module Xqsr3
 
+# Standard class, extended with methods:
+#
+# - Array#join_with_or
+class Array; end
+
+# Standard module, extended with methods:
+#
+# - Enumerable#collect_with_index
+# - Enumerable#detect_map
+# - Enumerable#unique
+module Enumerable; end
+
+# Standard class, extended with methods:
+#
+# - Hash#deep_transform
+# - Hash#has_match?
+# - Hash#match
+class Hash; end
+
+# Standard class, extended with methods:
+#
+# - IO#writelines
+class IO; end
+
+# Standard module, extended with methods:
+#
+# - Kernel::Integer
+# - Kernel#raise_with_options
+module Kernel; end
+
+# Standard class, extended with methods:
+#
+# - String#ends_with?
+# - String#map_option_string
+# - String#nil_if_empty
+# - String#nil_if_whitespace
+# - String#quote_if
+# - String#starts_with?
+# - String#to_bool
+# - String#to_symbol
+# - String#truncate
+class String; end
+
+# Standard module
+module Test
+
+	# Standard module
+	module Unit
+
+		# Standard module
+		#
+		# === Components of interest
+		# * ::Test::Unit::Assertions#assert_eql
+		# * ::Test::Unit::Assertions#assert_false
+		# * ::Test::Unit::Assertions#assert_not
+		# * ::Test::Unit::Assertions#assert_not_eql
+		# * ::Test::Unit::Assertions#assert_raise_with_message
+		# * ::Test::Unit::Assertions#assert_subclass_of
+		# * ::Test::Unit::Assertions#assert_superclass_of
+		# * ::Test::Unit::Assertions#assert_true
+		# * ::Test::Unit::Assertions#assert_type_has_instance_methods
+		module Assertions
+		end # module Assertions
+	end # module Unit
+end # module Test
+
+
 # ############################## end of file ############################# #
 
+