pantheios-ruby 0.13.4 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 42dd156fe607cf0712c3f8bf87a4b18d00b5876f
-  data.tar.gz: 2fb2a26c90fb74f89b0d6ddf37e95ae26a1786f8
+  metadata.gz: 851dd68a076bd0aec6f50aac903ec3481e11b5b5
+  data.tar.gz: f9fd44e79e3beb975796a0e165ec862bff647a75
 SHA512:
-  metadata.gz: 3143dabf9f559f38711bc3f90cc849fa3b91e21f08373cfaf63d769e6f704d27197cf9d22f5d3b1108e83db388987c815b59cbca1de5642e9f987a3b61da2005
-  data.tar.gz: c203a65311dca3d02517ed8e1ba34b3cf2137a19d8514788a6dcb216700a2a56b07bca0f972a9981cafffb39232082b52c5cc2721e7427191697b8f077626e67
+  metadata.gz: 266c00061542c2f1f6a45337ee76d340cadcf9b3d5e81d452400b70c9ca06f2020b62827de054811401a5cf0aa573f37046f668b1cf1ba26deb958a9188a4243
+  data.tar.gz: 9d87377399759d09b0b636100761737eef9291e1d1e8a8699b9f68c59ed19b8343bb32d02d94eb4b879d2f50c85cff9da102a5d30dfe286268a2ac34e4e76a9e

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

@@ -5,7 +5,7 @@
 # Purpose:      The Pantheios.Ruby core (::Pantheios::Core)
 #
 # Created:      2nd April 2011
-# Updated:      23rd January 2018
+# Updated:      5th February 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
+
+		@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
 
-		@program_name ||= ::Pantheios::Util::ProcessUtil.derive_process_name $0
+		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

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

data/lib/pantheios/services/simple_file_log_service.rb

