pantheios-ruby 0.22.0.2 → 0.22.3

data/README.md

@@ -1,5 +1,137 @@
-# **Pantheios.Ruby**
+# Pantheios.Ruby <!-- omit in toc -->
+
 Pantheios, for Ruby
 
-T.B.C.
+![Language](https://img.shields.io/badge/Ruby-CC342D?style=flat&logo=ruby&logoColor=white)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Gem Version](https://badge.fury.io/rb/pantheios-ruby.svg)](https://badge.fury.io/rb/pantheios-ruby)
+[![Last Commit](https://img.shields.io/github/last-commit/synesissoftware/Pantheios.Ruby)](https://github.com/synesissoftware/Pantheios.Ruby/commits/master)
+[![Ruby](https://github.com/synesissoftware/Pantheios.Ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/synesissoftware/Pantheios.Ruby/actions/workflows/ruby.yml)
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Components](#components)
+- [Examples](#examples)
+- [Project Information](#project-information)
+  - [Where to get help](#where-to-get-help)
+  - [Contribution guidelines](#contribution-guidelines)
+  - [Dependencies](#dependencies)
+    - [Efferent (fan-out)](#efferent-fan-out)
+      - [Runtime Dependencies (aka "Normal Dependencies")](#runtime-dependencies-aka-normal-dependencies)
+      - [Development Dependencies](#development-dependencies)
+    - [Afferent (fan-in)](#afferent-fan-in)
+      - [Runtime dependents](#runtime-dependents)
+      - [Development dependents](#development-dependents)
+  - [Related projects](#related-projects)
+  - [License](#license)
+
+
+## Introduction
+
+**Pantheios** is a diagnostic logging API library, originally implemented for C/C++ and later for .NET. **Pantheios.Ruby** is the **Ruby** implementation.
+
+It provides a layered logging model: application-facing severity levels and API helpers, optional front-ends (for example threshold filtering), and pluggable back-end log services (console, coloured console, file, null, multiplexing, and adapters).
+
+
+## Installation
+
+Install via **gem** as in:
+
+```
+gem install pantheios-ruby
+```
+
+or add it to your `Gemfile`.
+
+**Pantheios.Ruby** requires Ruby **2.0+**.
+
+> **NOTE**: On **Ruby 4+**, also install [**logger**](https://rubygems.org/gems/logger) (`gem install logger`, or `gem 'logger'` in your Gemfile). See [Runtime Dependencies](#runtime-dependencies-aka-normal-dependencies).
+
+Use via **require**, as in:
+
+```Ruby
+require 'pantheios'
+```
+
+
+## Components
+
+* **Pantheios::API** — primary logging API surface;
+* **Pantheios::ApplicationLayer** — stock severity levels and related application helpers;
+* **Pantheios::Core** — core registration and back-end wiring;
+* **Pantheios::FrontEnds** — front-ends such as **ThresholdFrontEnd**;
+* **Pantheios::Services** — back-end log services (console, coloured console, file, null, multiplexing, adapters);
+* **Pantheios::Util** — process, reflection, thread, and version utilities;
+
+
+## Examples
+
+Examples are provided in the ```examples``` directory, along with a markdown description where present. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
+
+
+## Project Information
+
+
+### Where to get help
+
+[GitHub Page](https://github.com/synesissoftware/Pantheios.Ruby "GitHub Page")
+
+
+### Contribution guidelines
+
+Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Pantheios.Ruby.
+
+
+### Dependencies
+
+
+#### Efferent (fan-out)
+
+Libraries upon which **Pantheios.Ruby** depends:
+
+
+##### Runtime Dependencies (aka "Normal Dependencies")
+
+* \<none> declared in **pantheios-ruby.gemspec**;
+
+> **NOTE**: On **Ruby 4+**, **logger** is required at runtime (`lib/pantheios/services/simple_file_log_service.rb`, `lib/pantheios/services/standard_log_service_adapter.rb`) but is no longer a default gem and is not listed in **pantheios-ruby.gemspec** (so older Rubies in the `[2.0, 4)` range still resolve). Install it explicitly, e.g. `gem install logger`, or add `gem 'logger'` to your Gemfile. This repository’s **Gemfile** pulls it in when `RUBY_VERSION >= '4'`.
+
+
+##### Development Dependencies
+
+* [**rake**](https://rubygems.org/gems/rake);
+* [**test-unit**](https://rubygems.org/gems/test-unit);
+* [**xqsr3**](https://github.com/synesissoftware/xqsr3);
+
+
+#### Afferent (fan-in)
+
+Projects that depend on **Pantheios.Ruby**:
+
+
+##### Runtime dependents
+
+* \<none>;
+
+
+##### Development dependents
+
+* \<none>;
+
+
+### Related projects
+
+* [**Pantheios**](https://github.com/synesissoftware/Pantheios/) (**C**/**C++**);
+* [**Pantheios.NET**](https://github.com/synesissoftware/Pantheios.NET/);
+* [**Pantheios.Rust**](https://github.com/synesissoftware/Pantheios.Rust/);
+
+
+### License
+
+**Pantheios.Ruby** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.
+
 
+<!-- ########################### end of file ########################### -->

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Rakefile for Pantheios.Ruby
+
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |tt|
+
+  tt.libs << 'lib'
+  tt.libs << 'test'
+  tt.name = 'test'
+  tt.test_files = FileList['test/**/tc_*.rb']
+  tt.verbose = true
+end
+
+
+task :default => :test
+
+
+# ############################## end of file ############################# #

data/SECURITY.md

@@ -0,0 +1,23 @@
+# Pantheios.Ruby - Security <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Reporting a vulnerability](#reporting-a-vulnerability)
+- [Supported versions](#supported-versions)
+
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories on https://github.com/synesissoftware/Pantheios.Ruby/security, or by opening an issue if an advisory cannot be filed. Do not attach exploit proofs of concept against third-party systems.
+
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.22.x  | ✅        |
+| < 0.22  | ❌        |
+
+
+<!-- ########################### end of file ########################### -->

data/TODO.md

@@ -0,0 +1,29 @@
+# Pantheios.Ruby - TODO <!-- omit in toc -->
+
+
+## Functional improvements
+
+* [x] ~~~quiet unused-variable warnings in **simple_file_log_service.rb**
+  (`logger_init_options`) and **standard_log_service_adapter.rb** (`sym`)~~~;
+* [x] ~~~quiet **Warnings** job noise in tests: unused `pid` in
+  **tc_standard_log_service_adapter.rb**; ambiguous `/` in
+  **tc_simple_file_log_service.rb** and **tc_standard_log_service_adapter.rb**~~~;
+
+
+## Performance improvements
+
+* \<none>
+
+
+## Packaging improvements
+
+* [ ] catalogue known afferent dependents in **README.md** when any are identified;
+* [x] ~~~handle Ruby **4** stdlib **logger** no longer being a default gem (**Gemfile** when `RUBY_VERSION >= '4'`; not in the gemspec because the **logger** gem requires Ruby **>= 2.5**)~~~;
+* [x] ~~~rename gemspec so the filename stem matches `spec.name` (`Pantheios.Ruby.gemspec` → **pantheios-ruby.gemspec**)~~~;
+* [x] ~~~obtain a **run_all_unit_tests.sh** (from **misc-dev-scripts**) that skips `tput` when `$TERM` is unset or stdout is not a TTY (CI: `tput: No value for $TERM and no -T specified`)~~~;
+* [x] ~~~gemspec polish: README tagline as `spec.summary`, package docs, exclude **Gemfile.lock** / **.ruby-version**~~~;
+* [x] ~~~stop tracking **Gemfile.lock**; **Gemfile** `lockfile false` when Bundler supports it; CI `bundler-cache: false`~~~;
+* [x] ~~~after the packaging/boilerplate/CI baseline: bump **VERSION** and align **CHANGES**/**NEWS**~~~;
+
+
+<!-- ########################### end of file ########################### -->

data/examples/coloured_console_log_service.rb

@@ -29,7 +29,7 @@ LEVELS = %i{ violation alert critical failure warning notice informational debug
 
 LEVELS.each do |level|
 
-	log(level, "logging level #{level}")
+  log(level, "logging level #{level}")
 end
 
 # ############################## end of file ############################# #

data/examples/multiple_modules.md

@@ -1,4 +1,4 @@
-# Pantheios.Ruby Example - **multiple_modules**
+# Pantheios.Ruby - Example - **multiple_modules**
 
 ## Summary
 

data/examples/multiple_modules.rb

@@ -14,46 +14,46 @@ module Organisation
 
 module Helpers
 
-	include ::Pantheios
+  include ::Pantheios
 
-	def with_trace
+  def with_trace
 
-		trace
-	end
+    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 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
+  def helper1
 
-		trace
+    trace
 
-		with_debug0
+    with_debug0
 
-		with_notice
-	end
+    with_notice
+  end
 
 end # module Helpers
 
 class OrgClass
 
-	include Helpers
-	include ::Pantheios
+  include Helpers
+  include ::Pantheios
 
-	def initialize()
+  def initialize()
 
-		trace
+    trace
 
-		log(:debug2) { 'initialised instance of OrgClass' }
+    log(:debug2) { 'initialised instance of OrgClass' }
 
-		helper1
-	end
+    helper1
+  end
 
 end # class OrgClas
 
@@ -79,25 +79,25 @@ SUPPRESSED_SEVERITIES = %i{
 
 def detect_suppression argv
 
-	argv.each do |arg|
+  argv.each do |arg|
 
-		SUPPRESSED_SEVERITIES << arg.to_sym
-	end
+    SUPPRESSED_SEVERITIES << arg.to_sym
+  end
 end
 
 class FrontEnd
 
-	def severity_logged? severity
+  def severity_logged? severity
 
-		case severity
-		when ::Symbol
+    case severity
+    when ::Symbol
 
-			!SUPPRESSED_SEVERITIES.include?(severity)
-		else
+      !SUPPRESSED_SEVERITIES.include?(severity)
+    else
 
-			true
-		end
-	end
+      true
+    end
+  end
 end
 
 Pantheios::Core.set_front_end FrontEnd.new
@@ -125,7 +125,7 @@ with_alert
 
 log(:info) { "Creating instance of OrgClass" }
 
-oc = Organisation::OrgClass.new
+Organisation::OrgClass.new
 
 # ############################## end of file ############################# #
 

data/examples/simple_logging.md

@@ -1,4 +1,4 @@
-# Pantheios.Ruby Example - **simple_logging**
+# Pantheios.Ruby - Example - **simple_logging**
 
 ## Summary
 

data/examples/simple_logging.rb

@@ -29,7 +29,7 @@ LEVELS = %i{ violation alert critical failure warning notice informational debug
 
 LEVELS.each do |level|
 
-	log(level, "logging level #{level}")
+  log(level, "logging level #{level}")
 end
 
 # ############################## end of file ############################# #

data/examples/threshold_front_end.rb

@@ -40,7 +40,7 @@ Pantheios::Core.set_front_end Pantheios::FrontEnds::ThresholdFrontEnd.new thresh
 
 LEVELS.each do |level|
 
-	log(level, "logging level #{level}")
+  log(level, "logging level #{level}")
 end
 
 # ############################## end of file ############################# #