pantheios-ruby 0.13.4 → 0.20.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 42dd156fe607cf0712c3f8bf87a4b18d00b5876f
-  data.tar.gz: 2fb2a26c90fb74f89b0d6ddf37e95ae26a1786f8
+  metadata.gz: 5f5bcc837f0b87b903fe88c0b5d1eb3f2c8193a3
+  data.tar.gz: 6e4acd4a1a86ae3df1f04d5ab506c1f0b0722666
 SHA512:
-  metadata.gz: 3143dabf9f559f38711bc3f90cc849fa3b91e21f08373cfaf63d769e6f704d27197cf9d22f5d3b1108e83db388987c815b59cbca1de5642e9f987a3b61da2005
-  data.tar.gz: c203a65311dca3d02517ed8e1ba34b3cf2137a19d8514788a6dcb216700a2a56b07bca0f972a9981cafffb39232082b52c5cc2721e7427191697b8f077626e67
+  metadata.gz: 5d7eff164a890518c3fabca3612d6f5810a554235831838e6a98c47562061924d37e09300e610de1cef8759c9c6ee582b695020b0fd6297c69e82802c9f814d2
+  data.tar.gz: 873c24a5b54e6711d498e06e0c20c335a81fc2f737c0fa1da634c8b5faa2767c6da49743611481ef6c9a446f39953255a500b3bb526854a2e02e1ef997fc285d

data/LICENSE

@@ -0,0 +1,31 @@
+Pantheios.Ruby
+
+Copyright (c) 2017-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 Pantheios or Pantheios.Ruby nor 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.
+

data/README.md

@@ -0,0 +1,5 @@
+# **Pantheios.Ruby**
+Pantheios, for Ruby
+
+T.B.C.
+

data/examples/simple_logging.md