@@ -0,0 +1,230 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/services/simple_file_log_service.rb
+#
+# Purpose:      Definition of the
+#               ::Pantheios::Services::SimpleFileLogService class
+#
+# Created:      17th June 2015
+# Updated:      4th February 2018
+#
+# Home:         http://github.com/synesissoftware/Pantheios-Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2015-2018, 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/application_layer/stock_severity_levels'
+
+require 'logger'
+
+=begin
+=end
+
+module Pantheios
+module Services
+
+# A class that fulfils the Pantheios *LogService* protocol that allows all
+# severities and logs to a file
+#
+# 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, msg : String)+
+class SimpleFileLogService
+
+	module SimpleFileLogService_Constants
+
+		DEFAULT_ROLL_DEPTH		=	7
+		DEFAULT_ROLL_SIZE		=	1024 * 1024
+
+		RECOGNISED_OPTIONS		=	%w{ roll_depth roll_period roll_size }.map { |s| s.to_sym }
+
+	end # module SimpleFileLogService_Constants
+
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +log_file_or_path+:: [ +::File+, +::IO+, +::String+ ] A file or an
+	#     IO that will be used as the target of the log statements, or a
+	#     string specifying the path of the file to be used as the target
+	#   - +options+:: [ ::Hash ] Options. Options other than those listed
+	#     are ignored silently (except if +$DEBUG+, in which case a
+	#     +warn+ing will be issued)
+	#
+	# * *Options:*
+	#   - +:roll_period+:: ( +:daily+, +:weekly+, +:monthly+ ) The
+	#     periodicity of the log-file rolling. Ignored unless
+	#     +log_file_or_path+ is a +::String+. Ignored if either +:roll_size+
+	#     or +:roll_depth+ is specified
+	#   - +:roll_size+:: [ ::Integer, [ ::Integer, ::Integer ] ] An integer
+	#     specifying the size of the log file, or an array containing the
+	#     size of the log file and the depth of the log roll
+	#   - +:roll_depth+:: [ ::Integer ] The depth of the size-based log
+	#     rolling. Overrides the second element in an array specified for
+	#     +:roll_size+ 
+
+
+	def initialize log_file_or_path, **options
+
+		roll_period	=	options[:roll_period]
+		roll_size	=	options[:roll_size]
+		roll_depth	=	options[:roll_depth]
+
+		if $DEBUG
+
+			options.each do |k, v|
+
+				warn "#{self.class}##{__method__}(): ignoring unrecognised option '#{k}'" unless SimpleFileLogService_Constants::RECOGNISED_OPTIONS.include?(:k)
+			end
+		end
+
+		if roll_period && (roll_size || roll_depth)
+
+			warn "#{self.class}##{__method__}(): caller specified :roll_depth/:roll_period with :roll_size to #{self.class}##{__method__}() - ignoring :roll_period" if $DEBUG
+
+			roll_period = nil
+		end
+
+		if roll_size || roll_depth
+
+			if ::Array === roll_size
+
+				roll_size, d	=	roll_size
+
+				roll_depth		||=	d
+			end
+
+			roll_size	||=	SimpleFileLogService_Constants::DEFAULT_ROLL_SIZE
+			roll_depth	||=	SimpleFileLogService_Constants::DEFAULT_ROLL_DEPTH
+		end
+
+		logger_init_args	=	[]
+		logger_init_options	=	{}
+
+		if false;
+		elsif roll_depth
+
+			logger_init_args	<<	roll_depth
+			logger_init_args	<<	roll_size
+		elsif roll_period
+
+			roll_period = roll_period.downcase.to_sym if ::String === roll_period
+
+			case roll_period
+			when :daily, :weekly, :monthly
+
+				;
+			else
+
+				raise ArgumentError, ":roll_period value must be one of :daily, :weekly, :monthly"
+			end
+
+			logger_init_args	<<	roll_period.to_s
+			logger_init_args	<<	0
+		end
+
+		raise ArgumentError, ":roll_depth must be a non-negative integer" unless roll_depth.nil? || (::Integer === roll_depth && roll_depth >= 0)
+		raise ArgumentError, ":roll_size must be a non-negative integer" unless roll_size.nil? || (::Integer === roll_size && roll_size >= 0)
+
+		file_proc = lambda do
+
+			@logger			=	::Logger.new log_file_or_path, *logger_init_args
+			@log_file_path	=	log_file_or_path.path
+		end
+
+		io_proc = lambda do
+
+			@logger			=	::Logger.new log_file_or_path, *logger_init_args
+			@log_file_path	=	log_file_or_path.respond_to?(:path) ? log_file_or_path.path : nil
+		end
+
+		case log_file_or_path
+		when nil
+
+			raise ArgumentError, 'log_file_or_path may not be nil'
+		when ::IO#, ::StringIO
+
+			io_proc.call
+		when ::File#, ::Tempfile
+
+			file_proc.call
+		when ::String
+
+			@logger			=	::Logger.new log_file_or_path, *logger_init_args
+			@log_file_path	=	log_file_or_path
+		else
+
+			ancestor_names	=	log_file_or_path.class.ancestors.map(&:to_s)
+
+			if false
+
+				;
+			elsif ancestor_names.include?('StringIO')
+
+				io_proc.call
+			elsif ancestor_names.include?('Tempfile')
+
+				file_proc.call
+			else
+
+				raise TypeError, "log_file_or_path type must be one of #{::File}, #{::IO}, #{::String}, #{::StringIO}"
+			end
+		end
+
+		self
+	end
+
+	# The path of the underlying log file. May return +nil+ if the path
+	# cannot be determined
+	attr_reader	:log_file_path
+
+	def severity_logged? severity
+
+		true
+	end
+
+	def log sev, t, pref, msg
+
+		@logger << "#{pref}#{msg}\n"
+	end
+end
+
+
+end # module Services
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/util/process_util.rb

@@ -4,13 +4,41 @@ module Util
 
 module ProcessUtil
 
-	def self.derive_process_name dollar0 = nil
+	#
+	# * *Options:*
+	#   - +:style+:: (:script, :script_basename, :script_dirname,
+	#   :script_realpath, :script_stem) directs the inference of the process
+	#   name. If none specified, :script_stem is assumed
+	def self.derive_process_name dollar0 = nil, **options
 
