xqsr3 0.32.2 → 0.36.0

data/lib/xqsr3/conversion.rb

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

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

@@ -6,7 +6,7 @@
 #               module
 #
 # Created:      21st November 2017
-# Updated:      12th April 2019
+# Updated:      15th April 2019
 #
 # Home:         http://github.com/synesissoftware/xqsr3
 #
@@ -54,10 +54,12 @@
 module Xqsr3
 module Conversion
 
+# +include-able module that provides Integer parsing
 module IntegerParser
 
 	private
-	module IntegerParser_Helper_ # :nodoc:
+	# @!visibility private
+	module IntegerParser_Helper_ # :nodoc: all
 
 		if Kernel.respond_to?(:xqsr3_Integer_original_method)
 
@@ -156,22 +158,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.rb

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

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
@@ -54,30 +54,28 @@ module Diagnostics
 
 module InspectBuilder
 
-	module InspectBuilder_Utilities
+	# @!visibility private
+	module InspectBuilder_Utilities # :nodoc: all
 
+		# @!visibility private
 		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	=	''
@@ -161,6 +159,8 @@ module InspectBuilder
 	end
 
 	# Creates an inspect string from self
+	#
+	# see InspectBuilder::make_inspect
 	def make_inspect **options
 
 		::Xqsr3::Diagnostics::InspectBuilder.make_inspect self, **options

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 ############################# #
 
+