pantheios-ruby 0.20.2 → 0.22.0.2

data/lib/pantheios/front_ends/threshold_front_end.rb

@@ -0,0 +1,148 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/front_ends/threshold_front_end.rb
+#
+# Purpose:      Definition of the ::Pantheios::FrontEnds::ThresholdFrontEnd
+#               class
+#
+# Created:      3rd June 2020
+# Updated:      4th 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
+
+	# 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
+	#
+	# * *Exceptions:*
+	#   - +::TypeError+ raised if a value given for +:value_lookup_map+ is
+	#     not a ::hash
+	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 = ::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES
+			@relativity_lookup_map = ::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVELS_RELATIVE
+		end
+
+		self.threshold = threshold_severity
+	end
+
+	# Determines whether a given severity is logged
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +severity+:: The severity level, which should be a known log
+	#   severity symbol or an integral equivalent
+	#
+	# * *Returns:*
+	#   a +truey+ value if the severity should be logged; a +falsey+ value
+	#   otherwise
+	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
@@ -81,7 +89,8 @@ module Pantheios
 #
 module Globals
 
-	module Internals_
+	# @!visibility private
+	module Internals_ # :nodoc: all
 
 		BOOLEAN_CLASSES			=	[ ::FalseClass, ::TrueClass ]
 		TRUTHY_CLASSES			=	BOOLEAN_CLASSES + [ ::NilClass ]
@@ -89,7 +98,8 @@ module Globals
 		PROCESS_NAME_CLASSES	=	[ ::Symbol, ::String ]
 	end
 
-	module Helpers_
+	# @!visibility private
+	module Helpers_ # :nodoc: all
 
 		def self.cattr receiver, name, types, initial_value, **options
 
@@ -138,7 +148,8 @@ module Globals
 
 	Helpers_.cattr self, 'SYNCHRONISED_SEVERITY_LOGGED', nil, true, boolean: true
 
-	def self.included receiver
+	# @!visibility private
+	def self.included receiver # :nodoc:
 
 		abort "Attempt to include #{self} into #{receiver}. This is not allowed"
 	end

data/lib/pantheios/services/coloured_console_log_service.rb

@@ -0,0 +1,204 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/services/coloured_console_log_service.rb
+#
+# Purpose:      Definition of the
+#               ::Pantheios::Services::ColouredConsoleLogService class
+#
+# Created:      19th June 2019
+# Updated:      4th June 2020
+#
+# Home:         http://github.com/synesissoftware/Pantheios-Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019, 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.
+#
+# ######################################################################## #
+
+
+require 'pantheios/services/common/console'
+
+=begin
+=end
+
+module Pantheios
+module Services
+
+# A class that fulfils the Pantheios *LogService* protocol that allows all
+# severities and logs to the console (via +$stdout+ and +$stderr+)
+#
+# NOTE: The *LogService* protocol is implemented by a class that provides
+# the instance methods +severity_logged?(severity : Object) : boolean+ and
+# +log(severity : Object, t : Time, prefix : String|Array, msg : String)+
+class ColouredConsoleLogService
+
+	module Constants
+
+		include ::Pantheios::Services::Common::Console::AnsiEscapeSequences
+	end # module Constants
+
+	def self.requires_prefix?
+
+		return @requires_prefix unless @requires_prefix.nil?
+
+		@requires_prefix = ::Pantheios::Services::Common::Console::Internal_::SHOULD_COLOURIZE_ ? :parts : false
+	end
+
+	def requires_prefix?
+
+		self.class.requires_prefix?
+	end
+
+	def severity_logged? severity
+
+		true
+	end
+
+	def log sev, t, pref, msg
+
+		stm = infer_stream sev
+
+		if requires_prefix?
+
+			pref = pref.map do |part|
+
+				bg	=	Constants::Background
+				fg	=	Constants::Foreground
+
+				if part.respond_to?(:severity)
+
+					part = fg.bold part
+
+					case sev
+					when :violation
+
+						part = bg.red part
+						#part = fg.bright_magenta part
+						part = fg.bright_yellow part
+						part = fg.blinking part
+					when :alert
+
+						part = bg.red part
+						part = fg.bright_cyan part
+						part = fg.blinking part
+					when :critical
+
+						part = bg.red part
+						part = fg.white part
+					when :failure
+
+						part = bg.yellow part
+						part = fg.red part
+					when :warning
+
+						part = bg.yellow part
+						part = fg.blue part
+					when :notice
+
+						part = bg.dark_grey part
+						part = fg.white part
+					when :informational
+
+						part = bg.dark_grey part
+						part = fg.light_grey part
+					when :debug0
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :debug1
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :debug2
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :debug3
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :debug4
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :debug5
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :trace
+
+						part = bg.blue part
+						part = fg.light_grey part
+					when :benchmark
+
+						part = bg.black part
+						part = fg.light_grey part
+					else
+
+						;
+					end
+				else
+
+					part = fg.dark_grey part
+				end
+
+				part
+			end.join(', ')
+
+			pref = '[' + pref + ']: '
+
+			#pref = pref.map { |pp| pp.severity? ? map_sev_(sev) : sev }.join(
+		end
+
+		stm.puts "#{pref}#{msg}"
+	end
+
+	# Overrideable method that determines which stream to write, based on a
+	# severity. This implementation always returns +$stderr+
+	#
+	# Overrides must return an object that supports the +puts(String)+
+	# method
+	def infer_stream sev
+
+		$stderr
+	end
+
+	private
+end # class ColouredConsoleLogService
+
+end # module Services
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/services/common/console.rb

