loba 1.2.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 196b8d0b75303a31baa40559f2ece4bb2e53ef288f78822e2436b95926826532
-  data.tar.gz: c06af1fc1450f468abd679b86d35da01464e07d80ea35fc651b9180b1eef8291
+  metadata.gz: 6d53014bd42826b2fee7d16d06ce19a345522ecfd3eb105b5b286f1bd5348e13
+  data.tar.gz: 2d6258dd046d5899469ebdba37606cc4da74b35ae027e87151d237bf83050137
 SHA512:
-  metadata.gz: 5355b4ffd23f1a7d07ff28a7ecd382f5b8b6b0e103b600fa91b96233483bc60588ab108206a2e798f64084509faab69cb15aad99c87089f3a65fbebe0af48e16
-  data.tar.gz: a51c4de30e76e85a45a319b58aa402ea32a2d5b32dd15914f2c409e4261ece721659ce4e4791bb09ac0083398a0766ff622199f1c007f78344370f2d89df92c5
+  metadata.gz: 9c109e14fdbf2d6a6271e92f640cf11a214d92e434938509e8f2ad015a2c6286798b22c1cced8defce4f588394e078e098cc4fa4ef3db5ea07f6a3f21f58141c
+  data.tar.gz: 797fef5afe7e868135070abbd950c6981cdcb63720d0891aa377d62f3086b885c0dfdf9d62a5776ef0034e1ad591f4e05c7b042c73392ce2c85f18a6c8bb4d0f

data/CHANGELOG.md

