xqsr3 0.38.1.1 → 0.39.1

data/lib/xqsr3/diagnostics/exception_utilities.rb

@@ -1,17 +1,18 @@
 
 # ######################################################################## #
-# File:         lib/xqsr3/diagnostics/exception_utilities.rb
+# File:     lib/xqsr3/diagnostics/exception_utilities.rb
 #
-# Purpose:      Definition of the ExceptionUtilities module
+# Purpose:  Definition of the ExceptionUtilities module
 #
-# Created:      12th February 2015
-# Updated:      2nd August 2017
+# Created:  12th February 2015
+# Updated:  29th March 2024
 #
-# Home:         http://github.com/synesissoftware/xqsr3
+# Home:     http://github.com/synesissoftware/xqsr3
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
-# Copyright (c) 2015-2017, Matthew Wilson and Synesis Software
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2015-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -25,7 +26,7 @@
 #   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
+# * Neither the names of the copyright holders nor the names of its
 #   contributors may be used to endorse or promote products derived from
 #   this software without specific prior written permission.
 #
@@ -55,161 +56,161 @@ module Diagnostics
 
 module ExceptionUtilities
 
-	# Raises an instance of a named exception that takes options in its
-	# constructor, as in:
-	#
-	#     class ArgumentErrorWithOptions < ArgumentError
-	#
-	#       def initialize(message = nil, **options)
-	#
-	#         . . .
-	#       end
-	#
-	#       attr_reader :options
-	#     end
-	#
-	#     begin
-	#
-	#       raise_with_options ArgumentErrorWithOptions, "message-1", opt1: :val1, opt2: 'val2'
-	#     rescue => x
-	#
-	#       $stderr.puts x.options # => {:opt1=>:val1, :opt2=>"val2"}
-	#     end
-	#
-	# It can also be used with full compatibility with <tt>Kernel#raise</tt>, as in:
-	#
-	#     begin
-	#
-	#       raise_with_options ArgumentError, "message-2"
-	#     rescue => x
-	#
-	#       $stderr.puts x.class # => ArgumenError
-	#       $stderr.puts x.message # => "message-2"
-	#     end
-	#
-	# and:
-	#
-	#     begin
-	#
-	#       raise_with_options "message-3"
-	#     rescue => x
-	#
-	#       $stderr.puts x.class # => RuntimeError
-	#       $stderr.puts x.message # => "message-3"
-	#     end
-	#
-	# === Parameters
-	#
-	# * +args+ 0 or more arguments
-	# * +options+ An options hash
-	#
-	# === Parameter Interpretation
-	#
-	# If the first argument is a class, it is assumed to be the exception
-	# type that will be raised; if not, RuntimeError is raised as is normal
-	# with Kernel#raise. The remaining arguments are passed - via the
-	# <tt>*</tt> operator - to the class's constructor.
-	#
-	# All options passed to this method are respread - by the
-	# <tt>**</tt> operator - and passed to the underlying
-	# <tt>Kernel#raise</tt> call.
-	#
-	# === Exceptions
-	#
-	# - An instance of <tt>arg[0]</tt> if <tt>args[0].is_a?(::Class)</tt>; or
-	# - An instance of +RuntimeError+
-	def self.raise_with_options *args, **options
-
-		# special handling in case called indirectly
-
-		called_indirectly	=	options[:called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96]
-
-		case called_indirectly
-		when nil, false
-
-			called_indirectly	=	0
-		when true
-
-			called_indirectly	=	1
-		when ::Integer
-
-			;
-		else
-
-			abort "indirect-call option (#{called_indirectly}) has invalid type (#{called_indirectly.class})"
-		end
-
-		options.delete :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 if called_indirectly
-
-
-		# Use cases:
-		#
-		# 1. No options
-		# 2. Non-class and options
-		# 3. Class and options
-		#   3.a Class and options
-		#   3.b Class and options and message
-		#   3.c Class and options and message and call-stack
-
-		class_given = args.size > 0 && args[0].is_a?(::Class)
-
-		if class_given && !options.empty?
-
-			exception_class_or_instance_or_message_string = args.shift
-
-			# 3. Class and options
-
-			#   3.a Class and options
-			#   3.b Class and options and message
-			#   3.c Class and options and message and call-stack
-
-
-			xargs	=	[]
-
-			xargs	<<	args.shift unless args.empty?
-
-			x		=	exception_class_or_instance_or_message_string.new(*xargs, **options)
-
-			rargs	=	[]
-			rargs	<<	x
-			rargs	+=	[ nil, args.shift ] unless args.empty?
-
-			# now need to trim backtrace
+  # Raises an instance of a named exception that takes options in its
+  # constructor, as in:
+  #
+  #     class ArgumentErrorWithOptions < ArgumentError
+  #
+  #       def initialize(message = nil, **options)
+  #
+  #         . . .
+  #       end
+  #
+  #       attr_reader :options
+  #     end
+  #
+  #     begin
+  #
+  #       raise_with_options ArgumentErrorWithOptions, "message-1", opt1: :val1, opt2: 'val2'
+  #     rescue => x
+  #
+  #       $stderr.puts x.options # => {:opt1=>:val1, :opt2=>"val2"}
+  #     end
+  #
+  # It can also be used with full compatibility with <tt>Kernel#raise</tt>, as in:
+  #
+  #     begin
+  #
+  #       raise_with_options ArgumentError, "message-2"
+  #     rescue => x
+  #
+  #       $stderr.puts x.class # => ArgumenError
+  #       $stderr.puts x.message # => "message-2"
+  #     end
+  #
+  # and:
+  #
+  #     begin
+  #
+  #       raise_with_options "message-3"
+  #     rescue => x
+  #
+  #       $stderr.puts x.class # => RuntimeError
+  #       $stderr.puts x.message # => "message-3"
+  #     end
+  #
+  # === Parameters
+  #
+  # * +args+ 0 or more arguments
+  # * +options+ An options hash
+  #
+  # === Parameter Interpretation
+  #
+  # If the first argument is a class, it is assumed to be the exception
+  # type that will be raised; if not, RuntimeError is raised as is normal
+  # with Kernel#raise. The remaining arguments are passed - via the
+  # <tt>*</tt> operator - to the class's constructor.
+  #
+  # All options passed to this method are respread - by the
+  # <tt>**</tt> operator - and passed to the underlying
+  # <tt>Kernel#raise</tt> call.
+  #
+  # === Exceptions
+  #
+  # - An instance of <tt>arg[0]</tt> if <tt>args[0].is_a?(::Class)</tt>; or
+  # - An instance of +RuntimeError+
+  def self.raise_with_options *args, **options
+
+    # special handling in case called indirectly
+
+    called_indirectly = options[:called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96]
+
+    case called_indirectly
+    when nil, false
+
+      called_indirectly = 0
+    when true
+
+      called_indirectly = 1
+    when ::Integer
+
+      ;
+    else
+
+      abort "indirect-call option (#{called_indirectly}) has invalid type (#{called_indirectly.class})"
+    end
+
+    options.delete :called_indirectly_06d353cb_5a6c_47ca_8dbe_ff76359c7e96 if called_indirectly
+
+
+    # Use cases:
+    #
+    # 1. No options
+    # 2. Non-class and options
+    # 3. Class and options
+    #   3.a Class and options
+    #   3.b Class and options and message
+    #   3.c Class and options and message and call-stack
+
+    class_given = args.size > 0 && args[0].is_a?(::Class)
+
+    if class_given && !options.empty?
+
+      exception_class_or_instance_or_message_string = args.shift
+
+      # 3. Class and options
+
+      #   3.a Class and options
+      #   3.b Class and options and message
+      #   3.c Class and options and message and call-stack
+
+
+      xargs = []
+
+      xargs << args.shift unless args.empty?
+
+      x = exception_class_or_instance_or_message_string.new(*xargs, **options)
+
+      rargs = []
+      rargs << x
+      rargs += [ nil, args.shift ] unless args.empty?
+
+      # now need to trim backtrace
 
