pantheios-ruby 0.18.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 851dd68a076bd0aec6f50aac903ec3481e11b5b5
-  data.tar.gz: f9fd44e79e3beb975796a0e165ec862bff647a75
+  metadata.gz: beccaa832a0515a050313c91e674a3804ffe4ac5
+  data.tar.gz: 2d1e8e82b8f7999578c9898afc94730e86e165d2
 SHA512:
-  metadata.gz: 266c00061542c2f1f6a45337ee76d340cadcf9b3d5e81d452400b70c9ca06f2020b62827de054811401a5cf0aa573f37046f668b1cf1ba26deb958a9188a4243
-  data.tar.gz: 9d87377399759d09b0b636100761737eef9291e1d1e8a8699b9f68c59ed19b8343bb32d02d94eb4b879d2f50c85cff9da102a5d30dfe286268a2ac34e4e76a9e
+  metadata.gz: 06cfa816a8c31242ea15e6673064c136ccf7b1457f8ed399c165426c2515879c3f3d465aae57f302c3880bcee8b6ef7101e95c93f0526a5b0c9c6eeb521453c1
+  data.tar.gz: 3887176f2effa59a70304a4c8b5c8da013bf122f9d8882042955767c700b747ceea39d859d0351430fecc08ec32fabfc73f09513cf0d50c3367e22cbe58ef188

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/multiple_modules.md

@@ -0,0 +1,204 @@
+# Pantheios.Ruby Example - **multiple_modules**
+
+## Summary
+
+Example showing application of Pantheios into multiple modules and
+suppression of arbitrary severity levels specified as command line
+arguments
+
+## Source
+
+```ruby
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# ######################################
+# requires
+
+require 'pantheios'
+
+# ######################################
+# modules
+
+module Organisation
+
+module Helpers
+
+	include ::Pantheios
+
+	def with_trace
+
+		trace
+	end
+
+	def with_debug0; log(:debug0); end
+	def with_debug1; log(:debug1); end
+	def with_informational; log(:informational); end
+	def with_notice; log(:notice); end
+	def with_warning; log(:warning); end
+	def with_failure; log(:failure); end
+	def with_critical; log(:critical); end
+	def with_alert; log(:alert); end
+
+	def helper1
+
+		trace
+
+		with_debug0
+
+		with_notice
+	end
+
+end # module Helpers
+
+class OrgClass
+
+	include Helpers
+	include ::Pantheios
+
+	def initialize()
+
+		trace
+
+		log(:debug2) { 'initialised instance of OrgClass' }
+
+		helper1
+	end
+
+end # class OrgClas
+
+end # module Organisation
+
+# ######################################
+# includes
+
+include ::Organisation::Helpers
+
+include ::Pantheios
+
+# ######################################
+# constants
+
+SUPPRESSED_SEVERITIES = %i{
+
+
+}
+
+# ######################################
+# diagnostics
+
+def detect_suppression argv
+
+	argv.each do |arg|
+
+		SUPPRESSED_SEVERITIES << arg.to_sym
+	end
+end
+
+class FrontEnd
+
+	def severity_logged? severity
+
+		case severity
+		when ::Symbol
+
+			!SUPPRESSED_SEVERITIES.include?(severity)
+		else
+
+			true
+		end
+	end
+end
+
+Pantheios::Core.set_front_end FrontEnd.new
+
+# ######################################
+# main
+
+detect_suppression ARGV
+
+log(:some_level)
+
+log(:notice, 'starting up')
+
+puts "Suppressed severities: #{SUPPRESSED_SEVERITIES}"
+
+log(:info) { "Calling helpers" }
+
+with_trace
+
+with_debug0
+with_debug1
+helper1
+with_critical
+with_alert
+
+log(:info) { "Creating instance of OrgClass" }
+
+oc = Organisation::OrgClass.new
+
+# ############################## end of file ############################# #
+
+```
+
+
+## Usage
+
+### No arguments
+
+When executed as follows
+
+```
+$ ./examples/multiple_modules.rb
+```
+
+it gives the following output:
+
+```
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853720, some_level]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853882, Notice]: starting up
+Suppressed severities: []
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.853971, Informational]: Calling helpers
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854134, Trace]: ./examples/multiple_modules.rb:21: Object#with_trace()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854200, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854255, Debug-1]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854333, Trace]: ./examples/multiple_modules.rb:35: Object#helper1()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854386, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854522, Notice]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854582, Critical]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854631, Alert]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854684, Informational]: Creating instance of OrgClass
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854772, Trace]: ./examples/multiple_modules.rb:51: Organisation::OrgClass#initialize()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854852, Debug-2]: initialised instance of OrgClass
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854930, Trace]: ./examples/multiple_modules.rb:35: Organisation::OrgClass#helper1()
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.854985, Debug-0]:
+[multiple_modules, 70123884951220, 2020-06-03 20:30:15.855035, Notice]:
+```
+
+### Some named suppressed levels
+
+When executed as follows
+
+```
+$ ./examples/multiple_modules.rb trace debug2
+```
+
+it gives the following output:
+
+```
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.201933, some_level]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202013, Notice]: starting up
+Suppressed severities: [:trace, :debug2]
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202050, Informational]: Calling helpers
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202073, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202091, Debug-1]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202110, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202125, Notice]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202167, Critical]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202199, Alert]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202243, Informational]: Creating instance of OrgClass
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202269, Debug-0]:
+[multiple_modules, 70350289450660, 2020-06-03 20:25:49.202286, Notice]:
+```
+

