pantheios-ruby 0.19.2 → 0.22.0.1

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.rb

@@ -6,7 +6,7 @@
 # +Pantheios::API+, +Pantheios::ApplicationLayer+, and +Pantheios::Util+ (as
 # well as certain sub modules of +Pantheios::Util+; see +Pantheios::Util+
 # for details), unless the global symbol
-# +::Pantheios::Globals.HAS_CASCADED_INCLUDES+ is truey
+# +::Pantheios::Globals.HAS_CASCADED_INCLUDES+ is falsey
 module Pantheios
 end # module Pantheios
 
@@ -19,7 +19,8 @@ require 'pantheios/version'
 
 module Pantheios
 
-	def self.included receiver
+	# @!visibility private
+	def self.included receiver # :nodoc:
 
 		if ::Pantheios::Globals.HAS_CASCADED_INCLUDES
 

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,11 +252,21 @@ 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
+	# @!visibility private
+	def self.included receiver # :nodoc:
 
 		receiver.extend self
 

data/lib/pantheios/application_layer.rb

@@ -7,7 +7,8 @@ require 'pantheios/core'
 module Pantheios
 module ApplicationLayer
 
-	def self.included receiver
+	# @!visibility private
+	def self.included receiver # :nodoc:
 
 		receiver.extend self
 

data/lib/pantheios/application_layer/param_name_list.rb

@@ -2,9 +2,18 @@
 module Pantheios
 module ApplicationLayer
 
+# Type-distinct +::Array+ for use with tracing, as in
+#
+#    def my_func arg1, arg2, **options
+#
+#        trace ParamNames [ :arg1, :arg2, :options ], arg1, arg2, options
+#
+#    end
+#
 class ParamNameList < Array
 end
 
+# Another name for +ParamNameList+
 ParamNames = ParamNameList
 
 end # module ApplicationLayer

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.
 #
@@ -55,33 +56,37 @@ module ApplicationLayer
 module StockSeverityLevels
 
 	private
-	module Internal_
+	# @!visibility private
+	module Internal_ # :nodoc: all
 
+		# @!visibility private
 		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
+		# @!visibility private
+		def self.create_level_keys m # :nodoc:
 
 			r = m.keys
 
 			m.each do |k, ar|
 
-				(ar[2] || []).each do |al|
+				(ar[3] || []).each do |al|
 
 					r << al
 				end
@@ -90,16 +95,17 @@ module StockSeverityLevels
 			r.uniq
 		end
 
-		def self.create_level_value_map m
+		# @!visibility private
+		def self.create_level_value_map m # :nodoc:
 
 			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 +113,71 @@ module StockSeverityLevels
 
 			r
 		end
-		def self.create_level_string_map m
+
+		# @!visibility private
+		def self.create_level_string_map m # :nodoc:
+
+			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|
+
+					s = ar[1]
+
+					s.define_singleton_method(:severity) { sev }
+
+					r[al] = s
+				end
+			end
+
+			r
+		end
+
+		# @!visibility private
+		def self.create_level_aliases m # :nodoc:
+
+			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
+
+		# @!visibility private
+		def self.create_level_relative_map m # :nodoc:
 
 			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|
+				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 +186,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.
 #
@@ -60,7 +61,8 @@ require 'pantheios/util/thread_util'
 module Pantheios
 module Core
 
-	module Constants_
+	# @!visibility private
+	module Constants_ # :nodoc: all
 
 		REQUIRED_SERVICE_METHODS	=	%w{ severity_logged? log }.map { |name| name.to_sym }
 		REQUIRED_FRONTEND_METHODS	=	%w{ severity_logged?     }.map { |name| name.to_sym }
@@ -68,9 +70,11 @@ module Core
 
 	end # module Constants_
 
-	module Internals_
+	# @!visibility private
+	module Internals_ # :nodoc: all
 
-		class DefaultDiscriminator
+		# @!visibility private
+		class DefaultDiscriminator # :nodoc:
 
 			def severity_logged? severity
 
@@ -87,8 +91,8 @@ module Core
 			end
 		end
 
-		# :nodoc:
-		class State
+		# @!visibility private
+		class State # :nodoc:
 
 			def initialize default_fe, **options
 
@@ -122,7 +126,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,16 +200,17 @@ 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
+	# @!visibility private
+	def self.included receiver # :nodoc:
 
 		abort "Attempt to include #{self} into #{receiver}. This is not allowed"
 	end
 
-	# :nodoc:
-	def self.core_init
+	# @!visibility private
+	def self.core_init # :nodoc:
 
 		# process-name
 
@@ -276,8 +281,8 @@ module Core
 		self.set_default_service
 	end
 
-	# :nodoc:
-	def self.set_default_service **options
+	# @!visibility private
+	def self.set_default_service **options # :nodoc:
 
 		# determine which log service to initialise as the default
 
@@ -462,7 +467,9 @@ module Core
 
 
 	# Internal implementation method, not to be called by application code
-	def self.get_block_value_ &block
+	#
+	# @!visibility private
+	def self.get_block_value_ &block # :nodoc:
 
 		case block.arity
 		when 0
@@ -486,7 +493,9 @@ module Core
 	end
 
 	# Internal implementation method, not to be called by application code
-	def self.log_v_impl prefix_provider, severity, argv, &block
+	#
+	# @!visibility private
+	def self.log_v_impl prefix_provider, severity, argv, &block # :nodoc:
 
 		argv << get_block_value_(&block) if block_given?
 
@@ -494,7 +503,9 @@ module Core
 	end
 
 	# Internal implementation method, not to be called by application code
-	def self.trace_v_impl prefix_provider, call_depth, param_list, severity, argv, &block
+	#
+	# @!visibility private
+	def self.trace_v_impl prefix_provider, call_depth, param_list, severity, argv, &block # :nodoc:
 
 		unless param_list
 
@@ -506,7 +517,7 @@ module Core
 
 		if block_given?
 
-			br = get_block_value_ &block
+			br = get_block_value_(&block)
 
 			if ApplicationLayer::ParamNameList === br
 
@@ -527,20 +538,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}::"
@@ -590,11 +602,30 @@ module Core
 	end
 
 	# Internal implementation method, not to be called by application code
-	def self.log_raw prefix_provider, severity, message
+	#
+	# @!visibility private
+	def self.log_raw prefix_provider, severity, message # :nodoc:
 
 		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