pantheios-ruby 0.18.2 → 0.22.0

data/examples/simple_logging.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# requires (0)
+
+require 'pantheios/globals'
+require 'pantheios/services/simple_console_log_service'
+
+# globals
+
+Pantheios::Globals.INITIAL_SERVICE_CLASSES = [ Pantheios::Services::SimpleConsoleLogService ]
+Pantheios::Globals.MAIN_THREAD_NAME = [ Thread.current, 'main' ]
+Pantheios::Globals.PROCESS_NAME = :script_stem
+
+# requires (1)
+
+require 'pantheios'
+
+# includes
+
+include ::Pantheios
+
+# constants
+
+LEVELS = %i{ violation alert critical failure warning notice informational debug0 debug1 debug2 debug3 debug4 debug5 benchmark }
+
+# main
+
+LEVELS.each do |level|
+
+	log(level, "logging level #{level}")
+end
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/api.rb

@@ -5,13 +5,13 @@
 # Purpose:      The Pantheios.Ruby API (::Pantheios::API)
 #
 # Created:      2nd April 2011
-# Updated:      22nd January 2018
+# Updated:      4th June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2011-2018, Matthew Wilson and Synesis Software
+# Copyright (c) 2011-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -47,7 +47,6 @@
 =begin
 =end
 
-
 require 'pantheios/application_layer/param_name_list'
 require 'pantheios/application_layer/stock_severity_levels'
 require 'pantheios/util/version_util'
@@ -74,6 +73,8 @@ module Pantheios
 # - severity_string severity
 # - thread_id
 # - timestamp t
+# - prefix_parts
+# - prefix
 module API
 
 	# Logs an arbitrary set of parameters at the given severity level
@@ -217,7 +218,13 @@ module API
 		::Pantheios::Core.timestamp t, nil
 	end
 
-	def prefix t, severity
+	# Assembles the prefix according to +prefix_elements+ into an array of
+	# parts
+	#
+	# * *Parameters:*
+	#   - +t+ [ Date, Time, DateTime ] The timestamp of the log entry
+	#   - +severity+ The severity
+	def prefix_parts t, severity
 
 		prefix_elements.map do |el|
 
@@ -245,9 +252,18 @@ module API
 
 				nil
 			end
-		end.join(', ') # TODO: need to do more intelligent joining
+		end
 	end
 
+	# Assembles the +prefix_parts+ into a string
+	#
+	# * *Parameters:*
+	#   - +t+ [ Date, Time, DateTime ] The timestamp of the log entry
+	#   - +severity+ The severity
+	def prefix t, severity
+
+		prefix_parts(t, severity).join(', ')
+	end
 
 	def self.included receiver
 

data/lib/pantheios/application_layer/stock_severity_levels.rb

@@ -7,12 +7,13 @@
 #               namespace module
 #
 # Created:      2nd April 2011