-		dollar0 ||= $0
+		dollar0	||=	$0
 
-		bn = File.basename dollar0
+		style	=	options[:style] || :script_stem
 
-		bn =~ /\.rb$/ ? $` : bn
+		case style
+		when :script
+
+			dollar0
+		when :script_basename
+
+			File.basename(dollar0)
+		when :script_dirname
+
+			File.basename(File.realpath(File.dirname(dollar0)))
+		when :script_realpath
+
+			File.realpath(File.dirname(dollar0))
+		when :script_stem
+
+			bn = File.basename(dollar0)
+
+			bn =~ /\.rb$/ ? $` : bn
+		else
+
+			warn "#{self.class}##{__method__}: ignoring unrecognised type/value for ':style': '#{style}' (#{style.class})"
+
+			dollar0
+		end
 	end
 
 end # module ProcessUtil

data/lib/pantheios/util/reflection_util.rb

@@ -0,0 +1,34 @@
+
+module Pantheios
+module Util
+
+module ReflectionUtil
+
+	module ReflectionUtil_Constants
+
+		ROOT_CLASSES = [ ::Object, ::BasicObject ]
+	end
+
+	def self.non_root_classes o
+
+		return [] if o.nil?
+
+		return self.non_root_classes o.class unless ::Class === o
+
+		return [] if ReflectionUtil_Constants::ROOT_CLASSES.any? { |c| c == o }
+
+		s = o.superclass
+
+		return [ o ] if ::Object == s
+
+		[ o ] + self.non_root_classes(s)
+	end
+
+end # module ProcessUtil
+
+end # module Util
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/version.rb

@@ -5,7 +5,7 @@
 # Purpose:      Version for Pantheios.Ruby library
 #
 # Created:      2nd April 2011
-# Updated:      23rd January 2018
+# Updated:      5th February 2018
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
@@ -50,7 +50,7 @@
 module Pantheios
 
 	# Current version of the Pantheios.Ruby library
-	VERSION				=	'0.13.4'
+	VERSION				=	'0.18.1'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:

data/test/performance/test_perf_simple_statements.rb

@@ -37,7 +37,9 @@ end
 
 Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:') do |r|
 
-	at_0 = r.report("arguments (1-arg)") do
+	totals	=	[]
+
+	totals << r.report("arguments (1-arg)") do
 
 		for i in (0...N) do
 
@@ -45,7 +47,7 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	bt_0 = r.report("blocks (1-arg)") do
+	totals << r.report("blocks (1-arg)") do
 
 		for i in (0...N) do
 
@@ -53,7 +55,16 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	at_1 = r.report("arguments (simple)") do
+	totals << r.report("args-if (1-arg)") do
+
+		for i in (0...N) do
+
+			log :notice, 'the cat in the hat.' if severity_logged? :notice
+		end
+	end
+
+
+	totals << r.report("arguments (simple)") do
 
 		for i in (0...N) do
 
@@ -61,7 +72,7 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	bt_1 = r.report("blocks (simple)") do
+	totals << r.report("blocks (simple)") do
 
 		for i in (0...N) do
 
@@ -69,7 +80,16 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	at_2 = r.report("arguments (complex)") do
+	totals << r.report("args-if (simple)") do
+
+		for i in (0...N) do
+
+			log :notice, 'the ', 'cat ', 'in ', 'the ', 'hat.' if severity_logged? :notice
+		end
+	end
+
+
+	totals << r.report("arguments (complex)") do
 
 		cat	=	'cat'
 		hat	=	:hat
@@ -81,7 +101,7 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	bt_2 = r.report("blocks (complex)") do
+	totals << r.report("blocks (complex)") do
 
 		cat	=	'cat'
 		hat	=	:hat
@@ -93,7 +113,20 @@ Benchmark.benchmark(Benchmark::CAPTION, 24, Benchmark::FORMAT, 'total:', 'avg:')
 		end
 	end
 