-			begin
+      begin
 
-				Kernel.raise(*rargs)
-			rescue => x
+        Kernel.raise(*rargs)
+      rescue => x
 
-				bt = x.backtrace
-				(0..called_indirectly).each { bt.shift }
-				Kernel.raise x, x.message, bt
-			end
-		end
+        bt = x.backtrace
+        (0..called_indirectly).each { bt.shift }
+        Kernel.raise x, x.message, bt
+      end
+    end
 
-		unless options.empty?
+    unless options.empty?
 
-			# 2. Non-class and options
+      # 2. Non-class and options
 
-			warn "cannot utilise options in raise_with_options when first argument is non-class"
-		else
+      warn "cannot utilise options in raise_with_options when first argument is non-class"
+    else
 
-			# 1. No options
-		end
+      # 1. No options
+    end
 
 
-		# now need to trim backtrace
+    # now need to trim backtrace
 
-		begin
+    begin
 
-			Kernel.raise(*args)
-		rescue => x
+      Kernel.raise(*args)
+    rescue => x
 
-			bt = x.backtrace
-			(0..called_indirectly).each { bt.shift }
-			Kernel.raise x, x.message, bt
-		end
-	end
+      bt = x.backtrace
+      (0..called_indirectly).each { bt.shift }
+      Kernel.raise x, x.message, bt
+    end
+  end
 end # module ExceptionUtilities
 
 end # module Diagnostics

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

@@ -1,16 +1,17 @@
 
 # ######################################################################## #
-# File:         lib/xqsr3/diagnostics/exceptions/with_cause.rb
+# File:     lib/xqsr3/diagnostics/exceptions/with_cause.rb
 #
-# Purpose:      Definition of the WithCause inclusion module
+# Purpose:  Definition of the WithCause inclusion module
 #
-# Created:      16th December 2017
-# Updated:      12th April 2019
+# Created:  16th December 2017
+# Updated:  29th March 2024
 #
-# Home:         http://github.com/synesissoftware/xqsr3
+# Home:     http://github.com/synesissoftware/xqsr3
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2017-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -25,7 +26,7 @@
 #   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