@@ -0,0 +1,65 @@
+# Pantheios.Ruby Example - **simple_logging**
+
+## Summary
+
+Simple example supporting ```--help``` and ```--version```.
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# requires (0)
+
+require 'pantheios/globals'
+
+# globals
+
+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 }
+
+# main
+
+LEVELS.each do |level|
+
+	log(level, "logging level #{level}")
+end
+
+# ############################## end of file ############################# #
+```
+
+## Usage
+
+### No arguments
+
+When executed gives the following output:
+
+```
+[simple_logging, main, 2019-06-05 13:18:52.517479, Violation]: logging level violation
+[simple_logging, main, 2019-06-05 13:18:52.517615, Alert]: logging level alert
+[simple_logging, main, 2019-06-05 13:18:52.517653, Critical]: logging level critical
+[simple_logging, main, 2019-06-05 13:18:52.517681, Failure]: logging level failure
+[simple_logging, main, 2019-06-05 13:18:52.517709, Warning]: logging level warning
+[simple_logging, main, 2019-06-05 13:18:52.517735, Notice]: logging level notice
+[simple_logging, main, 2019-06-05 13:18:52.517763, Informational]: logging level informational
+[simple_logging, main, 2019-06-05 13:18:52.517789, Debug-0]: logging level debug0
+[simple_logging, main, 2019-06-05 13:18:52.517837, Debug-1]: logging level debug1
+[simple_logging, main, 2019-06-05 13:18:52.517876, Debug-2]: logging level debug2
+[simple_logging, main, 2019-06-05 13:18:52.517905, Debug-3]: logging level debug3
+[simple_logging, main, 2019-06-05 13:18:52.517931, Debug-4]: logging level debug4
+```
+

data/examples/simple_logging.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# requires (0)
+
+require 'pantheios/globals'
+
+# globals
+
+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 }
+
+# main
+
+LEVELS.each do |level|
+
+	log(level, "logging level #{level}")
+end
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/api.rb

@@ -70,7 +70,7 @@ module Pantheios
 #
 # - prefix_elements
 # - process_id
-# - program_name
+# - process_name
 # - severity_string severity
 # - thread_id
 # - timestamp t
@@ -160,7 +160,7 @@ module API
 	# === Elements
 	#
 	# Elements can be one of:
-	#   - +:program_name+
+	#   - +:process_name+
 	#   - +:process_id+
 	#   - +:severity+
 	#   - +:thread_id+
@@ -169,7 +169,7 @@ module API
 	# This is called from +prefix+
 	def prefix_elements
 
-		[ :program_name, :thread_id, :timestamp, :severity ]
+		[ :process_name, :thread_id, :timestamp, :severity ]
 	end
 
 	# Obtains the process id
@@ -184,10 +184,10 @@ module API
 	# Obtains the program name
 	#
 	# Unless overridden, returns the value provided by
-	# +::Pantheios::Core::program_name+
-	def program_name
+	# +::Pantheios::Core::process_name+
+	def process_name
 
-		::Pantheios::Core.program_name
+		::Pantheios::Core.process_name
 	end
 
 	# Obtains the string corresponding to the severity
@@ -222,9 +222,9 @@ module API
 		prefix_elements.map do |el|
 
 			case el
-			when :program_name
+			when :program_name, :process_name
 
-				program_name
+				process_name
 			when :process_id
 
 				process_id

data/lib/pantheios/application_layer/stock_severity_levels.rb

@@ -7,7 +7,7 @@
 #               namespace module
 #
 # Created:      2nd April 2011
-# Updated:      6th January 2018
+# Updated:      12th March 2018
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
@@ -71,8 +71,8 @@ module StockSeverityLevels
 			:debug2 => [ 10, 'Debug-2' ],
 			:debug3 => [ 11, 'Debug-3' ],
 			:debug4 => [ 12, 'Debug-4' ],
-			:trace => [ 13, 'Trace' ],
-			:benchmark => [ 14, 'Benchmark' ],
+			:trace => [ 15, 'Trace' ],
+			:benchmark => [ 16, 'Benchmark' ],
 		}
 
 		def self.create_level_keys m

data/lib/pantheios/core.rb

@@ -5,7 +5,7 @@
 # Purpose:      The Pantheios.Ruby core (::Pantheios::Core)
 #
 # Created:      2nd April 2011
-# Updated:      23rd January 2018
+# Updated:      5th September 2018
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
@@ -51,6 +51,8 @@ require 'pantheios/application_layer/stock_severity_levels'
 require 'pantheios/services/simple_console_log_service'
 
 require 'pantheios/util/process_util'
+require 'pantheios/util/reflection_util'
+require 'pantheios/util/thread_util'
 
 =begin
 =end
@@ -132,8 +134,14 @@ module Core
 
 			def set_service svc
 
+				raise ::ArgumentError, 'service instance may not be nil' if svc.nil?
+
 				raise ::TypeError, "service instance (#{svc.class}) does not respond to all the required messages ([ #{Constants_::REQUIRED_SERVICE_METHODS.join(', ')} ])" unless Constants_::REQUIRED_SERVICE_METHODS.all? { |m| svc.respond_to? m }
 
+				nrcs	=	::Pantheios::Util::ReflectionUtil.non_root_classes svc
+
+				raise ::TypeError, "service instance class - #{svc.class} - inherits some of the required messages - [ #{Constants_::REQUIRED_SERVICE_METHODS.join(', ')} ] - from the top-level" unless Constants_::REQUIRED_SERVICE_METHODS.all? { |m| nrcs.any? { |nr| nr.instance_methods(false).include? m } }
+
 				r	=	[]
 				srp	=	svc.respond_to?(:requires_prefix?) ? svc.requires_prefix? : true
 
@@ -199,6 +207,70 @@ module Core
 	# :nodoc:
 	def self.core_init
 
+		# process-name
+
+		prg_nam	=	nil
+
+		case Pantheios::Globals.PROCESS_NAME
+		when nil
+
+			;
+		when ::Symbol
+
+			prg_nam	=	::Pantheios::Util::ProcessUtil.derive_process_name $0, style: Pantheios::Globals.PROCESS_NAME
+		when ::String
+
+			prg_nam	=	Pantheios::Globals.PROCESS_NAME.strip
+			prg_nam	=	nil if prg_name.empty?
+		else
+
+			warn "ignoring unsupported Globals.PROCESS_NAME type - '#{Pantheios::Globals.PROCESS_NAME.class}'"
+		end
+
+		@process_name = prg_nam if prg_nam
+
+
+		# main thread-name
+		#
+		# This is obtained from Pantheios::Globals.MAIN_THREAD_NAME, which
+		# may be either ::String or [ ::String, ::Thread ]
+
+		mt_th	=	nil
+		mt_nam	=	nil
+
+		case pg_mtn = ::Pantheios::Globals.MAIN_THREAD_NAME
+		when nil
+
+			;
+		when ::Array
+
+			if pg_mtn.size != 2
+
+				warn "ignoring array of wrong length - #{pg_mtn.size} given; 2-required - for Globals.MAIN_THREAD_TYPE"
+			else
+
+				mt_th	=	pg_mtn[0]
+				mt_nam	=	pg_mtn[1]
+
+				if ::Thread === mt_nam
+
+					mt_th, mt_nam = mt_nam, mt_th
+				end
+			end
+		when ::String
+
+			mt_th	=	Thread.current
+			mt_nam	=	pg_mtn
+		else
+
+			warn "ignoring unsupported Globals.MAIN_THREAD_NAME type - '#{Pantheios::Globals.MAIN_THREAD_NAME.class}'"
+		end
+
+		::Pantheios::Util::ThreadUtil.set_thread_name mt_th, mt_nam if mt_nam
+
+
+		# state (incl. default service)
+
 		@@state = Internals_::State.new Internals_::DefaultDiscriminator.new
 
 		self.set_default_service
@@ -209,14 +281,14 @@ module Core
 
 		# determine which log service to initialise as the default
 
-		(::Pantheios::Globals.INITIAL_SERVICE_INSTANCES || []).each do |inst|
+		([::Pantheios::Globals.INITIAL_SERVICE_INSTANCES].flatten || []).reject(&:nil?).each do |inst|
 
 			next unless inst
 
 			return @@state.set_service inst
 		end
 
-		(::Pantheios::Globals.INITIAL_SERVICE_CLASSES || []).each do |cls|
+		([::Pantheios::Globals.INITIAL_SERVICE_CLASSES].flatten || []).reject(&:nil?).each do |cls|
 
 			inst = cls.new
 
@@ -307,18 +379,43 @@ module Core
 		Process.pid
 	end
 
-	# Default implementation to obtain the program name
+	# Default implementation to obtain the process name
 	#
 	# * *Returns:*
 	#   The file stem of +$0+
 	#
-	# NOTE: this is implemented in terms of Process_Util.derive_process_name
-	# and the result is cached
-	def self.program_name
+	# NOTE: this is implemented in terms of
+	# +Process_Util.derive_process_name+ and the result is cached
+	def self.process_name
 
-		@program_name ||= ::Pantheios::Util::ProcessUtil.derive_process_name $0
+		@process_name ||= ::Pantheios::Util::ProcessUtil.derive_process_name $0
 	end
 
+	# [DEPRECATED] Use +process_name+
+	def self.program_name; self.process_name; end
+
+	# Sets the process name
+	#
+	# * *Parameters:*
+	#   - +name+:: [String] The (new) process name. May be +nil+, in which
+	#   case +process_name+ will obtain the process name from
+	#   +Process_Util.derive_process_name+
+	#
+	# * *Returns:*
+	#   The previous version
+	#
+	# NOTE: to reset the value, set to +nil+
+	def self.process_name= name
+
+		previous, @process_name = @process_name, name
+
+		previous
+	end
+
+	# [DEPRECATED] Use +process_name=+
+	def self.program_name= name; self.process_name = name; end
+
+	# Obtains a string form of the given severity
 	def self.severity_string severity
 
 		r = ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_STRINGS[severity] and return r
@@ -409,7 +506,7 @@ module Core
 
 		if block_given?
 
-			br = get_block_value_ &block
+			br = get_block_value_(&block)
 
 			if ApplicationLayer::ParamNameList === br
 
@@ -430,20 +527,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}::"

data/lib/pantheios/globals.rb

@@ -5,7 +5,7 @@
 # Purpose:      The Pantheios.Ruby "globals" (::Pantheios::Globals)
 #
 # Created:      24th December 2017
-# Updated:      22nd January 2018
+# Updated:      4th February 2018
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
@@ -57,11 +57,24 @@ module Pantheios
 #
 # === Variables
 #
+# * *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
+#
+#   NOTE: This feature is subject to the initialising threads: if the string
+#   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
+#   name. See +Pantheios::Util::ProcessUtil::derive_process_name+
+#
 # * *SYNCHRONISED_SEVERITY_LOGGED* [boolean] Determines whether the core
 #   protects the call to the underlying log-service's +severity_logged?+
 #   with a mutex (which has a non-trivial cost).
@@ -70,8 +83,10 @@ module Globals
 
 	module Internals_
 
-		BOOLEAN_CLASSES	=	[ ::FalseClass, ::TrueClass ]
-		TRUTHY_CLASSES	=	BOOLEAN_CLASSES + [ ::NilClass ]
+		BOOLEAN_CLASSES			=	[ ::FalseClass, ::TrueClass ]
+		TRUTHY_CLASSES			=	BOOLEAN_CLASSES + [ ::NilClass ]
+
+		PROCESS_NAME_CLASSES	=	[ ::Symbol, ::String ]
 	end
 
 	module Helpers_
@@ -117,6 +132,10 @@ module Globals
 
 	Helpers_.cattr self, 'INITIAL_SERVICE_CLASSES', nil, nil
 
+	Helpers_.cattr self, 'MAIN_THREAD_NAME', [ ::Array, ::String ], nil
+
+	Helpers_.cattr self, 'PROCESS_NAME', Internals_::PROCESS_NAME_CLASSES, nil
+
 	Helpers_.cattr self, 'SYNCHRONISED_SEVERITY_LOGGED', nil, true, boolean: true
 
 	def self.included receiver