xqsr3 0.17.2 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18672bcef5bd6994d1ff9c2dc5be6289ca79042e
-  data.tar.gz: cc79b90f538dbdc1273853d73d4b13cea0fab110
+  metadata.gz: fdaa43c901071d88f6fe3737998e4cd6a741c69b
+  data.tar.gz: c6876d3f0814a79a4c9a37bcb313c834ebae4096
 SHA512:
-  metadata.gz: 16ae7d901c5ef0a916497c34fb9edfb342c0f774071a1b6f3de6a922c452d1de639caee0e587c18e566a7164b4b5303dff2ab09acb03624dc4edcb1df954cde4
-  data.tar.gz: d77073d7e4fdcc461c75b5ab6d2e522573f113647b72cf7db16e3e7c8c209403cb37d5bbac96fda35cf697594f84b0ae88864e06a975785f7cbd6838de5352a6
+  metadata.gz: 308f153ed24f39fa50494df2099e8978b5aa55c99b5b016a48ab03e73f9cff058f00d8056364a87695fe16497a0c1b3d70225c9146b4fb1e23bd4fd2cef250ca
+  data.tar.gz: 7590f907009d95b6057aec1573d7841c39ea2bbd8ff0713fa29356ae3d3836e39121c587285144db6d6f8e05019744caf493c6ead4682d1e648354b2e66c4c46

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

@@ -0,0 +1,194 @@
+
+# ######################################################################## #
+# File:         lib/xqsr3/diagnostics/exceptions/with_cause.rb
+#
+# Purpose:      Definition of the WithCause inclusion module
+#
+# Created:      16th December 2017
+# Updated:      17th December 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::Diagnostics::Exceptions::WithCause
+
+=begin
+=end
+
+module Xqsr3
+module Diagnostics
+module Exceptions
+
+# This inclusion module adds to an exception class the means to chain a
+# cause (aka inner-exception), which is then exposed with the +cause+
+# attribute
+#
+# *Examples:*
+#
+# Passing an exception cause as a parameter
+#
+#
+#
+module WithCause
+
+	# 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:*
+	#  - 
+	#  - +option+:: 
+	#
+	# * *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
+
+		cz = options[:cause]
+
+		if cz
+
+			options = options.reject { |k, v| k == :cause }
+
+			@has_implicit_message = args.empty?
+
+			super *args
+
+			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
+
+			@cause = cz
+		else
+
+			cz_ix = args.index { |arg| ::Exception === arg }
+
+			if cz_ix
+
+				args = args.dup
+
+				cz = args.delete_at cz_ix
+
+				if args.empty?
+
+					if !(cz.message || '').empty? && cz.class.to_s != cz.message
+
+						@uses_cause_message = true
+
+						args = [ cz.message ]
+					end
+				end
+			else
+
+				cz = $!
+			end
+
+			@has_implicit_message = args.empty?
+
+			super *args
+
+			warn 'unexpected implicit message' if @has_implicit_message && self.message != self.class.to_s
+
+			@cause = cz
+		end
+
+		@options = options
+	end
+
+	# 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
+
+	def chained_message **options
+
+		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
+
+		return m if (cm || '').empty?
+		return cm if (m || '').empty?
+
+		sep	=	options[:separator] || ': '
+
+		"#{m}#{sep}#{cm}"
+	end
+
+	# An array of exceptions in the chain, excluding +self+
+	def chainees
+
+		return [] unless cause
+
+		r = [ cause ]
+
+		r += cause.chainees if cause.respond_to? :chainees
+
+		r
+	end
+
+	# An array of exceptions in the chain, including +self+
+	def exceptions
+
+		[ self ] + chainees
+	end
+
+	# A combination of the backtrace(s) of all chained exception(s)
+	def chained_backtrace
+
+		b = backtrace
+
+		return b unless cause
+
+		cb = cause.respond_to?(:chained_backtrace) ? cause.chained_backtrace : cause.backtrace
+
+		(cb - b) + b
+	end
+end
+
+end # module Exceptions
+end # module Diagnostics
+end # module Xqsr3