@@ -0,0 +1,92 @@
+
+module Pantheios
+module Services
+module Common
+
+module Console
+
+	module Internal_
+
+		STDERR_ISATTY_		=	$stderr.isatty
+		OS_IS_UNIX_			=	%w{
+
+			darwin
+			freebsd
+			linux
+			mingw32
+			solaris
+			sunos
+		}.any? { |os| RUBY_PLATFORM =~ /#{os.downcase}/ }
+		SHOULD_COLOURIZE_	=	STDERR_ISATTY_ && OS_IS_UNIX_
+
+		module ColourInitialiser
+
+			def self.extended other
+
+				other::COLOURS.each do |name, value|
+
+					other.const_set(name.to_s.upcase, value)
+
+					if SHOULD_COLOURIZE_
+
+						other.define_singleton_method(name) { |s| "\x1B[#{value}m#{s}\x1B[0m" }
+					else
+
+						other.define_singleton_method(name) { |s| s }
+					end
+				end
+			end
+		end # module ColourInitialiser
+	end # module Internal_
+
+	module AnsiEscapeSequences
+
+		module Foreground
+
+			COLOURS	=	{
+
+				blinking: 5,
+				bold: 1,
+				default: 39,
+
+				black: 30,
+				red: 31,
+				green: 32,
+				yellow: 33,
+				blue: 34,
+				magenta: 35,
+				cyan: 36,
+				light_grey: 37,
+
+				dark_grey: 90,
+				bright_red: 91,
+				bright_green: 92,
+				bright_yellow: 93,
+				bright_blue: 94,
+				bright_magenta: 95,
+				bright_cyan: 96,
+				white: 97,
+			}
+
+			extend Internal_::ColourInitialiser
+		end # module Foreground
+
+		module Background
+
+			COLOURS = Hash[Foreground::COLOURS.reject { |k, v| [ :blinking, :bold, :default ].include? k }.map { |k, v| [ k, 10 + v ] }]
+
+			extend Internal_::ColourInitialiser
+		end # module Background
+
+		module Special
+
+			# TODO
+
+		end # module Special
+	end # end AnsiEscapeSequences
+
+end # module Console
+end # module Common
+end # module Services
+end # module Pantheios
+