-	[ at_0 + at_1 + at_2 + bt_0 + bt_1 + bt_2, (at_0 + at_1 + at_2 + bt_0 + bt_1 + bt_2) / 2 ]
+	totals << r.report("args-if (complex)") do
+
+		cat	=	'cat'
+		hat	=	:hat
+		t	=	Time.now
+
+		for i in (0...N) do
+
+			log :notice, "the #{cat} in the #{hat} (#{t})" if severity_logged? :notice
+		end
+	end
+
+
+	[ totals.inject(:+), totals.inject(:+) / totals.size ]
 end
 
 

data/test/scratch/log_rolling_by_period_daily.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+#############################################################################
+# File:         test/scratch/log_rolling_by_period_daily.rb
+#
+# Purpose:      Tests the log-rolling functionality of SimpleFileLogService
+#
+# Created:      4th February 2018
+# Updated:      4th February 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright:    <<TBD>>
+#
+#############################################################################
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..'] * 2), 'lib')
+
+require 'pantheios/globals'
+require 'pantheios/services/simple_file_log_service'
+
+log_path_base = File.join(File.dirname(__FILE__), 'log_files', 'log_rolling_by_period_daily')
+
+Pantheios::Globals.INITIAL_SERVICE_INSTANCES = Pantheios::Services::SimpleFileLogService.new log_path_base, roll_period: :daily
+
+require 'pantheios'
+
+include Pantheios
+
+log :notice, 'program starting ...'
+
+log(:notice) { 'program started' }
+
+(0..1000).each do |n|
+
+	log :informational, "increment #{n}: '#{'*' * 10 * n}'"
+
+	sleep 100
+end
+
+at_exit { log :notice, 'program ending ...' }
+
+

data/test/scratch/log_rolling_by_size_and_depth.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+#############################################################################
+# File:         test/scratch/log_rolling_by_size_and_depth.rb
+#
+# Purpose:      Tests the log-rolling functionality of SimpleFileLogService
+#
+# Created:      4th February 2018
+# Updated:      4th February 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright:    <<TBD>>
+#
+#############################################################################
+
+$:.unshift File.join(File.dirname(__FILE__), *(['..'] * 2), 'lib')
+
+require 'pantheios/globals'
+require 'pantheios/services/simple_file_log_service'
+
+log_path_base = File.join(File.dirname(__FILE__), 'log_files', 'log_rolling_by_size_and_depth')
+
+Pantheios::Globals.INITIAL_SERVICE_INSTANCES = Pantheios::Services::SimpleFileLogService.new log_path_base, roll_size: [ 1000, 10 ]
+
+require 'pantheios'
+
+include Pantheios
+
+log :notice, 'program starting ...'
+
+log(:notice) { 'program started' }
+
+(0..1000).each do |n|
+
+	log :informational, "increment #{n}: '#{'*' * 10 * n}'"
+
+	sleep 1
+end
+
+at_exit { log :notice, 'program ending ...' }
+
+

data/test/scratch/log_using_blocks.rb

@@ -6,7 +6,7 @@
 # Purpose:      COMPLETE_ME
 #
 # Created:      22nd January 2018
-# Updated:      22nd January 2018
+# Updated:      5th February 2018
 #
 # Author:       Matthew Wilson
 #
@@ -16,6 +16,12 @@
 
 $:.unshift File.join(File.dirname(__FILE__), *(['..'] * 2), 'lib')
 
+require 'pantheios/globals'
+
+Pantheios::Globals.MAIN_THREAD_NAME = [ Thread.current, 'main' ]
+Pantheios::Globals.PROCESS_NAME = :script_stem
+
+
 require 'pantheios'
 
 include Pantheios
@@ -66,3 +72,4 @@ puts
 
 h 'lmnop', :q, :rst
 
+