data/lib/xqsr3/version.rb

@@ -50,7 +50,7 @@
 module Xqsr3
 
 	# Current version of the Xqsr3 library
-	VERSION				=	'0.17.2'
+	VERSION				=	'0.18.1'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/diagnostics/exceptions/tc_with_cause.rb

@@ -0,0 +1,262 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../../../lib')
+
+require 'xqsr3/diagnostics/exceptions/with_cause'
+
+require 'test/unit'
+
+class Test_WithCause < Test::Unit::TestCase
+
+	class SomeExceptionWithCause < ::Exception
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+	end
+
+	def test_no_ctor_args
+
+		x = SomeExceptionWithCause.new
+
+		assert_nil x.cause
+		assert_equal SomeExceptionWithCause.to_s, x.message
+		assert_equal SomeExceptionWithCause.to_s, x.chained_message
+		assert_empty x.chainees
+		assert_equal [ x ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_1_ctor_arg_that_is_a_message
+
+		msg = 'stuff'
+
+		x = SomeExceptionWithCause.new msg
+
+		assert_nil x.cause
+		assert_equal msg, x.message
+		assert_equal msg, x.chained_message
+		assert_empty x.chainees
+		assert_equal [ x ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_1_ctor_arg_that_is_a_cause_and_has_no_message
+
+		c = RuntimeError.new
+
+		x = SomeExceptionWithCause.new c
+
+		assert_not_nil x.cause
+		assert_equal SomeExceptionWithCause.to_s, x.message
+		assert_equal "#{SomeExceptionWithCause.to_s}: #{RuntimeError.to_s}", x.chained_message
+		assert_not_empty x.chainees
+		assert_equal [ c ], x.chainees
+		assert_equal [ x, c ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_1_ctor_arg_that_is_a_cause_and_has_a_message
+
+		c = RuntimeError.new 'blah'
+
+		x = SomeExceptionWithCause.new c
+
+		assert_not_nil x.cause
+		assert_equal 'blah', x.message
+		assert_equal 'blah', x.chained_message
+		assert_not_empty x.chainees
+		assert_equal [ c ], x.chainees
+		assert_equal [ x, c ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_2_ctor_args_that_are_message_and_cause
+
+		msg = 'stuff'
+
+		c = RuntimeError.new
+
+		x = SomeExceptionWithCause.new msg, c
+
+		assert_not_nil x.cause
+		assert_equal msg, x.message
+		assert_equal "#{msg}: #{RuntimeError.to_s}", x.chained_message
+		assert_not_empty x.chainees
+		assert_equal [ c ], x.chainees
+		assert_equal [ x, c ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_2_ctor_args_that_are_message_and_cause_that_has_a_message
+
+		msg = 'stuff'
+
+		c = RuntimeError.new 'blah'
+
+		x = SomeExceptionWithCause.new msg, c
+
+		assert_not_nil x.cause
+		assert_equal msg, x.message
+		assert_equal 'stuff: blah', x.chained_message
+
+		assert_not_empty x.chainees
+		assert_equal [ c ], x.chainees
+		assert_equal [ x, c ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+	def test_cause_in_options
+
+		c = RuntimeError.new 'inner'
+
+		x = SomeExceptionWithCause.new 'outer', cause: c
+
+		assert_not_nil x.cause
+		assert_equal 'outer', x.message
+		assert_equal 'outer: inner', x.chained_message
+
+		assert_not_empty x.chainees
+		assert_equal [ c ], x.chainees
+		assert_equal [ x, c ], x.exceptions
+		assert_nil x.backtrace
+		assert_empty x.options
+	end
+
+
+
+	class GrandchildException < Exception
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+	end
+
+	class ChildException < Exception
+
+		def initialize(*args, **options)
+
+			super *args, **options
+		end
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+	end
+
+	class ParentException < Exception
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+
+		def initialize(*args, **options)
+
+			super *args, **options
+		end
+	end
+
+	class GrandparentException < Exception
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+	end
+
+
+	def test_four_levels
+
+		gc = GrandchildException.new 'gc'
+
+		c = ChildException.new 'c', gc
+
+		p = ParentException.new c, 'p'
+
+		gp = GrandparentException.new 'gp', cause: p
+
+		assert_equal 'gp: p: c: gc', gp.chained_message
+		assert_equal 'gp-p-c-gc', gp.chained_message(separator: '-')
+	end
+end
+
+class Test_WithCause_throwing < Test::Unit::TestCase
+
+	class SomeExceptionWithCause < ::Exception
+
+		include ::Xqsr3::Diagnostics::Exceptions::WithCause
+	end
+
+	def f m
+
+		raise SomeExceptionWithCause, m
+	end
+
+	def g m, n
+
+		begin
+
+			f n
+		rescue Exception => x
+
+			raise SomeExceptionWithCause.new m, x
+		end
+	end
+
+	def h m, n, o
+
+		begin
+
+			g n, 0
+		rescue Exception => x
+
+			raise SomeExceptionWithCause.new m, x
+		end
+	end
+
+	def test_one_level
+
+		begin
+
+			f 'one-level'
+
+			assert false, 'should not get here!'
+		rescue Exception => x
+
+			assert_nil x.cause
+			assert_equal 'one-level', x.message
+			assert_equal 'one-level', x.chained_message
+			assert_empty x.chainees
+			assert_not_empty x.backtrace
+
+			x_bt0 = x.backtrace[0]
+
+			assert /:in\s+\`f\'\s*$/ =~ x_bt0, 'not receieved from f()'
+		end
+	end
+
+	def test_two_levels
+
+		begin
+
+			g 'two-levels', 'one-level'
+
+			assert false, 'should not get here!'
+		rescue Exception => x
+
+			assert_not_nil x.cause
+			assert_equal 'two-levels', x.message
+			assert_equal 'two-levels: one-level', x.chained_message
+			assert_not_empty x.chainees
+			assert_kind_of SomeExceptionWithCause, x.chainees[0]
+			assert_not_empty x.backtrace
+			assert_not_empty x.cause.backtrace
+
+			x_bt0 = x.backtrace[0]
+
+			assert /:in\s+\`rescue in g\'\s*$/ =~ x_bt0, 'not receieved from g()'
+
+			c_bt0 = x.cause.backtrace[0]
+
+			assert /:in\s+\`f\'\s*$/ =~ c_bt0, 'not receieved from f()'
+
+			assert_not_empty x.chained_backtrace
+		end
+	end
+end
+

data/test/unit/diagnostics/exceptions/ts_all.rb

@@ -0,0 +1,12 @@
+#! /usr/bin/env ruby
+#
+# executes all other tests
+
+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 }
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xqsr3
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.18.1
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-16 00:00:00.000000000 Z
+date: 2017-12-17 00:00:00.000000000 Z
 dependencies: []
 description: |
   eXtensions by fine Quantum for Standard Ruby and 3rd-party libraries is a
@@ -25,6 +25,7 @@ files:
 - lib/xqsr3/containers/multi_map.rb
 - lib/xqsr3/conversion/bool_parser.rb
 - lib/xqsr3/diagnostics/exception_utilities.rb
+- lib/xqsr3/diagnostics/exceptions/with_cause.rb
 - lib/xqsr3/doc_.rb
 - lib/xqsr3/extensions/array/join_with_or.rb
 - lib/xqsr3/extensions/enumerable/collect_with_index.rb
@@ -73,6 +74,8 @@ files:
 - test/unit/containers/ts_all.rb
 - test/unit/conversion/tc_to_bool.rb
 - test/unit/conversion/ts_all.rb
+- test/unit/diagnostics/exceptions/tc_with_cause.rb
+- test/unit/diagnostics/exceptions/ts_all.rb
 - test/unit/diagnostics/tc_exception_utilities.rb
 - test/unit/diagnostics/ts_all.rb
 - test/unit/extensions/enumerable/tc_collect_with_index.rb