-# Updated:      6th January 2018
+# 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) 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 => [ 13, 'Trace' ],
-			:benchmark => [ 14, '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
@@ -94,12 +96,12 @@ module StockSeverityLevels
 
 			r = {}
 
-			m.each do |s, ar|
+			m.each do |sev, ar|
 
-				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Symbol === sev
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				([sev] + (ar[3] || [])).each do |al|
 
 					r[al] = ar[0]
 				end
@@ -107,18 +109,68 @@ module StockSeverityLevels
 
 			r
 		end
+
 		def self.create_level_string_map m
 
 			r = {}
 
-			m.each do |s, ar|
+			m.each do |sev, ar|
+
+				warn 'invalid start-up' unless ::Symbol === sev
+				warn 'invalid start-up' unless ::Array === ar
+
+				([sev] + (ar[3] || [])).each do |al|
+
+					s = ar[1]
+
+					s.define_singleton_method(:severity) { sev }
+
+					r[al] = s
+				end
+			end
+
+			r
+		end
+
+		def self.create_level_aliases m
+
+			r = {}
+
+			m.each do |sev, ar|
+
+				warn 'invalid start-up' unless ::Symbol === sev
+				warn 'invalid start-up' unless ::Array === ar
+
+				([sev] + (ar[3] || [])).each do |al|
+
+					r[al] = sev
+				end
+			end
+
+			r
+		end
+
+		def self.create_level_relative_map m
+
+			r = {}
+
+			m.each do |sev, ar|
 
-				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Symbol === sev
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				relativity = ar[2]
+
+				case relativity
+				when :relative
 
-					r[al] = ar[1]
+					([sev] + (ar[3] || [])).each do |al|
+
+						r[al] = relativity
+					end
+				else
+
+					;
 				end
 			end
 
@@ -127,17 +179,26 @@ module StockSeverityLevels
 	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/core.rb

@@ -5,12 +5,13 @@
 # Purpose:      The Pantheios.Ruby core (::Pantheios::Core)
 #
 # Created:      2nd April 2011
-# Updated:      5th February 2018
+# 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) 2011-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -122,7 +123,7 @@ module Core
 				raise ::TypeError, "back-end instance (#{fe.class}) does not respond to all the required messages ([ #{Constants_::REQUIRED_BACKEND_METHODS.join(', ')} ])" unless be && Constants_::REQUIRED_BACKEND_METHODS.all? { |m| be.respond_to? m }
 
 				r	=	nil
-				srp	=	svc.respond_to?(:requires_prefix?) ? svc.requires_prefix? : true
+				srp	=	be.respond_to?(:requires_prefix?) ? be.requires_prefix? : true
 
 				@mx_service.synchronize do
 
@@ -196,7 +197,7 @@ module Core
 			attr_reader	:front_end
 			attr_reader	:back_end
 			def requires_prefix?; @requires_prefix; end
-		end
+		end # class State
 	end # module Internals_
 
 	def self.included receiver
@@ -506,7 +507,7 @@ module Core
 
 		if block_given?
 
-			br = get_block_value_ &block
+			br = get_block_value_(&block)
 
 			if ApplicationLayer::ParamNameList === br
 
@@ -527,20 +528,21 @@ module Core
 			end
 		end
 
+		fl	=	nil
+		rx	=	nil
+		fn	=	caller(call_depth + 1, 1)[0]
+
 		case param_list
 		when nil
 			;
 		when ApplicationLayer::ParamNameList
-			;
+
+			warn "#{fn}: param_list must contain only strings or symbols" unless param_list.all? { |p| p.kind_of?(::String) || p.kind_of?(::Symbol) }
 		else
 
-			warn "param_list (#{param_list.class}) must be nil or an instance of #{ApplicationLayer::ParamNameList}" unless param_list
+			warn "#{fn}: param_list (#{param_list.class}) must be nil or an instance of #{ApplicationLayer::ParamNameList}" unless param_list
 		end
 
-		fl	=	nil
-		rx	=	nil
-		fn	=	caller(call_depth + 1, 1)[0]
-
 		if ::Class === prefix_provider
 
 			rx	=	"#{prefix_provider}::"
@@ -594,7 +596,24 @@ module Core
 
 		now	=	Time.now
 
-		prf	=	@@state.requires_prefix? ? '[' + prefix_provider.prefix(now, severity) + ']: ' : nil
+		srp	=	@@state.requires_prefix?
+
+		case srp
+		when false
+
+			prf = nil
+		when true
+
+			prf = '[' + prefix_provider.prefix(now, severity) + ']: '
+		when :parts
+
+			prf = prefix_provider.prefix_parts(now, severity)
+		else
+
+			warn "invalid value '#{srp}' returned by #requires_prefix? of the Pantheios Core's state's service (which is of type #{@@state.service.class}"
+
+			prf = nil
+		end
 
 		@@state.back_end.log severity, now, prf, message
 	end

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