data/examples/multiple_modules.rb

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# ######################################
+# requires
+
+require 'pantheios'
+
+# ######################################
+# modules
+
+module Organisation
+
+module Helpers
+
+	include ::Pantheios
+
+	def with_trace
+
+		trace
+	end
+
+	def with_debug0; log(:debug0); end
+	def with_debug1; log(:debug1); end
+	def with_informational; log(:informational); end
+	def with_notice; log(:notice); end
+	def with_warning; log(:warning); end
+	def with_failure; log(:failure); end
+	def with_critical; log(:critical); end
+	def with_alert; log(:alert); end
+
+	def helper1
+
+		trace
+
+		with_debug0
+
+		with_notice
+	end
+
+end # module Helpers
+
+class OrgClass
+
+	include Helpers
+	include ::Pantheios
+
+	def initialize()
+
+		trace
+
+		log(:debug2) { 'initialised instance of OrgClass' }
+
+		helper1
+	end
+
+end # class OrgClas
+
+end # module Organisation
+
+# ######################################
+# includes
+
+include ::Organisation::Helpers
+
+include ::Pantheios
+
+# ######################################
+# constants
+
+SUPPRESSED_SEVERITIES = %i{
+
+
+}
+
+# ######################################
+# diagnostics
+
+def detect_suppression argv
+
+	argv.each do |arg|
+
+		SUPPRESSED_SEVERITIES << arg.to_sym
+	end
+end
+
+class FrontEnd
+
+	def severity_logged? severity
+
+		case severity
+		when ::Symbol
+
+			!SUPPRESSED_SEVERITIES.include?(severity)
+		else
+
+			true
+		end
+	end
+end
+
+Pantheios::Core.set_front_end FrontEnd.new
+
+# ######################################
+# main
+
+detect_suppression ARGV
+
+log(:some_level)
+
+log(:notice, 'starting up')
+
+puts "Suppressed severities: #{SUPPRESSED_SEVERITIES}"
+
+log(:info) { "Calling helpers" }
+
+with_trace
+
+with_debug0
+with_debug1
+helper1
+with_critical
+with_alert
+
+log(:info) { "Creating instance of OrgClass" }
+
+oc = Organisation::OrgClass.new
+
+# ############################## end of file ############################# #
+
+

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