data/test/unit/core/tc_core_1.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../..', 'lib')
+
+require 'pantheios/core'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+class Test_Core_set_process_name < Test::Unit::TestCase
+
+	Core = ::Pantheios::Core
+
+	def test_derive_process_name_obtains_the_same_results_but_different_instances
+
+		begin
+
+			Core.process_name = nil
+
+			n_1 = Core.process_name
+			n_2 = Core.process_name
+
+			assert_equal n_1, n_2
+			assert_same n_1, n_2
+
+
+			Core.process_name = nil
+
+			n_3 = Core.process_name
+
+			assert_equal n_1, n_3
+			assert_not_same n_1, n_3
+
+		ensure
+
+			Core.process_name = nil
+		end
+	end
+
+	def test_derive_process_name_accepts_custom_value
+
+		begin
+
+			Core.process_name = 'abc'
+
+			assert_equal 'abc', Core.process_name
+		ensure
+
+			Core.process_name = nil
+		end
+	end
+end
+

data/test/unit/core/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_simple_file_log_service.rb

@@ -0,0 +1,252 @@
+#!/usr/bin/env ruby
+#
+# test/unit/services/tc_simple_file_log_service.rb
+
+$:.unshift File.join(File.dirname(__FILE__), '../../..', 'lib')
+
+require 'pantheios/services/simple_file_log_service'
+
+require 'pantheios/application_layer/stock_severity_levels'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+require 'stringio'
+require 'tempfile'
+
+class Test_SimpleFileLogservice < Test::Unit::TestCase
+
+	include ::Pantheios::Services
+
+	def test_SimpleFileLogService_type_exists
+
+		assert defined? SimpleFileLogService
+	end
+
+	if  defined?(SimpleFileLogService)
+
+		def self.log_to_StringIO_and_get_output messages, def_sev, def_pref = nil, def_t = nil, **options
+
+			def_t		||=	Time.now
+			def_pref	||=	"[prog, thread, #{def_t}]: "
+
+			stream		=	StringIO.new
+
+			svc			=	SimpleFileLogService.new stream, **options
+
+			messages.each do |message|
+
+				ar		=	::Array === message ? message : [ message ]
+
+				msg		=	ar[0]
+				sev		=	ar[1] || def_sev
+				pref	=	ar[2] || def_pref
+				t		=	ar[3] || def_t
+
+				svc.log sev, t, pref, msg
+			end
+
+			stream.string
+		end
+
+		def self.log_to_Tempfile_and_get_output messages, def_sev, def_pref = nil, def_t = nil, **options
+
+			def_t		||=	Time.now
+			def_pref	||=	"[prog, thread, #{def_t}]: "
+
+			tf			=	Tempfile.new 'Pantheios.Ruby.Tempfile'
+
+			begin
+
+				svc			=	SimpleFileLogService.new tf, **options
+
+				messages.each do |message|
+
+					ar		=	::Array === message ? message : [ message ]
+
+					msg		=	ar[0]
+					sev		=	ar[1] || def_sev
+					pref	=	ar[2] || def_pref
+					t		=	ar[3] || def_t
+
+					svc.log sev, t, pref, msg
+				end
+
+				tf.rewind
+
+				return tf.read
+			ensure
+
+				tf.close
+				tf.unlink
+			end
+		end
+
+		def self.log_to_Tempfile_path_and_get_output messages, def_sev, def_pref = nil, def_t = nil, **options
+
+			def_t		||=	Time.now
+			def_pref	||=	"[prog, thread, #{def_t}]: "
+
+			tf			=	Tempfile.new 'Pantheios.Ruby.Tempfile'
+
+			begin
+
+				svc			=	SimpleFileLogService.new tf.path, **options
+
+				messages.each do |message|
+
+					ar		=	::Array === message ? message : [ message ]
+
+					msg		=	ar[0]
+					sev		=	ar[1] || def_sev
+					pref	=	ar[2] || def_pref
+					t		=	ar[3] || def_t
+
+					svc.log sev, t, pref, msg
+				end
+
+				tf.rewind
+
+				return tf.read
+			ensure
+
+				tf.close
+				tf.unlink
+			end
+		end
+
+		def test_SimpleFileLogService_type_is_a_class
+
+			assert_kind_of(::Class, SimpleFileLogService)
+		end
+
+		def test_SimpleFileLogService_type_has_expected_instance_methods
+
+			assert_type_has_instance_methods SimpleFileLogService, [ :severity_logged?, :log ]
+		end
+
+		def test_ctor_failures_with_invalid_log_file_or_path
+
+			assert_raise_with_message(::ArgumentError, /log_file_or_path.*not.*nil/) { SimpleFileLogService.new nil }
+
+			assert_raise_with_message(::TypeError, [ /log_file_or_path.*must be/, /::File/, /::IO/, /::String/, /::StringIO/ ]) { SimpleFileLogService.new // }
+		end
+
+		def test_ctor_failures_with_invalid_options
+
+			assert_raise_with_message(::ArgumentError, /:roll_depth.*non.*negative.*integer/) { SimpleFileLogService.new '/dev/null', roll_depth: true }
+			assert_raise_with_message(::ArgumentError, /:roll_depth.*non.*negative.*integer/) { SimpleFileLogService.new '/dev/null', roll_depth: -1 }
+
+			assert_raise_with_message(::ArgumentError, /:roll_size.*non.*negative.*integer/) { SimpleFileLogService.new '/dev/null', roll_size: true }
+			assert_raise_with_message(::ArgumentError, /:roll_size.*non.*negative.*integer/) { SimpleFileLogService.new '/dev/null', roll_size: -1 }
+		end
+
+		def test_severity_logged_false_with_large_range_of_integers
+
+			output	=	StringIO.new
+
+			svc = SimpleFileLogService.new output
+
+			(-10000 .. 10000).each do |sev|
+
+				assert_true(svc.severity_logged?(sev), "severity '#{sev}' (#{sev.class}) was not logged")
+			end
+		end
+
+		def test_simple_logging_with_StringIO_1
+
+			message	=	'msg'
+
+			output	=	self.class.log_to_StringIO_and_get_output [ message ], :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 1, lines.size
+			assert_match /msg$/, lines[0]
+		end
+
+		def test_simple_logging_with_StringIO_2
+
+			msgs	=	[
+
+				[ 'msg-1' ],
+				[ 'msg-2' ],
+			]
+
+			output	=	self.class.log_to_StringIO_and_get_output msgs, :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 2, lines.size
+			assert_match /msg-1$/, lines[0]
+			assert_match /msg-2$/, lines[1]
+		end
+
+		def test_simple_logging_with_Tempfile_1
+
+			message	=	'msg'
+
+			output	=	self.class.log_to_Tempfile_and_get_output [ message ], :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 1, lines.size
+			assert_match /msg$/, lines[0]
+		end
+
+		def test_simple_logging_with_Tempfile_2
+
+			msgs	=	[
+
+				[ 'msg-1' ],
+				[ 'msg-2' ],
+			]
+
+			output	=	self.class.log_to_Tempfile_and_get_output msgs, :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 2, lines.size
+			assert_match /msg-1$/, lines[0]
+			assert_match /msg-2$/, lines[1]
+		end
+
+		def test_simple_logging_with_Tempfile_path_1
+
+			message	=	'msg'
+
+			output	=	self.class.log_to_Tempfile_path_and_get_output [ message ], :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 1, lines.size
+			assert_match /msg$/, lines[0]
+		end
+
+		def test_simple_logging_with_Tempfile_path_2
+
+			msgs	=	[
+
+				[ 'msg-1' ],
+				[ 'msg-2' ],
+			]
+
+			output	=	self.class.log_to_Tempfile_path_and_get_output msgs, :notice, nil, nil
+
+			lines	=	output.split /\n/
+
+			assert_not_empty lines
+			assert_equal 2, lines.size
+			assert_match /msg-1$/, lines[0]
+			assert_match /msg-2$/, lines[1]
+		end
+	end
+end
+
+

data/test/unit/util/tc_process_util.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../..', 'lib')
+
+require 'pantheios/util/process_util'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+class Test_ProcessUtil_set_thread_name < Test::Unit::TestCase
+
+	PU = ::Pantheios::Util::ProcessUtil
+
+	def test_derive_process_name
+
+		assert_equal 'abc', PU.derive_process_name('abc')
+
+		assert_equal 'abc', PU.derive_process_name('abc.rb')
+
+		assert_equal 'abc', PU.derive_process_name('abc.rb')
+	end
+end
+

data/test/unit/util/tc_reflection_util.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../..', 'lib')
+
+require 'pantheios/util/reflection_util'
+
+require 'xqsr3/extensions/test/unit'
+
+require 'test/unit'
+
+class Test_ReflectionUtil_set_thread_name < Test::Unit::TestCase
+
+	class Grandparent; end
+
+	class Parent < Grandparent; end
+
+	class Child < Parent; end
+
+
+	class Basic_Grandparent < BasicObject; end
+
+	class Basic_Parent < Basic_Grandparent; end
+
+	class Basic_Child < Basic_Parent; end
+
+
+	RU = ::Pantheios::Util::ReflectionUtil
+
+	def test_non_root_classes_end_cases
+
+		assert_empty RU.non_root_classes(nil)
+
+		assert_empty RU.non_root_classes(::Object)
+
+		assert_equal [ ::Regexp ], RU.non_root_classes(//)
+
+		assert_equal [ ::String ], RU.non_root_classes('')
+
+		assert_equal [ ::String ], RU.non_root_classes(::String)
+
+		assert_equal [ Grandparent ], RU.non_root_classes(Grandparent)
+
+		assert_equal [ Parent, Grandparent ], RU.non_root_classes(Parent)
+
+		assert_equal [ Child, Parent, Grandparent ], RU.non_root_classes(Child)
+
+		assert_equal [ Basic_Grandparent ], RU.non_root_classes(Basic_Grandparent)
+
+		assert_equal [ Basic_Parent, Basic_Grandparent ], RU.non_root_classes(Basic_Parent)
+
+		assert_equal [ Basic_Child, Basic_Parent, Basic_Grandparent ], RU.non_root_classes(Basic_Child)
+	end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pantheios-ruby
 version: !ruby/object:Gem::Version
-  version: 0.13.4
+  version: 0.18.1
 platform: ruby
 authors:
 - Matt Wilson
@@ -46,23 +46,33 @@ files:
 - lib/pantheios/globals.rb
 - lib/pantheios/services/null_log_service.rb
 - lib/pantheios/services/simple_console_log_service.rb
+- lib/pantheios/services/simple_file_log_service.rb
 - lib/pantheios/services/standard_log_service_adapter.rb
 - lib/pantheios/util.rb
 - lib/pantheios/util/process_util.rb
+- lib/pantheios/util/reflection_util.rb
 - lib/pantheios/util/thread_util.rb
 - lib/pantheios/util/version_util.rb
 - lib/pantheios/version.rb
 - test/performance/test_perf_simple_statements.rb
 - test/performance/test_perf_trace_variants.rb
+- test/scratch/log_files/placeholder
+- test/scratch/log_rolling_by_period_daily.rb
+- test/scratch/log_rolling_by_size_and_depth.rb
 - test/scratch/log_using_blocks.rb
 - test/unit/application_layer/tc_param_name_list.rb
 - test/unit/application_layer/tc_stock_severity_levels.rb
 - test/unit/application_layer/ts_all.rb
+- test/unit/core/tc_core_1.rb
+- test/unit/core/ts_all.rb
 - test/unit/services/tc_null_log_service.rb
 - test/unit/services/tc_simple_console_log_service.rb
+- test/unit/services/tc_simple_file_log_service.rb
 - test/unit/services/tc_standard_log_service_adapter.rb
 - test/unit/services/ts_all.rb
 - test/unit/ts_all.rb
+- test/unit/util/tc_process_util.rb
+- test/unit/util/tc_reflection_util.rb
 - test/unit/util/tc_thread_util.rb
 - test/unit/util/tc_version_util.rb
 - test/unit/util/ts_all.rb