pantheios-ruby 0.20.3.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f5bcc837f0b87b903fe88c0b5d1eb3f2c8193a3
-  data.tar.gz: 6e4acd4a1a86ae3df1f04d5ab506c1f0b0722666
+  metadata.gz: beccaa832a0515a050313c91e674a3804ffe4ac5
+  data.tar.gz: 2d1e8e82b8f7999578c9898afc94730e86e165d2
 SHA512:
-  metadata.gz: 5d7eff164a890518c3fabca3612d6f5810a554235831838e6a98c47562061924d37e09300e610de1cef8759c9c6ee582b695020b0fd6297c69e82802c9f814d2
-  data.tar.gz: 873c24a5b54e6711d498e06e0c20c335a81fc2f737c0fa1da634c8b5faa2767c6da49743611481ef6c9a446f39953255a500b3bb526854a2e02e1ef997fc285d
+  metadata.gz: 06cfa816a8c31242ea15e6673064c136ccf7b1457f8ed399c165426c2515879c3f3d465aae57f302c3880bcee8b6ef7101e95c93f0526a5b0c9c6eeb521453c1
+  data.tar.gz: 3887176f2effa59a70304a4c8b5c8da013bf122f9d8882042955767c700b747ceea39d859d0351430fecc08ec32fabfc73f09513cf0d50c3367e22cbe58ef188

data/examples/multiple_modules.md