+# * Neither the names of the copyright holders nor the names of its
 #   contributors may be used to endorse or promote products derived from
 #   this software without specific prior written permission.
 #
@@ -66,139 +67,142 @@ module Exceptions
 #
 module WithCause
 
-	# Array of hidden fields
-	INSPECT_HIDDEN_FIELDS = [ 'has_implicit_message', 'uses_cause_message' ]
+  # 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
-	# an inner exception) to be specified, either as the first or last
-	# argument or as a +:cause+ option
-	#
-	# === Signature
-	#
-	# * *Parameters:*
-	#  - +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
-	def initialize(*args, **options)
+  # Defines an initializer for an exception class that allows a cause (aka
+  # an inner exception) to be specified, either as the first or last
+  # argument or as a +:cause+ option
+  #
+  # === Signature
+  #
+  # * *Parameters:*
+  #  - +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
+  def initialize(*args, **options)
 
-		@uses_cause_message = false
+    @uses_cause_message = false
 
-		cz = options[:cause]
+    cz = options[:cause]
 
-		if cz
+    if cz
 
-			options = options.reject { |k, v| k == :cause }
+      options = options.reject { |k, v| k == :cause }
 
-			@has_implicit_message = args.empty?
+      @has_implicit_message = args.empty?
 
-			super(*args)
+      super(*args)
 
-			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
+      warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
 
-			@cause = cz
-		else
+      @cause = cz
+    else
 
-			cz_ix = args.index { |arg| ::Exception === arg }
+      cz_ix = args.index { |arg| ::Exception === arg }
 
-			if cz_ix
+      if cz_ix
 
-				args = args.dup
+        args = args.dup
 
-				cz = args.delete_at cz_ix
+        cz = args.delete_at cz_ix
 
-				if args.empty?
+        if args.empty?
 
-					if !(cz.message || '').empty? && cz.class.to_s != cz.message
+          if !(cz.message || '').empty? && cz.class.to_s != cz.message
 
-						@uses_cause_message = true
+            @uses_cause_message = true
 
-						args = [ cz.message ]
-					end
-				end
-			else
+            args = [ cz.message ]
+          end
+        end
+      else
 
-				cz = $!
-			end
+        cz = $!
+      end
 
-			@has_implicit_message = args.empty?
+      @has_implicit_message = args.empty?
 
-			super(*args)
+      super(*args)
 
-			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
+      warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
 
-			@cause = cz
-		end
+      @cause = cz
+    end
 
-		@options = options
-	end
+    @options = options
+  end
 
-	# The cause / inner-exception, if any, specified to the instance
-	# initialiser
-	attr_reader :cause
+  # The cause / inner-exception, if any, specified to the instance
+  # initialiser
+  attr_reader :cause
 
-	# The options passed to the initialiser, with +:cause+ removed, if
-	# present
-	attr_reader :options
+  # The options passed to the initialiser, with +:cause+ removed, if
+  # 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
+  # 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
-		return message if @uses_cause_message
+    return message unless cause
+    return message if @uses_cause_message
 
-		m	=	message
-		c	=	cause
-		cm	=	c.respond_to?(:chained_message) ? c.chained_message(**options) : c.message
+    m = message
+    c = cause
+    cm = c.respond_to?(:chained_message) ? c.chained_message(**options) : c.message
 
-		return m if (cm || '').empty?
-		return cm if (m || '').empty?
+    return m if (cm || '').empty?
+    return cm if (m || '').empty?
 
-		sep	=	options[:separator] || ': '
+    sep = options[:separator] || ': '
 
-		"#{m}#{sep}#{cm}"
-	end
+    "#{m}#{sep}#{cm}"
+  end
 
-	# An array of exceptions in the chain, excluding +self+
-	def chainees
+  # An array of exceptions in the chain, excluding +self+
+  def chainees
 
-		return [] unless cause
+    return [] unless cause
 
-		r = [ cause ]
+    r = [ cause ]
 
-		r += cause.chainees if cause.respond_to? :chainees
+    r += cause.chainees if cause.respond_to? :chainees
 
-		r
-	end
+    r
+  end
 
-	# An array of exceptions in the chain, including +self+
-	def exceptions
+  # An array of exceptions in the chain, including +self+
+  def exceptions
 
-		[ self ] + chainees
-	end
+    [ self ] + chainees
+  end
 
-	# A combination of the backtrace(s) of all chained exception(s)
-	def chained_backtrace
+  # A combination of the backtrace(s) of all chained exception(s)
+  def chained_backtrace
 
-		b = backtrace
+    b = backtrace
 
-		return b unless cause
+    return b unless cause
 
-		cb = cause.respond_to?(:chained_backtrace) ? cause.chained_backtrace : cause.backtrace
+    cb = cause.respond_to?(:chained_backtrace) ? cause.chained_backtrace : cause.backtrace
 
-		(cb - b) + b
-	end
+    (cb - b) + b
+  end
 end
 
 end # module Exceptions
 end # module Diagnostics
 end # module Xqsr3
+
+# ############################## end of file ############################# #
+