@@ -1,4 +1,5 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog (1.0.0)](https://keepachangelog.com/en/1.0.0/),
@@ -6,6 +7,31 @@ and, as of version 0.3.0 and later, this project adheres to [Semantic Versioning
 
 ## [Unreleased]
 
+## [2.1.0] - 2024-09-09
+### Added
+- Added `logger` option for accepting a logger to write to instead of default behavior
+- Added `logdev` option to direct logging in non-Rails environments
+- Added `out` option to allow turning off console (`puts`) output
+
+### Changed
+- Changed so `log` option will allow logging in non-Rails environments
+- Changed so `log` option will be defaulted to `true` when `out` options is set to `false`
+- Updated documentation for new and changed options and to improve completeness
+- Refreshed gems and dependencies
+
+## [2.0.0] - 2023-07-07
+### Added
+- `Loba.ts`: `log` option to allow logging to Rails.logger (ignored if unavailable)
+- `Loba.val`: `log` option to allow logging to Rails.logger (ignored if unavailable)
+- SECURITY.md to specify security policy
+
+### Changed
+- Dropped support for Ruby prior to 3.0.6
+- Changed output to always write to `$stdout` (regardless whether Rails is present)
+- Changed to only write to Rails.logger (when present) when `log` option is set to `true`
+- Updated YARD documentation for improved completeness
+- Refreshed gems and dependencies
+
 ## [1.2.1] - 2021-09-05
 ### Added
 - Optional specs for developers to check Loba performance (no surprising issues found)
@@ -13,7 +39,7 @@ and, as of version 0.3.0 and later, this project adheres to [Semantic Versioning
 ### Changed
 - Updated README reference links
 - Updated to support Ruby 2.2.2 as minimum (retreated from 2.5 for broader support)
-- Refactored to seperate stripping quotes from .inspect-generated strings
+- Refactored to separate stripping quotes from .inspect-generated strings
 
 ## [1.2.0] - 2021-09-05 [YANKED]
 
@@ -78,7 +104,9 @@ and, as of version 0.3.0 and later, this project adheres to [Semantic Versioning
 ### Added
 - Initial implementation
 
-[Unreleased]: https://github.com/rdnewman/loba/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/rdnewman/loba/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/rdnewman/loba/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/rdnewman/loba/compare/v1.2.1...v2.0.0
 [1.2.1]: https://github.com/rdnewman/loba/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/rdnewman/loba/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/rdnewman/loba/compare/v1.0.0...v1.1.0

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2021 Richard Newman
+Copyright (c) 2015-2023 Richard Newman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,15 +1,13 @@
+# Loba
+
 [![Gem Version](https://badge.fury.io/rb/loba.svg)](https://badge.fury.io/rb/loba)
-[![Build Status](https://app.travis-ci.com/rdnewman/loba.svg?branch=main)](https://app.travis-ci.com/rdnewman/loba)
+[![Build Status](https://github.com/rdnewman/loba/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/rdnewman/loba/actions?query=branch%3Amain++)
 [![Code Climate](https://codeclimate.com/github/rdnewman/loba/badges/gpa.svg)](https://codeclimate.com/github/rdnewman/loba)
 [![Test Coverage](https://codeclimate.com/github/rdnewman/loba/badges/coverage.svg)](https://codeclimate.com/github/rdnewman/loba/coverage)
-[![Inline docs](http://inch-ci.org/github/rdnewman/loba.svg?branch=master)](http://inch-ci.org/github/rdnewman/loba)
-[![security](https://hakiri.io/github/rdnewman/loba/main.svg)](https://hakiri.io/github/rdnewman/loba/main)
-
-# Loba
 
 ![Loba is "write" in Zulu](readme/zulu.png)
 
-Easy tracing for debugging: handy methods for adding trace lines to output or Rails logs.
+Easy tracing for debugging: handy methods for adding trace lines to output (or logs).
 
 (Installation is pretty much what you'd expect for a gem, but read Environment Notes below first.)
 
@@ -17,22 +15,24 @@ Easy tracing for debugging: handy methods for adding trace lines to output or Ra
 
 There are two kinds of questions I usually want to answer when trying to diagnose code behavior:
 
-1.  Is this spot of code being reached (or is it reached in the order I think it is)?
-1.  What is the value of this variable?
+1. Is this spot of code being reached (or is it reached in the order I think it is)?
+1. What is the value of this variable?
 
 Loba statements are intended to be terse to minimize typing.
 
-Loba statements are intended to be minimally invasive and atomic. They should not have any (much) more impact than regular `puts` or `Rails.logger.debug` statements.
+Loba statements are intended to be minimally invasive and atomic. They should have negligible impact over regular `puts` or logging statements.
 
 Loba statements are expected to be removed when you're done with them. No point in cluttering up production code.
 
-Loba will check for presence of Rails. If it's there, it'll write to `Rails.logger.debug`.  If not, it'll write to STDOUT (i.e., `puts`).  Loba will work equally well with or without Rails.
+Loba will generally always write to `$stdout` (i.e., `puts`). In addition to `$stdout`, Loba can also be made to write to a log (:debug). Writing to `$stdout` can be overridden.
+
+Loba will work equally well with or without Rails. If Rails is present and writing to a log is wanted, it will use the Rails log (e.g., `Rails.logger.debug`).
 
 Loba uses the [rainbow gem](https://rubygems.org/gems/rainbow) to help make trace statements more visible.
 
 ## Usage
 
-My advice is to align Loba statements to the far left in your source code (a la `=begin` or `=end`) so they're easy to see and remove when you're done.
+Aligning Loba statements to the far left in your source code (a la `=begin` or `=end`) will make them easier to see and remove when you're done. You may though find this somewhat annoying to do if your editor auto-indents.
 
 #### Timestamp notices:  `Loba.ts`
 
@@ -40,7 +40,7 @@ Outputs a timestamped notice, useful for quick traces to see the code path and e
 
 For example,
 
-```
+```text
 [TIMESTAMP] #=0002, diff=93.478016, at=1451444972.970602     (in=/home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
 ```
 
@@ -56,7 +56,7 @@ You can read [more detail](readme/ts.md) on this command.
 
 #### Variable or method return inspection:  `Loba.val`
 
-Inserts line to Rails.logger.debug (or to STDOUT if Rails.logger not available) showing value with method and class identification
+Writes line to `$stdout` (or optionally to a log, `logger.debug`) showing value with method and class identification.
 
 ```ruby
 Loba.val :var_sym   # the :var_sym argument is the variable or method name given as a symbol
@@ -64,12 +64,22 @@ Loba.val :var_sym   # the :var_sym argument is the variable or method name given
 
 For example,
 
-```
+```text
 [Target.some_calculation] my_var: 54       (in /home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
 ```
 
 You can read [more detail](readme/val.md) on this command.
 
+#### Output and logging options
+
+There are several options to control where Loba writes its output:
+* `out`: controls whether `puts` to `$stdout` occurs (default: `true`)
+* `log`: controls whether logging occurs (default: `false`)
+* `logger`: controls which logger is used
+* `logdev`: in non-Rails environments, another way to direct where logging occurs
+
+You can read [more detail](readme/log.md) about how to use these options.
+
 #### Snippet example
 
 ```ruby
@@ -92,7 +102,7 @@ HelloWorld.new.hello
 
 Output:
 
-```
+```text
 [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411   (in=/home/usracct/src/lobademo/hello_world.rb:4:in 'initialize'
 [HelloWorld#hello] @x: 42       (in /home/usracct/src/loba/spec/hello_world.rb:9:in `hello')
 Hello, Charlie
@@ -107,14 +117,14 @@ The expectation is that Loba statements are just for development or test trace s
 
 `Loba.ts` and `Loba.val` try to protect against timestamp or value notice requests being accidentally left in the code by checking for the Rails environment Loba is being invoked under. If in production, `Loba.ts` and `Loba.val` will normally just return immediately without attempting to render anything to help minimize any impact on production code.
 
-However, that behavior can be overridden by using the options hash with `:production => true` as an additional last argument to output a notice even when in the production environment.  In general, this should be avoided.
+However, that behavior can be overridden by using the option `production: true` as an additional argument to output a notice even when in the production environment. Note also behavior of the `log` option, which defaults to `false` (introduced in v2.0.0). In general, enabling in production should not be done, but we're consenting adults.
 
-WARNING: this gem depends on the [binding_of_caller gem](https://rubygems.org/gems/binding_of_caller) -- use `:production => true` with their warning in mind:
+WARNING: this gem depends on the [binding_of_caller gem](https://rubygems.org/gems/binding_of_caller) -- use `production: true` with their warning in mind:
 > **Recommended for use only in debugging situations. Do not use this in production apps.**
 
-These considerations also have an impact on how you install the Loba gem when using `bundler`. If you only install the gem for :development and :test, then any Loba statements left in the code when it goes to production will cause an error because the statements wouldn't be recognized. That's usually a Good Thing, if you never want them left in.
+These considerations also have an impact on how you install the Loba gem when using `bundler`. If you only install the gem for `:development` and `:test`, then any Loba statements left in the code when it goes to production will cause an error because the statements wouldn't be recognized. That can be a good thing if you never want them left in.
 
-If you simply install the gem for all environments, then Loba will be available in production, but you may not notice as easily if some Loba calls are unintentionally left in. Of course, if you want those statements to work in production, then you should install the gem for all environments.
+If you simply install the gem for all environments, then Loba will be available in production, but you may not notice as easily if some Loba calls are unintentionally left in. Of course, if you want Loba statements to possibly work in production, then you should install the gem for all environments.
 
 The following is the code example snippet but always logging even in Rails production environments:
 
@@ -122,12 +132,12 @@ The following is the code example snippet but always logging even in Rails produ
 class HelloWorld
   def initialize
     @x = 42
-Loba.ts production: true
+Loba.ts log: true, production: true
     @y = "Charlie"
   end
 
   def hello
-Loba.val :@x, production: true
+Loba.val :@x, log: true, production: true
     puts "Hello, #{@y}" if @x == 42
 Loba.ts true
   end
@@ -139,11 +149,10 @@ HelloWorld.new.hello
 
 See above Environment Notes if using with Rails.
 
-
 Install as below to be generally available (recommended to restrict to only local use):
 
 ```bash
-$ gem install loba
+gem install loba
 ```
 
 To bundle, add this line to your application's Gemfile:
@@ -160,18 +169,19 @@ or for all environments (for example, if `production: true` used):
 gem 'loba', require: false
 ```
 
-
 And then execute:
 
 ```bash
-$ bundle
+bundle install
 ```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Changelog
 

data/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+Loba is intended for diagnostic use in development and test environments.
+
+Loba assumes consenting adults: it provides an explicit mechanism for temporary use in
+production environments. Use in production environments is NOT recommended
+and should be treated as a security vulnerability. Please see the README.md for
+additional information.
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.1.x   | :white_check_mark: |
+| 2.0.x   | :white_check_mark: |
+| < 2.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Please report suspected security vulnerabilities via
+[Github issues][def].
+For urgent concerns, write to
+**[richard@newmanworks.com](mailto:richard@newmanworks.com)**.
+
+[def]: https://github.com/rdnewman/loba/issues

data/lib/loba/error.rb

@@ -0,0 +1,18 @@
+module Loba
+  # Errors raised by Loba are subclasses of +Loba::Error+.
+  # Rescue this class to rescue any Loba-specific errors.
+  # @api private
+  class Error < StandardError; end
+
+  # Error raised with an invalid logdev is specified
+  # @api private
+  class InvalidLogdevOptionError < Error; end
+
+  # Error raised with an invalid logger is specified
+  # @api private
+  class InvalidLoggerOptionError < Error; end
+
+  # Error raised with an invalid target for #puts is specified
+  # @api private
+  class InvalidOutOptionError < Error; end
+end

data/lib/loba/internal/platform/formatter.rb

@@ -0,0 +1,43 @@
+require 'logger'
+require 'English'
+
+module Loba
+  module Internal
+    module Platform
+      # Custom logging formatter (for when Rails is not involved)
+      class Formatter
+        # Formats supplied message to write to logger.
+        #
+        # This formatter ignores +severity+, +time+, and +progname+ because it enforces
+        # that Loba messages are written out to the log without additional ornamentation.
+        #
+        # @param message [String] Loba content to write out
+        # @return [String] message formatted for writing to log
+        def call(_severity, _time, _progname, message)
+          "#{format(message)}#{$INPUT_RECORD_SEPARATOR}"
+        end
+
+        private
+
+        def format(message)
+          case message
+          when ::String
+            message
+          when ::Exception
+            format_exception(message)
+          else
+            message.inspect
+          end
+        end
+
+        def format_exception(err)
+          backtrace = err.backtrace
+          result = "#{err.message} (#{err.class})"
+          return result if backtrace.to_s.empty?
+
+          result + "\n#{backtrace}"
+        end
+      end
+    end
+  end
+end

data/lib/loba/internal/platform/within_rails.rb

@@ -0,0 +1,22 @@
+module Loba
+  module Internal
+    module Platform
+      # Internal module for considering Rails
+      module WithinRails
+        # Determines if Rails has its logger defined (generally +true+)
+        # @return [boolean] +true+ if +Rails.logger+ is defined
+        def logger?
+          Internal.boolean_cast(defined?(Rails)) && Internal.boolean_cast(Rails.logger)
+        end
+        module_function :logger?
+
+        # Determines if Rails is running in a production environment
+        # @return [boolean] +true+ if +Rails.env+ is +:production+
+        def production?
+          Internal.boolean_cast(defined?(Rails)) && Rails.env.production?
+        end
+        module_function :production?
+      end
+    end
+  end
+end

data/lib/loba/internal/platform.rb

@@ -1,31 +1,25 @@
+require_relative 'platform/formatter'
+require_relative 'platform/within_rails'
+
 module Loba
   module Internal
-    # Internal class for managing logging across Rails and non-Rails applications
-    class Platform
+    # Internal module for managing output and logging across Rails and non-Rails applications
+    module Platform
       class << self
-        # Returns true if Rails appears to be available
-        def rails?
-          defined?(Rails) ? true : false
-        end
-
-        # Returns true if logging is to be allowed
-        def logging_ok?(force_true = false)
-          return true if force_true
-          return true unless rails?
-
-          begin
-            !Rails.env.production?
-          rescue StandardError
-            true # let it attempt to log anyway
-          end
-        end
+        # Provides mechanism for appropriate console output and logging.
+        #
+        # @note To avoid doubled output, if a non-Rails logger is to be logged to and +logdev+ is
+        #   set to +$stdout+, then output will be suppressed (i.e., +settings.out+ is +false+).
+        #   Doubled output can still occur; in that case, explicitly use +out: false+.
+        #
+        # @param settings [::Loba::Internal::Settings] settings for output control
+        # @return [lambda {|message| ...}] procedure for presenting output. Takes one argument,
+        #   +message+ (String), for the output to be written
+        def writer(settings:)
+          lambda do |message|
+            puts(message) if settings.out?
 
-        # Returns a logging mechanism appropriate for the application
-        def logger
-          if rails? && Rails.logger.present?
-            ->(arg) { Rails.logger.debug arg }
-          else
-            ->(arg) { puts arg }
+            settings.logger.debug { message } if settings.log?
           end
         end
       end

data/lib/loba/internal/settings.rb

@@ -0,0 +1,143 @@
+module Loba
+  module Internal
+    # Internal class for tracking output and logging settings based on supplied options
+    class Settings
+      # @return [boolean] whether logging is performed
+      attr_reader :log
+      alias log? log
+
+      # @return [Logger] +::Logger+ used for logging; may be +nil+ if not logging
+      attr_reader :logger
+
+      # @return [nil, String, IO, File::NULL]
+      #   any custom (overridden) logging device being written to; +nil+ if none specified
+      attr_reader :logdev
+
+      # @return [boolean] +false+ if console output is suppressed; otherwise, +true+
+      attr_reader :out
+      alias out? out
+
+      # @return [boolean]
+      #   +true+ if Loba is enabled even within a Rails production environment; otherwise, +false+
+      attr_reader :production
+      alias production? production
+
+      # @param log [boolean]
+      #   set to +false+ if no logging is ever wanted
+      #   (default when not in Rails and +logger+ is nil);
+      #   set to +true+ if logging is always wanted (default when in Rails or
+      #   when +logger+ is set or +out+ is false);
+      # @param logger [Logger] override logging with specified Ruby Logger
+      # @param logdev [nil, String, IO, File::NULL]
+      #   custom log device to use (when not in Rails); ignored if +logger+ is set;
+      #   must be filename or IO object
+      # @param out [boolean]
+      #   set to +false+ if console output is to be suppressed
+      # @param production [boolean]
+      #   set to +true+ if Loba is to work even within a Rails production environment
+      # @note To avoid doubled output, if a non-Rails logger is to be logged to and +logdev+ is
+      #   set to +$stdout+, then output will be suppressed (i.e., +settings.out+ is +false+).
+      #   Doubled output can still occur; in that case, explicitly use +out: false+.
+      # @raise [InvalidLoggerOptionError] when an invalid logger is specified
+      # @raise [InvalidLogdevOptionError] when an invalid logdev is specified
+      def initialize(log: nil, logger: nil, logdev: nil, out: true, production: false)
+        @raw_log_argument = log
+        @log = validated_log(log)
+        @out = false
+        @production = validated_production(production)
+
+        return unless enabled?
+
+        @logger = validated_logger(logger)
+        @logdev = validated_logdev(logdev)
+        @out = validated_out(out)
+
+        configure_logging
+      end
+
+      # @return [Boolean] +true+ if Loba is used; otherwise, +false+
+      def enabled?
+        production? || !Internal::Platform::WithinRails.production?
+      end
+
+      # @return [Boolean] +true+ if Loba is skipped (because of a production environment);
+      #   otherwise, +false+
+      def disabled?
+        !enabled?
+      end
+
+      private
+
+      attr_reader :raw_log_argument
+
+      def validated_log(candidate_log)
+        Internal.boolean_cast(candidate_log)
+      end
+
+      def validated_logger(candidate_logger)
+        return if candidate_logger.nil?
+        raise InvalidLoggerOptionError unless candidate_logger.is_a?(::Logger)
+
+        @log = true unless log_explicit?
+
+        candidate_logger
+      end
+
+      def validated_logdev(candidate_logdev)
+        case candidate_logdev
+        when nil, String, IO, StringIO, File::NULL
+          candidate_logdev
+        else
+          raise InvalidLogdevOptionError
+        end
+      end
+
+      def validated_out(candidate_out)
+        will_output = !logging_to_stdout? && out_param_cast(candidate_out)
+
+        @log = true unless will_output || log_explicit?
+
+        will_output
+      end
+
+      def validated_production(candidate_production)
+        Internal.boolean_cast(candidate_production)
+      end
+
+      def log_explicit?
+        !raw_log_argument.nil?
+      end
+
+      def logging_to_stdout?
+        log? && ((logdev == $stdout) || (logdev == '$stdout'))
+      end
+
+      def configure_logging
+        @log &&= enabled?
+
+        @logger ||= default_logger if log?
+      end
+
+      def default_logger
+        if Internal::Platform::WithinRails.logger?
+          ::Rails.logger
+        else
+          ::Logger.new((logdev || $stdout), formatter: Internal::Platform::Formatter.new)
+        end
+      end
+
+      def out_param_cast(value)
+        case value
+        when true, TrueClass
+          true
+        when nil, false, FalseClass, File::NULL
+          false
+        when String, Integer, IO, StringIO
+          Internal.boolean_cast(value)
+        else
+          raise InvalidOutOptionError
+        end
+      end
+    end
+  end
+end

data/lib/loba/internal/time_keeper.rb

@@ -15,6 +15,11 @@ module Loba
         reset!
       end
 
+      # Increments timestamping, including attributes +timenum+ and +timewas+
+      # @return [Hash] timestamp details
+      #   * :number => [Integer] incremented count of pings so far (attribute +timenum+)
+      #   * :now => [Time] current date and time
+      #   * :change => [Float] difference in seconds from any previous ping or reset
       def ping
         @timenum += 1
         now = Time.now
@@ -24,9 +29,13 @@ module Loba
         { number: @timenum, now: now, change: change }
       end
 
+      # Resets timestamping
+      # @return [NilClass] nil
       def reset!
         @timewas = Time.now
         @timenum = 0
+
+        nil
       end
     end
   end

data/lib/loba/internal/value/value_helper.rb

@@ -30,7 +30,7 @@ module Loba
         # @param argument [Symbol, Object] the value or variable for which information is
         #   to be retrieved
         # @param inspect [Boolean] when true, force #inspect to be called against
-        #   `argument` when evaluating
+        #   +argument+ when evaluating
         # @param depth [Integer] depth in call stack to start evaluation from
         # @return [String] value representation of argument for display
         def value(argument:, inspect: true, depth: 0)
@@ -46,7 +46,7 @@ module Loba
 
         # Builds a label for display based on the argument when instantiated.
         # If the argument (when instantiated) is not a symbol, it may not be possible
-        # to infer a label; in that case, '[unknown value]' is returned.
+        # to infer a label; in that case, "[unknown value]"" is returned.
         #
         # @param argument [Symbol, Object] the value or variable for which information is
         #   to be retrieved
@@ -54,8 +54,8 @@ module Loba
         #     and a label can be inferred.
         #   * If any other type, it is assumed to be a literal value to
         #     and a label should be supplied when instantiated.
-        # @param label [String] when provided, an explicit label to use; will override any
-        #   possible inferred label
+        # @param explicit_label [String] when provided, an explicit label to use; will
+        #   override any possible inferred label
         #
         # @return [String] label
         def label(argument:, explicit_label: nil)
@@ -73,8 +73,8 @@ module Loba
         # Evaluate an arguments value from where it's bound.
         # @param argument [Symbol, Object] the value or variable for which information is
         #   to be retrieved
-        # @param inspect [Boolean] when true, force #inspect to be called against
-        #   `argument` when evaluating
+        # @param inspect [Boolean] when true, force +#inspect+ to be called against
+        #   +argument+ when evaluating
         # @param depth [Integer] depth in call stack to start evaluation from
         # @return [Object] value of the argument when Loba was invoked
         def evaluate(argument:, inspect: true, depth: 0)

data/lib/loba/internal/value.rb

@@ -16,8 +16,8 @@ module Loba
       #     and a label should be supplied when instantiated.
       # @param label [String] when provided, an explicit label to use; will override any
       #   possible inferred label
-      # @param inspect [Boolean] when true, force #inspect to be called against
-      #   `argument` when evaluating
+      # @param inspect [Boolean] when true, force +#inspect+ to be called against
+      #   +argument+ when evaluating
       # @param depth_offset [Integer] depth in call stack to start evaluation from
       #
       # @return [Hash] various detail about the value being analyzed
@@ -25,7 +25,7 @@ module Loba
       #   * :line => [String] code line reference
       #   * :value => [String] value of argument (if nil, '-nil-' is returned)
       #   * :label => [String] label, ending with ":"
-      #     (if not possible to infer, '[unknown value]' is returned)
+      #     (if not possible to infer, "[unknown value]" is returned)
       def phrases(argument:, label: nil, inspect: true, depth_offset: 0)
         depth = depth_offset.nil? ? 0 : depth_offset.to_i
         {

data/lib/loba/internal.rb

@@ -1,13 +1,15 @@
 require_relative 'internal/platform'
+require_relative 'internal/settings'
 require_relative 'internal/time_keeper'
 require_relative 'internal/value'
 
 module Loba
+  # Internal functionality support
   # @api private
   module Internal
     # Remove wrapping quotes on a string (produced by .inspect)
     #
-    # @param argument [String] the string (assumed to be produced from calling .inspect)
+    # @param content [String] the string (assumed to be produced from calling .inspect)
     #   to remove quotes (") that wrap a string
     #
     # @return [String, Object]
@@ -23,5 +25,31 @@ module Loba
       content[1...-1]
     end
     module_function :unquote
+
+    # Canonical set of values interpreted to be false.
+    # Adapted from Rails's ActiveModule::Type::Boolean (2024)
+    FALSE_VALUES = [
+      false, 0, nil, '',
+      '0', :'0',
+      'f', :f,
+      'F', :F,
+      'false', :false, # rubocop:disable Lint/BooleanSymbol
+      'FALSE', :FALSE,
+      'off', :off,
+      'OFF', :OFF
+    ].to_set.freeze
+    private_constant :FALSE_VALUES
+
+    # Casts any value to true or false (boolean)
+    #
+    # @param value [Object] the value to cast
+    #
+    # @return [true, false]
+    def boolean_cast(value)
+      return false if value.respond_to?(:empty) && value.empty?
+
+      !FALSE_VALUES.include?(value)
+    end
+    module_function :boolean_cast
   end
 end

data/lib/loba/timestamp.rb

@@ -0,0 +1,80 @@
+module Loba # rubocop:disable Style/Documentation
+  # Outputs a timestamped notice, useful for quick traces to see the code path.
+  # Also does a simple elapsed time check since the previous timestamp notice to
+  # help with quick, minimalist profiling.
+  # @param production [boolean]
+  #   set to +true+ if this timestamp notice is to be recorded
+  #   when running in a Rails production environment
+  # @param log [boolean]
+  #   set to +false+ if no logging is ever wanted
+  #   (default when not in Rails and +logger+ is nil);
+  #   set to +true+ if logging is always wanted (default when in Rails or
+  #   when +logger+ is set or +out+ is false);
+  # @param logger [Logger] override logging with specified Ruby Logger
+  # @param logdev [nil, String, IO, File::NULL]
+  #   custom log device to use (when not in Rails); ignored if +logger+ is set;
+  #   must be filename or IO object
+  # @param out [boolean]
+  #   set to +false+ if console output is to be suppressed
+  # @return [NilClass] nil
+  # @example Basic use
+  #   def hello
+  #     Loba.timestamp
+  #   end
+  #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
+  # @example Forced to output when in production environment
+  #   def hello
+  #     Loba.ts production: true # Loba.ts is a shorthand alias for Loba.timestamp
+  #   end
+  #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
+  # @example Forced to output to log in addition to $stdout
+  #   def hello
+  #     Loba.timestamp log: true
+  #   end
+  #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
+  # @note To avoid doubled output, if a non-Rails logger is to be logged to and +logdev+ is
+  #   set to +$stdout+, then output will be suppressed (i.e., +settings.out+ is +false+).
+  #   Doubled output can still occur; in that case, explicitly use +out: false+.
+  def timestamp( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    production: false,
+    log: false,
+    logger: nil,
+    logdev: nil,
+    out: true
+  )
+    settings = Internal::Settings.new(
+      log: log, logger: logger, logdev: logdev, out: out, production: production
+    )
+
+    return unless settings.enabled?
+
+    # NOTE: while tempting, memoizing loba_logger can lead to surprises if
+    #   Rails presence isn't constant
+    writer = Internal::Platform.writer(settings: settings)
+
+    begin
+      stats = Internal::TimeKeeper.instance.ping
+      writer.call(
+        # 60: light_black / grey
+        "#{Rainbow('[TIMESTAMP]').black.bg(60)}" \
+        "#{Rainbow(' #=').yellow.bg(:default)}" \
+        "#{format('%04d', stats[:number])}" \
+        "#{Rainbow(', diff=').yellow}" \
+        "#{format('%.6f', stats[:change])}" \
+        "#{Rainbow(', at=').yellow}" \
+        "#{format('%.6f', stats[:now].round(6).to_f)}" \
+        "#{Rainbow("    \t(in #{caller(1..1).first})").color(60)}" # warning: nested interpolation
+      )
+    rescue StandardError => e
+      writer.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
+    end
+
+    nil
+  end
+  module_function :timestamp
+
+  # Shorthand alias for Loba.timestamp.
+  # @!method ts(production: false, log: false, logger: nil, logdev: nil, out: true)
+  alias ts timestamp
+  module_function :ts
+end

data/lib/loba/value.rb

@@ -0,0 +1,104 @@
+module Loba # rubocop:disable Style/Documentation
+  # Outputs a value notice showing value of provided argument including method and
+  # class identification.
+  # @param argument [various] (required) the value to be evaluated and shown; if given as
+  #   a +Symbol+, a label based on the argument will proceed the value the argument refers to
+  # @param label [String] explicit label to be used instead of attempting
+  #   to infer from the argument; default is to attempt to infer a label from the argument
+  # @param inspect [boolean] +true+ if this value notice is to use +#inspect+ against the
+  #   content being evaluated; otherwise, +false+
+  # @param production [boolean]
+  #   set to +true+ if the value notice is to be recorded
+  #   when running in a Rails production environment
+  # @param log [boolean]
+  #   set to +false+ if no logging is ever wanted
+  #   (default when not in Rails and +logger+ is nil);
+  #   set to +true+ if logging is always wanted (default when in Rails or
+  #   when +logger+ is set or +out+ is false);
+  # @param logger [Logger] override logging with specified Ruby Logger
+  # @param logdev [nil, String, IO, File::NULL]
+  #   custom log device to use (when not in Rails); ignored if +logger+ is set;
+  #   must be filename or IO object
+  # @param out [boolean]
+  #   set to +false+ if console output is to be suppressed
+  # @return [NilClass] nil
+  # @example Using Symbol as argument
+  #   class HelloWorld
+  #     def hello(name)
+  #   Loba.value :name # putting Loba statement to far left helps remember to remove later
+  #       puts "Hello, #{name}!"
+  #     end
+  #   end
+  #   HelloWorld.new.hello("Charlie")
+  #   #=> [HelloWorld#hello] name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
+  #   #=> Hello, Charlie!
+  # @example Using non-Symbol as argument
+  #   class HelloWorld
+  #     def hello(name)
+  #   Loba.val name # Loba.val is a shorthand alias for Loba.value
+  #       puts "Hello, #{name}!"
+  #     end
+  #   end
+  #   HelloWorld.new.hello("Charlie")
+  #   #=> [HelloWorld#hello] Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
+  #   #=> Hello, Charlie!
+  # @example Using non-Symbol as argument with a label
+  #   class HelloWorld
+  #     def hello(name)
+  #   Loba.value name, "Name:"
+  #       puts "Hello, #{name}!"
+  #     end
+  #   end
+  #   HelloWorld.new.hello("Charlie")
+  #   #=> [HelloWorld#hello] Name: Charlie        (at /path/to/file/hello_world.rb:3:in 'hello')
+  #   #=> Hello, Charlie!
+  # @note To avoid doubled output, if a non-Rails logger is to be logged to and +logdev+ is
+  #   set to +$stdout+, then output will be suppressed (i.e., +settings.out+ is +false+).
+  #   Doubled output can still occur; in that case, explicitly use +out: false+.
+  def value( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+    argument,
+    label: nil,
+    inspect: true,
+    production: false,
+    log: false,
+    logger: nil,
+    logdev: nil,
+    out: true
+  )
+    settings = Internal::Settings.new(
+      log: log, logger: logger, logdev: logdev, out: out, production: production
+    )
+
+    return unless settings.enabled?
+
+    text = Internal::Value.phrases(
+      argument: (argument.nil? ? :nil : argument),
+      label: label,
+      inspect: inspect,
+      depth_offset: 1
+    )
+
+    Internal::Platform.writer(settings: settings).call(
+      # NOTE: while tempting, memoizing Internal::Platform.logger can lead to surprises
+      #   if Rails presence isn't constant
+      #
+      # warning: nested interpolation below (slight help to performance)
+      # 60: light_black
+      # 62: light_green
+      "#{Rainbow("#{text[:tag]} ").green.bg(:default)}" \
+      "#{Rainbow("#{text[:label]} ").color(62)}" \
+      "#{text[:value]}" \
+      "#{Rainbow("    \t(in #{text[:line]})").color(60)}"
+    )
+
+    nil
+  end
+  module_function :value
+
+  # rubocop:disable Layout/LineLength
+  # Shorthand alias for Loba.value.
+  # @!method val(argument, label: nil, inspect: true, production: false, log: false, logger: nil, logdev:nil, out: true)
+  alias val value
+  module_function :val
+  # rubocop:enable Layout/LineLength
+end

data/lib/loba/version.rb

@@ -1,3 +1,4 @@
 module Loba
-  VERSION = '1.2.1'.freeze
+  # Semantic version number
+  VERSION = '2.1.0'.freeze
 end

data/lib/loba.rb

@@ -1,127 +1,14 @@
 require 'loba/version'
+require 'loba/error'
 require 'loba/internal'
 
 require 'binding_of_caller'
 require 'rainbow'
 
+require 'loba/timestamp'
+require 'loba/value'
+
 # Loba module for quick tracing of Ruby and Rails.
-# If a Rails application, will use Rails.logger.debug.
-# If not a Rails application, will use STDOUT.
+# Will write to $stdout (generally) and, optionally, a log.
 module Loba
-  # Outputs a timestamped notice, useful for quick traces to see the code path.
-  # Also does a simple elapsed time check since the previous timestamp notice to
-  # help with quick, minimalist profiling.
-  # @param production [Boolean] set to true if this timestamp notice is
-  #   to be recorded when running in :production environment
-  # @return [NilClass] nil
-  # @example Basic use
-  #   def hello
-  #     Loba.timestamp
-  #   end
-  #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
-  # @example Forced to output when in production environment
-  #   def hello
-  #     Loba.ts production: true # Loba.ts is a shorthand alias for Loba.timestamp
-  #   end
-  #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
-  def timestamp(production: false)
-    return unless Internal::Platform.logging_ok?(production)
-
-    # produce timestamp notice
-    @loba_logger ||= Internal::Platform.logger
-
-    begin
-      stats = Internal::TimeKeeper.instance.ping
-      @loba_logger.call(
-        # 60: light_black / grey
-        "#{Rainbow('[TIMESTAMP]').black.bg(60)}" \
-        "#{Rainbow(' #=').yellow.bg(:default)}" \
-        "#{format('%04d', stats[:number])}" \
-        "#{Rainbow(', diff=').yellow}" \
-        "#{format('%.6f', stats[:change])}" \
-        "#{Rainbow(', at=').yellow}" \
-        "#{format('%.6f', stats[:now].round(6).to_f)}" \
-        "#{Rainbow("    \t(in #{caller(1..1).first})").color(60)}" # warning: nested interpolation
-      )
-    rescue StandardError => e
-      @loba_logger.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
-    end
-
-    nil
-  end
-  module_function :timestamp
-
-  # Shorthand alias for Loba.timestamp.
-  alias ts timestamp
-  module_function :ts
-
-  # Outputs a value notice showing value of provided argument including method and
-  # class identification.
-  # @param argument [various] (required) the value to be evaluated and shown; if given as
-  #   a Symbol, a label based on the argument will proceed the value the argument refers to
-  # @param label [String] explicit label to be used instead of attempting
-  #   to infer from the argument; default is to attempt to infer a label from the argument
-  # @param inspect [Boolean] true if this value notice is to use #inspect against the
-  #   content being evaluated; otherwise, false
-  # @param production [Boolean] set to true if this timestamp notice is
-  #   to be recorded when running in :production environment
-  # @return [NilClass] nil
-  # @example Using Symbol as argument
-  #   class HelloWorld
-  #     def hello(name)
-  #   Loba.value :name # putting Loba statement to far left helps remember to remove later
-  #       puts "Hello, #{name}!"
-  #     end
-  #   end
-  #   HelloWorld.new.hello("Charlie")
-  #   #=> [HelloWorld#hello] name: Charlie        (at /path/to/file/hello_world.rb:3:in `hello')
-  #   #=> Hello, Charlie!
-  # @example Using non-Symbol as argument
-  #   class HelloWorld
-  #     def hello(name)
-  #   Loba.val name # Loba.val is a shorthand alias for Loba.value
-  #       puts "Hello, #{name}!"
-  #     end
-  #   end
-  #   HelloWorld.new.hello("Charlie")
-  #   #=> [HelloWorld#hello] Charlie        (at /path/to/file/hello_world.rb:3:in `hello')
-  #   #=> Hello, Charlie!
-  # @example Using non-Symbol as argument with a label
-  #   class HelloWorld
-  #     def hello(name)
-  #   Loba.value name, "Name:"
-  #       puts "Hello, #{name}!"
-  #     end
-  #   end
-  #   HelloWorld.new.hello("Charlie")
-  #   #=> [HelloWorld#hello] Name: Charlie        (at /path/to/file/hello_world.rb:3:in `hello')
-  #   #=> Hello, Charlie!
-  def value(argument, label: nil, inspect: true, production: false)
-    return nil unless Internal::Platform.logging_ok?(production)
-
-    @loba_logger ||= Internal::Platform.logger
-
-    text = Internal::Value.phrases(
-      argument: (argument.nil? ? :nil : argument),
-      label: label,
-      inspect: inspect,
-      depth_offset: 1
-    )
-    @loba_logger.call(
-      # warning: nested interpolation below (slight help to performance)
-      # 60: light_black
-      # 62: light_green
-      "#{Rainbow("#{text[:tag]} ").green.bg(:default)}" \
-      "#{Rainbow("#{text[:label]} ").color(62)}" \
-      "#{text[:value]}" \
-      "#{Rainbow("    \t(in #{text[:line]})").color(60)}"
-    )
-
-    nil
-  end
-  module_function :value
-
-  # Shorthand alias for Loba.value.
-  alias val value
-  module_function :val
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: loba
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Richard Newman
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-05 00:00:00.000000000 Z
+date: 2024-09-09 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
 description: Handy methods for adding trace lines to output or Rails logs.
 email:
 - richard@newmanworks.com
@@ -63,12 +49,19 @@ files:
 - CODE_OF_CONDUCT.md
 - LICENSE
 - README.md
+- SECURITY.md
 - lib/loba.rb
+- lib/loba/error.rb
 - lib/loba/internal.rb
 - lib/loba/internal/platform.rb
+- lib/loba/internal/platform/formatter.rb
+- lib/loba/internal/platform/within_rails.rb
+- lib/loba/internal/settings.rb
 - lib/loba/internal/time_keeper.rb
 - lib/loba/internal/value.rb
 - lib/loba/internal/value/value_helper.rb
+- lib/loba/timestamp.rb
+- lib/loba/value.rb
 - lib/loba/version.rb
 homepage: https://github.com/rdnewman/loba
 licenses:
@@ -78,7 +71,8 @@ metadata:
   bug_tracker_uri: https://github.com/rdnewman/loba/issues
   changelog_uri: https://github.com/rdnewman/loba/blob/main/CHANGELOG.md
   documentation_uri: https://www.rubydoc.info/gems/loba
-post_install_message: 
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -86,15 +80,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.2
+      version: 3.0.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.23
-signing_key: 
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: 'Loba: Easy tracing for debugging.'
 test_files: []