@@ -0,0 +1,204 @@
+# Pantheios.Ruby Example - **multiple_modules**
+
+## Summary
+
+Example showing application of Pantheios into multiple modules and
+suppression of arbitrary severity levels specified as command line
+arguments
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# ######################################
+# requires
+
+require 'pantheios'
+
+# ######################################
+# modules
+
+module Organisation
+
+module Helpers
+
+	include ::Pantheios
+
+	def with_trace
+
+		trace
+	end
+
+	def with_debug0; log(:debug0); end
+	def with_debug1; log(:debug1); end
+	def with_informational; log(:informational); end
+	def with_notice; log(:notice); end
+	def with_warning; log(:warning); end
+	def with_failure; log(:failure); end
+	def with_critical; log(:critical); end
+	def with_alert; log(:alert); end
+
+	def helper1
+
+		trace
+
+		with_debug0
+
+		with_notice
+	end
+
+end # module Helpers
+
+class OrgClass
+
+	include Helpers
+	include ::Pantheios
+
+	def initialize()
+
+		trace
+
+		log(:debug2) { 'initialised instance of OrgClass' }
+
+		helper1
+	end
+
+end # class OrgClas
+
+end # module Organisation
+
+# ######################################
+# includes
+
+include ::Organisation::Helpers
+
+include ::Pantheios
+
+# ######################################
+# constants
+
+SUPPRESSED_SEVERITIES = %i{
+
+
+}
+
+# ######################################
+# diagnostics
+
+def detect_suppression argv
+
+	argv.each do |arg|
+
+		SUPPRESSED_SEVERITIES << arg.to_sym
+	end
+end
+
+class FrontEnd
+
+	def severity_logged? severity
+
+		case severity
+		when ::Symbol
+
+			!SUPPRESSED_SEVERITIES.include?(severity)
+		else
+
+			true
+		end
+	end
+end
+
+Pantheios::Core.set_front_end FrontEnd.new
+
+# ######################################
+# main
+
+detect_suppression ARGV
+
+log(:some_level)
+
+log(:notice, 'starting up')
+
+puts "Suppressed severities: #{SUPPRESSED_SEVERITIES}"
+
+log(:info) { "Calling helpers" }
+
+with_trace
+
+with_debug0
+with_debug1
+helper1
+with_critical
+with_alert
+
+log(:info) { "Creating instance of OrgClass" }
+
+oc = Organisation::OrgClass.new
+
+# ############################## end of file ############################# #
+
+```
+
+
+## Usage
+
+### No arguments
+
+When executed as follows
+
+```
+$ ./examples/multiple_modules.rb
+```
+
+it gives the following output:
+
+```
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853720, some_level]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853882, Notice]: starting up
+Suppressed severities: []
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853971, Informational]: Calling helpers
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854134, Trace]: ./examples/multiple_modules.rb:21: Object#with_trace()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854200, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854255, Debug-1]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854333, Trace]: ./examples/multiple_modules.rb:35: Object#helper1()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854386, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854522, Notice]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854582, Critical]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854631, Alert]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854684, Informational]: Creating instance of OrgClass
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854772, Trace]: ./examples/multiple_modules.rb:51: Organisation::OrgClass#initialize()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854852, Debug-2]: initialised instance of OrgClass
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854930, Trace]: ./examples/multiple_modules.rb:35: Organisation::OrgClass#helper1()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854985, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.855035, Notice]:
+```
+
+### Some named suppressed levels
+
+When executed as follows
+
+```
+$ ./examples/multiple_modules.rb trace debug2
+```
+
+it gives the following output:
+
+```
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.201933, some_level]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202013, Notice]: starting up
+Suppressed severities: [:trace, :debug2]
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202050, Informational]: Calling helpers
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202073, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202091, Debug-1]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202110, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202125, Notice]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202167, Critical]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202199, Alert]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202243, Informational]: Creating instance of OrgClass
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202269, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202286, Notice]:
+```
+

data/examples/multiple_modules.rb

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# ######################################
+# requires
+
+require 'pantheios'
+
+# ######################################
+# modules
+
+module Organisation
+
+module Helpers
+
+	include ::Pantheios
+
+	def with_trace
+
+		trace
+	end
+
+	def with_debug0; log(:debug0); end
+	def with_debug1; log(:debug1); end
+	def with_informational; log(:informational); end
+	def with_notice; log(:notice); end
+	def with_warning; log(:warning); end
+	def with_failure; log(:failure); end
+	def with_critical; log(:critical); end
+	def with_alert; log(:alert); end
+
+	def helper1
+
+		trace
+
+		with_debug0
+
+		with_notice
+	end
+
+end # module Helpers
+
+class OrgClass
+
+	include Helpers
+	include ::Pantheios
+
+	def initialize()
+
+		trace
+
+		log(:debug2) { 'initialised instance of OrgClass' }
+
+		helper1
+	end
+
+end # class OrgClas
+
+end # module Organisation
+
+# ######################################
+# includes
+
+include ::Organisation::Helpers
+
+include ::Pantheios
+
+# ######################################
+# constants
+
+SUPPRESSED_SEVERITIES = %i{
+
+
+}
+
+# ######################################
+# diagnostics
+
+def detect_suppression argv
+
+	argv.each do |arg|
+
+		SUPPRESSED_SEVERITIES << arg.to_sym
+	end
+end
+
+class FrontEnd
+
+	def severity_logged? severity
+
+		case severity
+		when ::Symbol
+
+			!SUPPRESSED_SEVERITIES.include?(severity)
+		else
+
+			true
+		end
+	end
+end
+
+Pantheios::Core.set_front_end FrontEnd.new
+
+# ######################################
+# main
+
+detect_suppression ARGV
+
+log(:some_level)
+
+log(:notice, 'starting up')
+
+puts "Suppressed severities: #{SUPPRESSED_SEVERITIES}"
+
+log(:info) { "Calling helpers" }
+
+with_trace
+
+with_debug0
+with_debug1
+helper1
+with_critical
+with_alert
+
+log(:info) { "Creating instance of OrgClass" }
+
+oc = Organisation::OrgClass.new
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/application_layer/stock_severity_levels.rb

@@ -7,12 +7,13 @@
 #               namespace module
 #
 # Created:      2nd April 2011
-# Updated:      12th March 2018
+# Updated:      3rd June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2011-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -59,20 +60,21 @@ module StockSeverityLevels
 
 		STOCK_SEVERITY_LEVELS_ = {
 
-			:violation => [ 1, 'Violation', [ :emergency ] ],
-			:alert => [ 2, 'Alert' ],
-			:critical => [ 3, 'Critical' ],
-			:failure => [ 4, 'Failure' ],
-			:warning => [ 5, 'Warning', [ :warn ] ],
-			:notice => [ 6, 'Notice' ],
-			:informational => [ 7, 'Informational', [ :info ] ],
-			:debug0 => [ 8, 'Debug-0' ],
-			:debug1 => [ 9, 'Debug-1' ],
-			:debug2 => [ 10, 'Debug-2' ],
-			:debug3 => [ 11, 'Debug-3' ],
-			:debug4 => [ 12, 'Debug-4' ],
-			:trace => [ 15, 'Trace' ],
-			:benchmark => [ 16, 'Benchmark' ],
+			:violation => [ 1, 'Violation', :relative, [ :emergency ] ],
+			:alert => [ 2, 'Alert', :relative ],
+			:critical => [ 3, 'Critical', :relative ],
+			:failure => [ 4, 'Failure', :relative, [ :fail ] ],
+			:warning => [ 5, 'Warning', :relative, [ :warn ] ],
+			:notice => [ 6, 'Notice', :relative ],
+			:informational => [ 7, 'Informational', :relative, [ :info ] ],
+			:debug0 => [ 8, 'Debug-0', :relative ],
+			:debug1 => [ 9, 'Debug-1', :relative ],
+			:debug2 => [ 10, 'Debug-2', :relative ],
+			:debug3 => [ 11, 'Debug-3', :relative ],
+			:debug4 => [ 12, 'Debug-4', :relative ],
+			:debug5 => [ 13, 'Debug-5', :relative ],
+			:trace => [ 15, 'Trace', :relative ],
+			:benchmark => [ 16, 'Benchmark', :separate ],
 		}
 
 		def self.create_level_keys m
@@ -81,7 +83,7 @@ module StockSeverityLevels
 
 			m.each do |k, ar|
 
-				(ar[2] || []).each do |al|
+				(ar[3] || []).each do |al|
 
 					r << al
 				end
@@ -99,7 +101,7 @@ module StockSeverityLevels
 				warn 'invalid start-up' unless ::Symbol === s
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				([s] + (ar[3] || [])).each do |al|
 
 					r[al] = ar[0]
 				end
@@ -107,6 +109,7 @@ module StockSeverityLevels
 
 			r
 		end
+
 		def self.create_level_string_map m
 
 			r = {}
@@ -116,7 +119,7 @@ module StockSeverityLevels
 				warn 'invalid start-up' unless ::Symbol === s
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				([s] + (ar[3] || [])).each do |al|
 
 					r[al] = ar[1]
 				end
@@ -124,20 +127,74 @@ module StockSeverityLevels
 
 			r
 		end
+
+		def self.create_level_aliases m
+
+			r = {}
+
+			m.each do |s, ar|
+
+				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Array === ar
+
+				([s] + (ar[3] || [])).each do |al|
+
+					r[al] = s
+				end
+			end
+
+			r
+		end
+
+		def self.create_level_relative_map m
+
+			r = {}
+
+			m.each do |s, ar|
+
+				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Array === ar
+
+				relativity = ar[2]
+
+				case relativity
+				when :relative
+
+					([s] + (ar[3] || [])).each do |al|
+
+						r[al] = relativity
+					end
+				else
+
+					;
+				end
+			end
+
+			r
+		end
 	end
 	public
 
-	# Ordered list of stock severity levels, without any aliases
+	# Ordered list of stock severity level symbols, without any aliases
 	STOCK_SEVERITY_LEVELS_PRIME = Internal_::STOCK_SEVERITY_LEVELS_.keys
 
-	# Ordered list of stock severity levels, some of which may be aliases
+	# Unordered list of stock severity levels, some of which may be aliases
 	STOCK_SEVERITY_LEVELS = Internal_.create_level_keys Internal_::STOCK_SEVERITY_LEVELS_
 
-	# Mapping of severity levels (and level aliases) to integral
+	# Mapping of severity level aliases - with may be symbols and strings -
+	# to the prime stock severity level symbols
+	STOCK_SEVERITY_LEVEL_ALIASES = Internal_.create_level_aliases Internal_::STOCK_SEVERITY_LEVELS_
+
+	# Mapping of severity level aliases - with may be symbols and strings -
+	# containing only those levels that are relative, i.e. may participate
+	# meaningfully in a threshold-based filtering
+	STOCK_SEVERITY_LEVELS_RELATIVE = Internal_.create_level_relative_map Internal_::STOCK_SEVERITY_LEVELS_
+
+	# Mapping of severity level (and level alias) symbols to integral
 	# equivalent
 	STOCK_SEVERITY_LEVEL_VALUES = Internal_.create_level_value_map Internal_::STOCK_SEVERITY_LEVELS_
 
-	# Mapping of severity levels (and level aliases) to string
+	# Mapping of severity level (and level alias) symbols to string
 	STOCK_SEVERITY_LEVEL_STRINGS = Internal_.create_level_string_map Internal_::STOCK_SEVERITY_LEVELS_
 
 end # module StockSeverityLevels

data/lib/pantheios/front_ends/threshold_front_end.rb

@@ -0,0 +1,135 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/front_ends/threshold_front_end.rb
+#
+# Purpose:      Definition of the ::Pantheios::FrontEnds::ThresholdFrontEnd
+#               class
+#
+# Created:      3rd June 2020
+# Updated:      3rd June 2020
+#
+# Home:         http://github.com/synesissoftware/Pantheios-Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2020, Matthew Wilson and Synesis Information Systems
+# 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.
+#
+# ######################################################################## #
+
+
+=begin
+=end
+
+require 'pantheios/application_layer/stock_severity_levels'
+
+module Pantheios
+module FrontEnds
+
+# A class that fulfils the Pantheios *FrontEnd* protocol that implements
+# +severity_logged?+ based on a threshold specified to the initialiser
+#
+# NOTE: The *FrontEnd* protocol is implemented by a class that provides
+# the instance method +severity_logged?(severity : Object)+
+class ThresholdFrontEnd
+
+	include ::Pantheios::ApplicationLayer
+
+	# Initialises the instance
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +threshold_severity+ [ ::Symbol ] The threshold severity
+	#
+	# * *Options:*
+	#   - +value_lookup_map+ [ ::Hash ] A map that is used to lookup
+	#     +severity+ values (that are not +::Integer+) in
+	#     +severity_logged?+. May be +nil+, in which case
+	#     +::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES+
+	#     is used
+	def initialize(threshold_severity, **options)
+
+		m = options[:value_lookup_map]
+
+		raise TypeError, "value given for :value_lookup_map must be a #{::Hash}" if m && !m.respond_to?(:to_hash)
+
+		if m
+
+			@value_lookup_map = m
+			@relativity_lookup_map = ::Hash.new(:relative)
+		else
+
+			@value_lookup_map = StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES
+			@relativity_lookup_map = StockSeverityLevels::STOCK_SEVERITY_LEVELS_RELATIVE
+		end
+
+		self.threshold = threshold_severity
+	end
+
+	def severity_logged? severity
+
+		case severity
+		when ::Integer
+
+			v = severity
+		else
+
+			v = @value_lookup_map[severity] or warn "unknown severity level '#{severity}' (#{severity.class})"
+		end
+
+		return true if v.nil?
+
+		v <= @threshold_v
+	end
+
+	# assigns the threshold
+	#
+	# * *Parameters:*
+	#   - +threshold_severity+ [ ::Symbol ] The threshold severity
+	def threshold=(threshold_severity)
+
+		raise TypeError, "threshold_severity must be a #{::Symbol}" unless ::Symbol === threshold_severity
+
+		@threshold_v = @value_lookup_map[threshold_severity] if @relativity_lookup_map[threshold_severity] or raise ArgumentError, "unknown threshold severity level '#{threshold_severity}' (#{threshold_severity.class})"
+		@threshold = threshold_severity
+
+		nil
+	end
+	attr_reader :threshold
+
+end # class ThresholdFrontEnd
+
+end # module FrontEnds
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/globals.rb

@@ -5,12 +5,13 @@
 # Purpose:      The Pantheios.Ruby "globals" (::Pantheios::Globals)
 #
 # Created:      24th December 2017
-# Updated:      4th February 2018
+# Updated:      3rd June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -57,6 +58,18 @@ module Pantheios
 #
 # === Variables
 #
+# * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
+#   +::Pantheios+ also includes all relevant parts of subordinate
+#   namespaces. See the documentation for the +::Pantheios+ namespace for
+#   further details
+#
+# * *INITIAL_SERVICE_CLASSES* [ svc-class, [ svc-class ] ] Specifies
+#   the service class(es) that will be used to create the initial service
+#   instance. Ignored if INITIAL_SERVICE_INSTANCES specifies an instance
+#
+# * *INITIAL_SERVICE_INSTANCES* [ svc-instance, [ svc-instance ] ] Specifies
+#   the initial service instance
+#
 # * *MAIN_THREAD_NAME* A string specifying the main thread name, or an array
 #   containing a thread instance and a string specifying the thread and its
 #   name
@@ -65,11 +78,6 @@ module Pantheios
 #   form is used then the first initialising thread of Pantheios.Ruby will
 #   be the named thread
 #
-# * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
-#   +::Pantheios+ also includes all relevant parts of subordinate
-#   namespaces. See the documentation for the +::Pantheios+ namespace for
-#   further details
-#
 # * *PROCESS_NAME* A string specifying the process name, or one of the
 #   recognised symbols - :script, :script_basename, :script_dirname,
 #   :script_realpath, :script_stem - that directs inference of the process

data/lib/pantheios/util/reflection_util.rb

@@ -9,6 +9,8 @@ module ReflectionUtil
 		ROOT_CLASSES = [ ::Object, ::BasicObject ]
 	end
 
+	# Obtains a list of all classes pertaining to +o+, excepting root
+	# objects (+::Object+ and +::BaseObject+).
 	def self.non_root_classes o
 
 		return [] if o.nil?

data/lib/pantheios/util/thread_util.rb

@@ -22,6 +22,7 @@ module ThreadUtil
 		t.thread_name = name
 	end
 
+	# Obtains the name of the calling thread
 	def self.get_thread_name t
 
 		t ||= Thread.current

data/lib/pantheios/version.rb

@@ -5,12 +5,13 @@
 # Purpose:      Version for Pantheios.Ruby library
 #
 # Created:      2nd April 2011
-# Updated:      5th June 2019
+# Updated:      3rd June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2011-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -50,7 +51,7 @@
 module Pantheios
 
 	# Current version of the Pantheios.Ruby library
-	VERSION				=	'0.20.3.1'
+	VERSION				=	'0.21.0'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/unit/application_layer/tc_stock_severity_levels.rb

@@ -26,12 +26,15 @@ class Test_StockSeverityLevels < Test::Unit::TestCase
 		debug2
 		debug3
 		debug4
+		debug5
 		trace
+		benchmark
 	}.map { |s| s.to_sym }
 
 	EXPECTED_LEVELS = %w{
 
 		emergency
+		fail
 		info
 		warn
 	}.map { |s| s.to_sym } + EXPECTED_LEVELS_PRIME
@@ -51,6 +54,7 @@ class Test_StockSeverityLevels < Test::Unit::TestCase
 		if defined? StockSeverityLevels
 
 			assert StockSeverityLevels.const_defined?(:STOCK_SEVERITY_LEVELS)
+			assert StockSeverityLevels.const_defined?(:STOCK_SEVERITY_LEVELS_PRIME)
 			assert StockSeverityLevels.const_defined?(:STOCK_SEVERITY_LEVEL_VALUES)
 			assert StockSeverityLevels.const_defined?(:STOCK_SEVERITY_LEVEL_STRINGS)
 		end
@@ -58,18 +62,36 @@ class Test_StockSeverityLevels < Test::Unit::TestCase
 
 	def test_StockSeverityLevels_expected_levels
 
+		# all the ones that we expect exist
+
 		EXPECTED_LEVELS.each do |sev|
 
 			assert(StockSeverityLevels::STOCK_SEVERITY_LEVELS.include?(sev), "did not find level #{::Symbol === sev ? ':' : ''}#{sev} in #{StockSeverityLevels}::STOCK_SEVERITY_LEVELS")
 		end
+
+		# we expect all the ones that exist
+
+		StockSeverityLevels::STOCK_SEVERITY_LEVELS.each do |sev|
+
+			assert(EXPECTED_LEVELS.include?(sev), "found unexpected level #{::Symbol === sev ? ':' : ''}#{sev} in #{StockSeverityLevels}::STOCK_SEVERITY_LEVELS")
+		end
 	end
 
 	def test_StockSeverityLevels_expected_prime_levels
 
+		# all the ones that we expect exist
+
 		EXPECTED_LEVELS_PRIME.each do |sev|
 
 			assert(StockSeverityLevels::STOCK_SEVERITY_LEVELS_PRIME.include?(sev), "did not find level #{::Symbol === sev ? ':' : ''}#{sev} in #{StockSeverityLevels}::STOCK_SEVERITY_LEVELS")
 		end
+
+		# we expect all the ones that exist
+
+		StockSeverityLevels::STOCK_SEVERITY_LEVELS_PRIME.each do |sev|
+
+			assert(EXPECTED_LEVELS_PRIME.include?(sev), "found unexpected level #{::Symbol === sev ? ':' : ''}#{sev} in #{StockSeverityLevels}::STOCK_SEVERITY_LEVELS")
+		end
 	end
 
 	def test_StockSeverityLevels_expected_prime_levels_have_distinct_values
@@ -99,5 +121,50 @@ class Test_StockSeverityLevels < Test::Unit::TestCase
 			strings[string] = string
 		end
 	end
+
+	def test_StockSeverityLevels_aliases
+
+		aliases = StockSeverityLevels::STOCK_SEVERITY_LEVEL_ALIASES
+
+		assert_equal :violation, aliases[:violation]
+		assert_equal :violation, aliases[:emergency]
+
+		assert_equal :alert, aliases[:alert]
+
+		assert_equal :critical, aliases[:critical]
+
+		assert_equal :failure, aliases[:failure]
+		assert_equal :failure, aliases[:fail]
+		#assert_equal :failure, aliases[:error]
+
+		assert_equal :warning, aliases[:warning]
+		assert_equal :warning, aliases[:warn]
+
+		assert_equal :notice, aliases[:notice]
+
+		assert_equal :informational, aliases[:informational]
+		assert_equal :informational, aliases[:info]
+
+		%i{ debug0 debug1 debug2 debug3 debug4 debug5 }.each do |sev|
+
+			assert_equal sev, aliases[sev]
+		end
+
+		assert_equal :trace, aliases[:trace]
+
+		assert_equal :benchmark, aliases[:benchmark]
+	end
+
+	def test_StockSeverityLevels_recognised_values_are_nil
+
+		EXPECTED_LEVELS.each do |sev|
+
+			assert_not_nil StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES[sev]
+			assert_nil StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES[sev.to_s]
+		end
+
+		assert_nil StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES[nil]
+		assert_nil StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES['failure']
+	end
 end
 

data/test/unit/front_ends/tc_threshold_front_end.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../..', 'lib')
+
+require 'pantheios/front_ends/threshold_front_end'
+
+require 'test/unit'
+
+class Test_FrontEnds_ThresholdFrontEnd < Test::Unit::TestCase
+
+	include ::Pantheios::FrontEnds
+
+	def test_SimpleConsoleLogService_type_exists
+
+		assert defined? ThresholdFrontEnd
+	end
+
+	def test_construct_with_invalid_parameters
+
+		assert_raise(::TypeError) { ThresholdFrontEnd.new('notice') }
+
+		assert_raise_with_message(::ArgumentError, /unknown threshold severity level.*something_else.*Symbol/) { ThresholdFrontEnd.new(:something_else) }
+
+		ThresholdFrontEnd.new(:notice)
+		ThresholdFrontEnd.new(:notice, value_lookup_map: Hash.new)
+		assert_raise_with_message(::TypeError, /:value_lookup_map must be.*Hash/) { ThresholdFrontEnd.new(:notice, value_lookup_map: Array.new) }
+	end
+
+	def test_default_construct
+
+		fe = ThresholdFrontEnd.new(:notice)
+
+		assert_equal :notice, fe.threshold
+
+		assert_true fe.severity_logged?(:violation)
+		assert_true fe.severity_logged?(:alert)
+		assert_true fe.severity_logged?(:critical)
+		assert_true fe.severity_logged?(:failure)
+		assert_true fe.severity_logged?(:warning)
+		assert_true fe.severity_logged?(:notice)
+		assert_false fe.severity_logged?(:informational)
+		assert_false fe.severity_logged?(:debug0)
+		assert_false fe.severity_logged?(:debug1)
+		assert_false fe.severity_logged?(:debug2)
+		assert_false fe.severity_logged?(:debug3)
+		assert_false fe.severity_logged?(:debug4)
+		assert_false fe.severity_logged?(:debug5)
+		assert_false fe.severity_logged?(:trace)
+	end
+
+	def test_default_construct_and_change_threshold
+
+		fe = ThresholdFrontEnd.new(:notice)
+
+		assert_equal :notice, fe.threshold
+
+		fe.threshold = :failure
+
+		assert_equal :failure, fe.threshold
+
+		assert_true fe.severity_logged?(:violation)
+		assert_true fe.severity_logged?(:alert)
+		assert_true fe.severity_logged?(:critical)
+		assert_true fe.severity_logged?(:failure)
+		assert_false fe.severity_logged?(:warning)
+		assert_false fe.severity_logged?(:notice)
+		assert_false fe.severity_logged?(:informational)
+		assert_false fe.severity_logged?(:debug0)
+		assert_false fe.severity_logged?(:debug1)
+		assert_false fe.severity_logged?(:debug2)
+		assert_false fe.severity_logged?(:debug3)
+		assert_false fe.severity_logged?(:debug4)
+		assert_false fe.severity_logged?(:debug5)
+		assert_false fe.severity_logged?(:trace)
+	end
+
+	def test_use_custom_thresholds
+
+		value_lookup_map = {
+
+			FATAL: 1,
+			ERROR: 2,
+			WARN: 3,
+			INFO: 4,
+			DEBUG: 5,
+		}
+
+		fe = ThresholdFrontEnd.new(:INFO, value_lookup_map: value_lookup_map)
+
+		assert_equal :INFO, fe.threshold
+
+		assert_true fe.severity_logged?(:FATAL)
+		assert_true fe.severity_logged?(:ERROR)
+		assert_true fe.severity_logged?(:WARN)
+		assert_true fe.severity_logged?(:INFO)
+		assert_false fe.severity_logged?(:DEBUG)
+	end
+end
+
+# ############################## end of file ############################# #
+
+

data/test/unit/front_ends/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 }
+

data/test/unit/services/tc_multiplexing_log_service.rb

@@ -89,7 +89,7 @@ class Test_MultiplexingLogservice < Test::Unit::TestCase
 
 			log_multiple_statements svc
 
-			assert_equal 11, svc_0.items.size
+			assert_equal 12, svc_0.items.size
 			assert_equal  4, svc_1.items.size
 			assert_equal  6, svc_2.items.size
 		end
@@ -104,7 +104,7 @@ class Test_MultiplexingLogservice < Test::Unit::TestCase
 
 			log_multiple_statements svc
 
-			assert_equal 11, svc_0.items.size
+			assert_equal 12, svc_0.items.size
 			assert_equal  4, svc_1.items.size
 			assert_equal  6, svc_2.items.size
 		end
@@ -119,7 +119,7 @@ class Test_MultiplexingLogservice < Test::Unit::TestCase
 
 			log_multiple_statements svc
 
-			assert_equal 11, svc_0.items.size
+			assert_equal 12, svc_0.items.size
 			assert_equal  4, svc_1.items.size
 			assert_equal  6, svc_2.items.size
 		end
@@ -134,7 +134,7 @@ class Test_MultiplexingLogservice < Test::Unit::TestCase
 
 			log_multiple_statements svc
 
-			assert_equal 11, svc_0.items.size
+			assert_equal 12, svc_0.items.size
 			assert_equal  4, svc_1.items.size
 			assert_equal  6, svc_2.items.size
 		end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pantheios-ruby
 version: !ruby/object:Gem::Version
-  version: 0.20.3.1
+  version: 0.21.0
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-02 00:00:00.000000000 Z
+date: 2020-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xqsr3
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.31'
+        version: '0.36'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.31'
+        version: '0.36'
 description: 'A Ruby version of the popular C++ (and .NET) logging API library
 
 '
@@ -34,6 +34,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- examples/multiple_modules.md
+- examples/multiple_modules.rb
 - examples/simple_logging.md
 - examples/simple_logging.rb
 - lib/pantheios.rb
@@ -42,6 +44,7 @@ files:
 - lib/pantheios/application_layer/param_name_list.rb
 - lib/pantheios/application_layer/stock_severity_levels.rb
 - lib/pantheios/core.rb
+- lib/pantheios/front_ends/threshold_front_end.rb
 - lib/pantheios/globals.rb
 - lib/pantheios/services.rb
 - lib/pantheios/services/multiplexing_log_service.rb
@@ -67,6 +70,8 @@ files:
 - test/unit/application_layer/ts_all.rb
 - test/unit/core/tc_core_1.rb
 - test/unit/core/ts_all.rb
+- test/unit/front_ends/tc_threshold_front_end.rb
+- test/unit/front_ends/ts_all.rb
 - test/unit/services/tc_multiplexing_log_service.rb
 - test/unit/services/tc_null_log_service.rb
 - test/unit/services/tc_simple_console_log_service.rb