rb_falcon_logger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0bad75b78e2dc2cc1edc991a6e7fc912937e45252605057c324ce54a630120f2
+  data.tar.gz: 250fe6f8ec33ece120659375e8b2869a8046c28bbd31715ba4d9b6c4824e8ada
+SHA512:
+  metadata.gz: 70f5902ea03b8c144d6845da7514112602a859c1e8249a84dbb38df012269db05b069aea38bcc35b51bfd1027ed5d1ba2f16cc01057c4c23680c7b24c203aa1d
+  data.tar.gz: f6da83bc50a6ccd04deee151da80e138aa3e86189202b2049f58d68fcda181c18fca8f55d4bf7f9447cd6f5aaae78188527f3f6f884a8d648d21feb6e688f6f1

data/LICENSE.txt

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) since 2025: rb-falcon-logger Ruby Gem
+description: fast logger with multiple modes and formats
+author:      J. Arrizza   email: cppgent0@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,215 @@
+* website: <https://arrizza.com/rb-falcon-logger.html>
+* installation: see <https://arrizza.com/setup-common.html>
+
+## Summary
+
+This is a ruby gem that provides a way to run a fast logger.
+see <https://arrizza.com/python-falcon-logger.html> for a python version
+
+## Sample code
+
+see src/logger_tester.rb for a full example
+
+Use doit script to run the logger.
+
+TODO logger_tester args
+TODO multithreaded_tester
+
+## parameters and functions
+
+Use these on the logger creation: ```@log = FalconLogger(path: etc, max_entries: etc, mode: etc.)```
+
+* ```path: nil``` : (default) write to stdout
+* ```path: 'path/to/file'``` : write to the given file
+* ```max_entries: 10```: flush the queue when this number of log entries is reached.
+* ```loop_delay: 0.250```: check the queue this often. The longer the delay, the fast it runs.
+* Note: use max_entries: 1 and loop_delay: 0.001, to flush the queue as often as possible
+* ```set_verbose(true)``` - (default) print all log lines to stdout/file.
+* ```set_verbose(false)``` - only print err(), critical(), exception(), and bug() lines
+* ```@log.set_max_dots(num)``` set the number of dots to print before a newline is printed
+* use ```@log.save``` to force the queue to be saved. Generally not recommended.
+* use ```@log.term``` to clear out the queue and gracefully end the background thread
+
+There are 3 modes: ```FalconLogger(mode: 'normal')```
+
+* nil or 'normal': (default) writes a line to stdout or the file. See below for outputs
+* 'ut' or 'mock': useful in UTs. These do not write to stdout or to a file.
+    * The lines are saved in an internal list accessible by: ```@log.ut_lines```.
+    * Use ```@log.ut_clear``` or ```@log.ut_lines = []``` to empty it.
+* 'null': is useful when you don't want any output. No stdout, no file, no ut_lines.
+
+There are 3 formats: 'elapsed' (default), 'prefix', 'none'
+
+* Use ```@log.set_format(fmt)``` to set the format to fmt
+
+## 'elapsed' format outputs
+
+These contain:
+
+* the number of MM:SS.nnn milliseconds since the last log line
+    * if this the first log line, the current date time stamp is automatically printed:
+      ```DTS  2025/05/11 16:21:43.170```
+    * if an hour goes by since the last DTS, then it is automatically printed
+* a prefix indicating the type of log line error, OK, Debug, etc.
+
+```text
+@log.set_format('elapsed')  # the default format
+
+# idx = 2
+
+# === showing with elapsed time delays
+# === @log.start("#{idx}:", 'start of dts values')
+# === sleep(0.250)
+# === @log.line("#{idx}:", 'start + 250ms')
+# === sleep(0.123)
+# === @log.line("#{idx}:", 'start + 373ms')
+00:00.000 ==== 2: start of dts values
+00:00.250      2: start + 250ms
+00:00.373      2: start + 373ms
+
+# === the automatic DTS line when 1 hour has elapsed or at the beginning
+# === @log.start("#{idx}:", 'start')
+          DTS  2025/05/21 19:01:11.154
+00:00.000 ==== 2: start
+
+# === @log.line("#{idx}:", 'line')
+00:00.000      2: line
+
+# === @log.highlight("#{idx}:", 'highlight')
+00:00.000 ---> 2: highlight
+
+# === @log.ok("#{idx}:", 'ok')
+00:00.000 OK   2: ok
+
+# === @log.err("#{idx}:", 'err')
+00:00.000 ERR  2: err
+
+# === @log.warn("#{idx}:", 'warn')
+00:00.000 WARN 2: warn
+
+# === @log.bug("#{idx}:", 'bug')
+00:00.000 BUG  2: bug
+
+# === @log.dbg("#{idx}:", 'dbg')
+00:00.000 DBG  2: dbg
+
+# === @log.raw("#{idx}", 'raw', 'line')
+2 raw line
+
+# === @log.output(nil, "#{idx}:", 'output (line nil)')
+# === @log.output(21, "#{idx}:", 'output (line 21)')
+00:00.000  --       2: output (line nil)
+00:00.000  --   21] 2: output (line 21)
+
+#=== lines = ["#{idx}: num_output (line 1)", "#{idx}: num_output (line 2)"]
+#=== @log.num_output(lines)
+00:00.000  --    1] 2: num_output (line 1)
+00:00.000  --    2] 2: num_output (line 2)
+
+# === @log.check(true, "#{idx}:", 'check true')
+# === @log.check(false, "#{idx}:", 'check false')
+00:00.000 OK   2: check true
+00:00.000 ERR  2: check false
+
+# === lines = ["#{idx}: check_all (line 1)", "#{idx}: check_all (line 2)"]
+# === @log.check_all(true, 'check_all true title', lines)
+00:00.000 OK   check_all true title: true
+00:00.000 OK      - 2: check_all (line 1)
+00:00.000 OK      - 2: check_all (line 2)
+
+# === info = { 'key1' => ['val1'] }
+# === @log.json(info, "#{idx}:", 'json', 'list (json/hash)')
+00:00.000      2: json list (json/hash)
+00:00.000  >   {
+00:00.000  >     "key1": [
+00:00.000  >       "val1"
+00:00.000  >     ]
+00:00.000  >   }
+
+#=== val = "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11"
+#=== @log.hex(val, "#{idx}:", 'hex long')
+00:00.000      2: hex long
+00:00.000          0 0x00: 00 01 02 03 04 05 06 07   08 09 0A 0B 0C 0D 0E 0F
+00:00.000         16 0x10: 10 11
+
+# === @log.debug("#{idx}:", 'debug')
+00:00.000 DBG  2: debug
+
+# === @log.info("#{idx}:", 'info')
+00:00.000      2: info
+
+# === @log.warning("#{idx}:", 'warning')
+00:00.000 WARN 2: warning
+
+# === @log.error("#{idx}:", 'error')
+00:00.000 ERR  2: error
+
+# === @log.critical("#{idx}:", 'critical')
+00:00.000 CRIT 2: critical
+
+# === val = 5
+# === begin
+# ===   val /= 0
+# === rescue ZeroDivisionError => e   # <== note: use max_lines: 1 to reduce the amount of output you need
+# ===   @log.exception(e)
+# === end
+# === @log.line("after excp; val=#{val}")
+00:00.000 EXCP divided by 0
+00:00.000 EXCP Backtrace:
+00:00.000 EXCP    <snip>/logger_tester.rb:178:in `/'
+00:00.000 EXCP    <snip>/logger_tester.rb:178:in `_log_exception'
+00:00.000 EXCP    <snip>/logger_tester.rb:88:in `block in run'
+    
+# === @log.full_dts
+       DTS  2025/05/11 16:21:43.170
+```
+
+## 'prefix' format outputs
+
+These are the same as elapsed format, except no elapsed times.
+Use ```./doit normal prefix``` to see an example.
+
+```text
+@log.set_format('prefix')
+
+# === @log.ok("#{idx}:", 'ok')
+OK   2: ok
+# === @log.err("#{idx}:", 'err')
+ERR  2: err
+<snip>
+```
+
+## 'none' format outputs
+
+These are the same as elapsed/prefix format, except no elapsed times or prefixes
+Use ```./doit normal none``` to see an example.
+
+```text
+@log.set_format('none')
+
+# === @log.ok("#{idx}:", 'ok')
+2: ok
+# === @log.err("#{idx}:", 'err')
+2: err
+<snip>
+```
+
+## dots
+
+To put out a series of dots to show progress, use ```@log.dot```.
+
+Periodically a newline is printed.
+The default is 25, use ```@log.set_max_dots(nn)``` to change it
+
+## ./doit examples
+
+* Use ```./doit file``` to generate a file ```out/sample.log```
+* Use ```./doit null``` to use ```mode: 'null'```, no output, no file generated
+* Use ```./doit ut```  or ```./doit mock``` to use ```mode: 'ut'```. This mode can be used in unit tests.
+* Use ```./doit thread``` to see an example of a multithreaded use of the logger. The default is:
+    * 100 client threads
+    * each client thread putting in 1000 entries onto the queue.
+    * There are random delays between each push() between 0 and 250ms
+    * each client thread logs it is putting an entry on the queue using FalconLogger
+    * 1 background thread checking that queue, and printing any entries using FalconLogger
+    * This takes just over 2m (on my PC)

data/lib/gem_source/logger.rb

@@ -0,0 +1,870 @@
+# frozen_string_literal: true
+require 'json'
+
+# import atexit
+# import threading
+
+# -------------------
+## Sample gem source
+class FalconLogger
+  ## logging formats
+  class LogFormat
+    include Enumerable
+
+    ## logging format with elapsed time and prefixes
+    ELAPSED = 1
+    ## logging format with prefixes only
+    PREFIX = 2
+    ## logging format with no prefixes or elapsed time
+    NONE = 3
+  end
+
+  ## configuration in for bg thread runner
+  class RunnerCfg
+    ## the maximum entries to hold in the queue before saving to the file
+    attr_accessor :max_entries
+    ## the maximum number of loops before the queue is emptied
+    attr_accessor :max_count
+    ## the delay between checking the queue for entries to save
+    attr_accessor :loop_delay
+
+    # -------------------
+    def initialize
+      @max_entries = 0
+      @max_count   = 0
+      @loop_delay  = 0.0
+    end
+
+    # -------------------
+    def copy_from(copy_obj)
+      @max_entries = copy_obj.max_entries
+      @max_count   = copy_obj.max_count
+      @loop_delay  = copy_obj.loop_delay
+    end
+  end
+
+  ## holds verbosity
+  attr_writer :verbose
+
+  ## UT only: holds all lines printed
+  attr_accessor :ut_lines
+
+  ###
+  ## constructor
+  # @param path         nil for stdout, or full path to the logger file
+  # @param max_entries  (optional) maximum number of entries before a flush is done; default 10
+  # @param loop_delay   (optional) time between checking queue; default 0.250 seconds
+  # @param mode         (optional) logging mode:
+  #                      nil or "normal": (default) log all lines as set by configuration, format, etc.
+  #                      "ut" or "mock": for UT purposes, saves lines in ut_lines array
+  #                      "null": do no logging; see verbosity for an alternative
+  def initialize(path: nil,
+                 max_entries: 10,
+                 loop_delay: 0.250,
+                 mode: nil)
+    ## the full path to the log file (if any)
+    @path = path
+    ## file pointer to destination file or stdout
+    @fp = nil
+    ## holds the logging mode (nil, normal, ut, etc.
+    @logging_mode = mode
+    ## holds the function that handles the logging of the current mode and format
+    @log_it = nil
+
+    ## flag to log to stdout or not
+    @verbose = true
+    ## for UT only
+    @ut_mode = false
+    ## for UT only
+    @ut_lines = []
+
+    # === log formatting related
+
+    ## verbosity; if true print all lines, if not print only errors, excp ad bug lines
+    @verbose = true
+    ## the log display format to use; default: elapsed time + prefixes
+    @log_format = LogFormat::ELAPSED
+    ## holds the last time a full DTS was written to the log;
+    # printed at the beginning and once per hour
+    @start_time = Time.at(0.0)
+    ## current number of dots printed
+    @dots = 0
+    ## max number of dots to display
+    @max_dots = 25
+
+    # === runner() related
+    ## configuration values used by runner()
+    @runner_cfg = nil
+    ## backup of runner_cfg
+    @backup_cfg = nil
+    ## the bg thread used to run
+    @thread = nil
+    ## the queue used
+    @queue = nil
+    ## flag to the thread to end the loop
+    @finished = false
+
+    # === log_mode related
+    _init_cfg(max_entries, loop_delay)
+    if mode.nil? || mode == 'normal'
+      @logging_mode = 'normal'
+      @log_it       = method(:_log_it_normal)
+
+      # initialize destination file pointer
+      @fp = $stdout
+      if @path.nil?
+        @fp = $stdout
+      else
+        @fp = File.open(@path, 'w', encoding: 'UTF-8')
+      end
+      _init_thread
+    elsif %w[ut mock].include?(mode)
+      _set_log_it_ut_fn
+    elsif mode == 'null'
+      @log_it = method(:_log_it_null)
+    else
+      raise(ArgumentError, "Unknown mode: \"#{mode}\", choose \"normal\", \"ut\", \"mock\" or \"null\"")
+    end
+
+    # try ensure at least one save() and thread cleanup is done
+    at_exit do
+      # uncomment to debug
+      # puts('in at_exit:')
+      term
+    end
+  end
+
+  # --------------------
+  ## initialize the configuration variables for the loop
+  #
+  # @param max_entries   the max number of entries in the queue
+  # @param loop_delay    how long to wait between checks of the queue
+  # @return nil
+  def _init_cfg(max_entries, loop_delay)
+    @runner_cfg = RunnerCfg.new
+    set_max_entries(max_entries)
+    set_loop_delay(loop_delay)
+    @backup_cfg = RunnerCfg.new
+    @backup_cfg.copy_from(@runner_cfg)
+  end
+
+  # --------------------
+  ## initialize and start the thread
+  #
+  # @return nil
+  def _init_thread
+    @queue    = Queue.new
+    @finished = false
+
+    @thread = Thread.new do
+      _runner
+    end
+
+    # wait for thread to start
+    sleep(0.100)
+  end
+
+  # --------------------
+  ## UT only; clears ut_lines
+  # for backwards compatibility with python version
+  #
+  # @return nil
+  def ut_clear
+    @ut_lines = []
+  end
+
+  # --------------------
+  # for UT only; set the start_time to the given value
+  def ut_start_time(new_time)
+    if new_time.is_a?(Float)
+      @start_time = Time.at(new_time)
+    else
+      # assume it's a Time
+      @start_time = new_time
+    end
+  end
+
+  # --------------------
+  ## set verbosity
+  # for backwards compatibility with python version
+  #
+  # @param value  (bool) verbosity level
+  # @return nil
+  def set_verbose(value)
+    @verbose = value
+  end
+
+  # --------------------
+  ## set log line format.
+  #
+  # @param form  (str) either "elapsed", "prefix", "non" or throws excp
+  # @return nil
+  def set_format(form)
+    if form == 'elapsed'
+      @log_format = LogFormat::ELAPSED
+    elsif form == 'prefix'
+      @log_format = LogFormat::PREFIX
+    elsif form == 'none'
+      @log_format = LogFormat::NONE
+    else
+      raise(ArgumentError, "Unknown format: \"#{form}\", choose \"elapsed\", \"prefix\" or \"none\"")
+    end
+
+    _set_log_it_ut_fn if %w[ut mock].include?(@logging_mode)
+  end
+
+  # --------------------
+  ## set the log_it function to call based on the current logging format
+  #
+  # @return nil
+  def _set_log_it_ut_fn
+    if @log_format == LogFormat::ELAPSED
+      @log_it = method(:_log_it_ut_elapsed)
+    elsif @log_format == LogFormat::PREFIX
+      @log_it = method(:_log_it_ut_prefix)
+    elsif @log_format == LogFormat::NONE
+      @log_it = method(:_log_it_ut_none)
+    else
+      # :nocov:
+      # coverage: cannot be done in a UT
+      puts("BUG in _set_log_it_ut_fn : unhandled log format #{@log_format}")
+      # :nocov:
+    end
+  end
+
+  # --------------------
+  ## set max entries to allow in the queue before printing them
+  #
+  # @param value  (int) number of entries; default: 10
+  # @return nil
+  def set_max_entries(value)
+    @runner_cfg.max_entries = value
+    raise(ArgumentError, 'max_entries must be greater than 0') if @runner_cfg.max_entries <= 0
+  end
+
+  # --------------------
+  ## set loop delay to check the queue
+  #
+  # @param loop_delay (float) number of seconds; default: 0.250
+  # @return nil
+  def set_loop_delay(loop_delay)
+    @runner_cfg.loop_delay = loop_delay
+    raise(ArgumentError, 'loop_delay must be >= 0.001 seconds') if @runner_cfg.loop_delay < 0.001
+
+    # print every loop_delay seconds even if less than max_entries are in the queue
+    @runner_cfg.max_count = (1 / @runner_cfg.loop_delay).round(1).to_i
+  end
+
+  # --------------------
+  ## set how many dots to print on one line before printing a newline
+  #
+  # @param value  (int) number of dots
+  # @return nil
+  def set_max_dots(value)
+    @max_dots = value
+    raise(ArgumentError, 'max_dots must be greater than 0') unless @max_dots.positive?
+  end
+
+  # === cleanup functions
+
+  # --------------------
+  ## terminate
+  # stop the thread, save any remaining line in the internal queue
+  #
+  # @return nil
+  def term
+    begin
+      # since this will be called during atexit() handling,
+      # stdout and/or file can be closed. Protect against this case.
+      _save
+    rescue Exception
+      # nothing to do
+    end
+
+    @finished = true
+    @thread.join(5.0) unless @thread.nil? || !@thread.alive?
+  end
+
+  # --------------------
+  ## user can request a save at this point
+  #
+  # @return nil
+  attr_reader :save
+
+  # === log modes
+
+  # --------------------
+  ## since it's normal mode, put the logging info on the queue.
+  #
+  # @param info  the line info
+  # @return nil
+  def _log_it_normal(info)
+    @queue.push(info)
+  end
+
+  # --------------------
+  ## since it's ut mode and no prefixes, add the line to ut_lines
+  #
+  # @param info  the line info
+  # @return nil
+  def _log_it_ut_none(info)
+    return unless info[0] || info[1]
+
+    # always_print or verbose
+    if info[3].nil? && info[4] == [nil]
+      line = 'DTS'
+    elsif info[3] == '.' && info[4] == [nil]
+      line = '.'
+    else
+      line = info[4].join(' ')
+    end
+    @ut_lines.append(line)
+  end
+
+  # --------------------
+  ## since it's ut mode and prefix mode add the line with prefix to ut_lines
+  #
+  # @param info  the line info
+  # @return nil
+  def _log_it_ut_prefix(info)
+    return unless info[0] || info[1]
+
+    # always_print or verbose
+    prefix = info[3]
+    if prefix.nil? && info[4] == [nil]
+      line   = 'DTS'
+      prefix = ' '
+      @ut_lines.append(format('%-4s %s', prefix, line))
+    elsif info[3] == '.' && info[4] == [nil]
+      @ut_lines.append('.')
+    elsif prefix.nil? # raw line
+      line = info[4].join(' ')
+      @ut_lines.append(line)
+    else
+      line = info[4].join(' ')
+      @ut_lines.append(format('%-4s %s', prefix, line))
+    end
+  end
+
+  # --------------------
+  ## since it's ut mode and elapsed mode add the line with elapsed and prefix to ut_lines
+  #
+  # @param info  the line info
+  # @return nil
+  def _log_it_ut_elapsed(info)
+    return unless info[0] || info[1]
+
+    # always_print or verbose
+    dts = info[2]
+
+    elapsed = Time.at(dts - @start_time)
+    if elapsed.to_f >= 3600.0
+      @start_time = Time.now
+      elapsed     = 0.0
+    end
+    t_str   = _get_elapsed_str(elapsed)
+
+    prefix = info[3]
+    if prefix.nil? && info[4] == [nil]
+      line   = 'DTS'
+      prefix = ' '
+      @ut_lines.append(format('%-4s %s', prefix, line))
+    elsif info[3] == '.' && info[4] == [nil]
+      @ut_lines.append('.')
+    elsif prefix.nil? # raw line
+      line = info[4].join(' ')
+      @ut_lines.append(line)
+    else
+      line = info[4].join(' ')
+      @ut_lines.append(format('%s %-4s %s', t_str, prefix, line))
+    end
+  end
+
+  # --------------------
+  ## since it's null mode, ignore the line
+  #
+  # @param info  (ignored)
+  # @return nil
+  def _log_it_null(info)
+    # logging ignored
+  end
+
+  # === log lines with prefixes and elapsed times
+
+  # --------------------
+  ## add an item to write the full date-time-stamp to the log
+  #
+  # @return nil
+  def full_dts
+    # the nil args/line causes the full dts to display
+    @log_it.call([false, @verbose, Time.now, nil, [nil]])
+  end
+
+  # -------------------
+  ## write a "start" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def start(*args)
+    @log_it.call([false, @verbose, Time.now, '====', args].freeze)
+  end
+
+  # --------------------
+  ## write a line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def line(*args)
+    @log_it.call([false, @verbose, Time.now, '', args].freeze)
+  end
+
+  # -------------------
+  ## write a "warn" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def highlight(*args)
+    @log_it.call([false, @verbose, Time.now, '--->', args].freeze)
+  end
+
+  # -------------------
+  ## write a "ok" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def ok(*args)
+    @log_it.call([false, @verbose, Time.now, 'OK', args].freeze)
+  end
+
+  # -------------------
+  ## write an "err" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def err(*args)
+    @log_it.call([true, @verbose, Time.now, 'ERR', args].freeze)
+  end
+
+  # -------------------
+  ## write a "warn" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def warn(*args)
+    @log_it.call([false, @verbose, Time.now, 'WARN', args].freeze)
+  end
+
+  # -------------------
+  ## write a "bug" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def bug(*args)
+    @log_it.call([true, @verbose, Time.now, 'BUG', args].freeze)
+  end
+
+  # -------------------
+  ## write a "dbg" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def dbg(*args)
+    @log_it.call([false, @verbose, Time.now, 'DBG', args].freeze)
+  end
+
+  # -------------------
+  ## write a raw line (no prefix or elapsed)
+  #
+  # @param args  the message to log
+  # @return nil
+  def raw(*args)
+    @log_it.call([false, @verbose, Time.now, nil, args].freeze)
+  end
+
+  # -------------------
+  ## write an output line with the given message
+  #
+  # @param lineno  (optional) the current line number for each line printed
+  # @param args    the message to write
+  # @return nil
+  def output(lineno, *args)
+    if lineno.nil?
+      new_args = ['    ']
+    else
+      new_args = [format('%3d]', lineno)]
+    end
+    new_args += args
+    @log_it.call([false, @verbose, Time.now, ' --', new_args].freeze)
+  end
+
+  # -------------------
+  ## write a list of lines using output()
+  #
+  # @param lines   the lines to write
+  # @return nil
+  def num_output(lines)
+    lineno = 0
+    lines.each do |line|
+      lineno += 1
+      output(lineno, line)
+    end
+  end
+
+  # --------------------
+  ## if ok is true, write an OK line, otherwise an ERR line.
+  #
+  # @param ok   condition indicating ok or err
+  # @param args  the message to log
+  # @return nil
+  def check(ok, *args)
+    if ok
+      ok(args)
+    else
+      err(args)
+    end
+  end
+
+  # --------------------
+  ## log a series of messages. Use ok() or err() as appropriate.
+  #
+  # @param ok      the check state
+  # @param title   the line indicating what the check is about
+  # @param lines   individual list of lines to print
+  # @return nil
+  def check_all(ok, title, lines)
+    check(ok, "#{title}: #{ok}")
+    lines.each do |line|
+      check(ok, "   - #{line}")
+    end
+  end
+
+  # -------------------
+  ## add an item to write a 'line' message and a json object to the log
+  #
+  # @param j_data  the json object to write
+  # @param args    the message to write
+  # @return nil
+  def json(j_data, *args)
+    now = Time.now
+    @log_it.call([false, @verbose, now, ' ', args].freeze)
+
+    j_data = JSON.parse(j_data) if j_data.is_a?(String)
+    JSON.pretty_generate(j_data).split("\n").each do |line|
+      @log_it.call([false, @verbose, now, ' >', [line]].freeze)
+    end
+  end
+
+  # -------------------
+  ## add an item to write a 'line' message and a data buffer to the log in hex
+  #
+  # @param data    the data buffer to write; can be a string or a bytes array
+  # @param args    the message to write
+  # @return nil
+  def hex(data, *args)
+    now = Time.now
+    @log_it.call([false, @verbose, now, ' ', args].freeze)
+    line = format('%3d 0x%02X:', 0, 0)
+    data = data.bytes.to_a if data.is_a?(String)
+
+    # data.each_char
+    col = 0
+    data.each_with_index do |ch, i|
+      if col >= 16
+        @log_it.call([false, @verbose, now, '', [' ', line]].freeze)
+        col  = 0
+        line = format('%3d 0x%02X:', i, i)
+      end
+
+      line += format(' %02X', ch)
+      col  += 1
+      line += '  ' if col == 8
+    end
+
+    # print if there's something left over
+    @log_it.call([false, @verbose, now, ' ', [' ', line]].freeze)
+  end
+
+  # --------------------
+  ## write a dot to stdout
+  #
+  # @return nil
+  def dot
+    @log_it.call([false, @verbose, Time.now, '.', [nil]].freeze)
+  end
+
+  # === (some) compatibility with python logger
+
+  # -------------------
+  ## write a "debug" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def debug(*args)
+    @log_it.call([false, @verbose, Time.now, 'DBG', args].freeze)
+  end
+
+  # --------------------
+  ## write a line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def info(*args)
+    @log_it.call([false, @verbose, Time.now, '', args].freeze)
+  end
+
+  # -------------------
+  ## write a "warn" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def warning(*args)
+    @log_it.call([false, @verbose, Time.now, 'WARN', args].freeze)
+  end
+
+  # -------------------
+  ## write a "err" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def error(*args)
+    @log_it.call([true, @verbose, Time.now, 'ERR', args].freeze)
+  end
+
+  # -------------------
+  ## write an "err" line with the given message
+  #
+  # @param args  the message to log
+  # @return nil
+  def critical(*args)
+    @log_it.call([true, @verbose, Time.now, 'CRIT', args].freeze)
+  end
+
+  # --------------------
+  ## log an exception
+  #
+  # @param excp        the exception to print
+  # @param max_lines   the maximum lines to print from the backtrace
+  # @return nil
+  def exception(excp, max_lines: 3)
+    now = Time.now
+
+    @log_it.call([true, @verbose, now, 'EXCP', [excp.message]].freeze)
+    @log_it.call([true, @verbose, now, 'EXCP', ['Backtrace:']].freeze)
+    count = 1
+    excp.backtrace.each do |line|
+      @log_it.call([true, @verbose, now, 'EXCP', ['  ', line]].freeze)
+      count += 1
+      # :nocov:
+      # coverage: cannot be done in a UT; minitest adds an unknown number of excp lines
+      break if count > max_lines
+      # :nocov:
+    end
+  end
+
+  private
+
+  # === logging functions
+
+  # -------------------
+  ## write the given line to stdout
+  #
+  # @return nil
+  def _save
+    # if stdout or file is none/closed then nothing to do
+    # if @fp.nil?:  # pragma: no cover
+    #    # coverage: can not be replicated
+    #    # probably redundant to finish but do it anyway
+    #    @finished = true
+    #    return
+
+    count = @queue.size
+    while count.positive?
+      # in some closing/race conditions, the file may be closed in the middle of a loop
+      # note this can be applied to stdout as well.
+      # :nocov:
+      # coverage: cannot be done in a UT
+      break if @fp.closed?
+      # :nocov:
+
+      # get the next tuple: (always_print, verbose, dts, prefix, args)
+      tuple        = @queue.pop
+      always_print = tuple[0]
+      verbose      = tuple[1]
+      dts          = tuple[2]
+      prefix       = tuple[3]
+      args         = tuple[4]
+      count        -= 1
+
+      # uncomment to debug
+      # puts("#{always_print} #{verbose} '#{prefix}'  #{dts}  '#{args}'")
+
+      # not verbose and ok not to print
+      next unless verbose || always_print
+
+      if args[0].nil? && prefix == '.'
+        # dots used to log waiting periods, so okay to call fn
+        _handle_dots
+        next
+      end
+
+      # at this point, not a dot
+
+      # last call was a dot, so reset and print a newline ready for the new log line
+      if @dots != 0
+        @dots = 0
+        @fp.write("\n")
+        @runner_cfg.copy_from(@backup_cfg)
+      end
+
+      # print the full DTS requested by the user
+      if args[0].nil? && prefix.nil?
+        # rare request, so okay to call fn
+        _handle_full_dts(dts)
+        next
+      end
+
+      # print with no prefix or elapsed time
+      if @log_format == LogFormat::NONE
+        line = args.join(' ')
+        @fp.write(line)
+        @fp.write("\n")
+        next
+      end
+
+      # print with the prefix, but no elapsed time
+      if @log_format == LogFormat::PREFIX
+        line = args.join(' ')
+        if prefix.nil?
+          msg = line # raw line
+        else
+          msg = format('%-4s %s', prefix, line)
+        end
+        @fp.write(msg)
+        @fp.write("\n")
+        next
+      end
+
+      # at this point, mode is LogFormat.ELAPSED
+
+      # approximately once an hour, restart the time period
+      elapsed = Time.at(dts - @start_time)
+      if elapsed.to_f > 3600.0
+        # rare, so okay to call fn
+        # display the time at the moment the log line was saved
+        _handle_full_dts(dts)
+
+        # recalc the elapsed time, should be 0
+        # add the small value for round-off issues
+        elapsed = Time.at(dts - @start_time) #  + 0.0001)
+      end
+
+      # print prefix and elapsed time
+      line = args.join(' ')
+
+      # log the line
+      if prefix.nil?
+        msg = line
+      else
+        t_str = _get_elapsed_str(elapsed)
+        msg   = format('%s %-4s %s', t_str, prefix, line)
+      end
+
+      # assume @fp is not closed
+      @fp.write(msg)
+      @fp.write("\n")
+    end
+
+    # uncomment to debug
+    # @fp.close
+
+    # flush lines to stdout/file; protect with except in case
+    begin
+      @fp.flush
+    rescue IOError
+      # coverage: rare case: if stdout/file is closed this will throw an exception
+    end
+  end
+
+  # --------------------
+  ## If past max_dots, print a newline. Then print a dot.
+  #
+  # @return none
+  def _handle_dots
+    if @dots.zero?
+      # save delay and count
+      @backup_cfg.copy_from(@runner_cfg)
+      @runner_cfg.loop_delay  = 0.100
+      @runner_cfg.max_entries = 1
+      @runner_cfg.max_count   = 1
+    end
+
+    if @dots >= @max_dots
+      @fp.write("\n")
+      @dots = 0
+    end
+
+    @fp.write('.')
+    @dots += 1
+  end
+
+  # --------------------
+  ## print full DTS stamp
+  #
+  # @param dts   the dts of the current log line
+  # @return nil
+  def _handle_full_dts(dts)
+    # restart the timer; user wants the full DTS and elapsed is since that absolute time
+    @start_time = dts
+
+    full_dts = format('%-4s %s', 'DTS', dts.strftime('%4Y/%2m/%2d %2H:%2M:%2S.%3N'))
+    full_dts = format('%9s %s', '', full_dts) if @log_format == LogFormat::ELAPSED
+    @fp.write(full_dts)
+    @fp.write("\n")
+  end
+
+  # --------------------
+  ## generate the string of the given elapsed time
+  #
+  # @param elapsed   the elapsed time to format
+  # @return the string ("MM.SS.nnn")
+  def _get_elapsed_str(elapsed)
+    elapsed = Time.at(elapsed) if elapsed.is_a?(Float)
+    elapsed.strftime('%2M:%2S.%3N')
+  end
+
+  # --------------------
+  ## the thread runner
+  # wakes periodically to check if the queue has max_entries or more in it
+  # if so, the lines are written to the file
+  # if not, it sleeps
+  #
+  # @return nil
+  def _runner
+    count = 0
+    until @finished
+      # sleep until:
+      #  - there are enough entries in the queue
+      #  - the max delay is reached
+      if @queue.size < @runner_cfg.max_entries && count < @runner_cfg.max_count
+        count += 1
+        sleep(@runner_cfg.loop_delay)
+        next
+      end
+
+      # write out all the current entries
+      count = 0
+      _save
+    end
+  rescue Interrupt # handle ctrl-c
+    # nothing to do
+  ensure
+    # save any remaining entries
+    _save
+
+    # close the file if necessary
+    if @path && !@fp.nil?
+      @fp.close
+      @fp = nil
+    end
+  end
+end

data/lib/rb_falcon_logger.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'gem_source/logger'

data/lib/version.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+## current version
+VERSION = '0.1.0'

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: rb_falcon_logger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- J. Arrizza
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-01 00:00:00.000000000 Z
+dependencies: []
+description: fast logger with multiple modes and formats
+email: cppgent0@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/gem_source/logger.rb
+- lib/rb_falcon_logger.rb
+- lib/version.rb
+homepage: https://rubygems.org/gems/rb-falcon-logger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://arrizza.com/rb-falcon-logger
+  source_code_uri: https://bitbucket.org/arrizza-public/rb-falcon-logger/src/master
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: fast logger, several modes and formats
+test_files: []