loba 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 196b8d0b75303a31baa40559f2ece4bb2e53ef288f78822e2436b95926826532
-  data.tar.gz: c06af1fc1450f468abd679b86d35da01464e07d80ea35fc651b9180b1eef8291
+  metadata.gz: fd37694b2e7fc3a573237e959410b0bb388e4b4873f16ebb75724c8b3c2db359
+  data.tar.gz: c26f5ea9b333bf0bef43d19f0cd139aebe88420eb800daa344b363361fc05a05
 SHA512:
-  metadata.gz: 5355b4ffd23f1a7d07ff28a7ecd382f5b8b6b0e103b600fa91b96233483bc60588ab108206a2e798f64084509faab69cb15aad99c87089f3a65fbebe0af48e16
-  data.tar.gz: a51c4de30e76e85a45a319b58aa402ea32a2d5b32dd15914f2c409e4261ece721659ce4e4791bb09ac0083398a0766ff622199f1c007f78344370f2d89df92c5
+  metadata.gz: 5529034ea281db641c3105b0aba812de2b7d05933816f690a9f3cade786b9a6b7c42004ce5567ec767902538f817a17fb976c8a0f20e72ce9842f8ef53b7c4d3
+  data.tar.gz: cfcff516d957181281939ed46af92027d2c673dd6b9035a421fda4c04118c8e7d47300727cbab8230b6fef93e8ec23c368f689244e843bb87dccf20e85791b85

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,19 @@ and, as of version 0.3.0 and later, this project adheres to [Semantic Versioning
 
 ## [Unreleased]
 
+## [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 +27,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 +92,8 @@ 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.0.0...HEAD
+[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/README.md

@@ -1,11 +1,9 @@
+# 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)
 
@@ -17,8 +15,8 @@ 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.
 
@@ -26,7 +24,9 @@ Loba statements are intended to be minimally invasive and atomic. They should no
 
 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 always write to STDOUT (i.e., `puts`).
+
+Loba will work equally well with or without Rails. If Rails is present, in addition to STDOUT, Loba will also always write to `Rails.logger.debug`.
 
 Loba uses the [rainbow gem](https://rubygems.org/gems/rainbow) to help make trace statements more visible.
 
@@ -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')
 ```
 
@@ -64,7 +64,7 @@ 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')
 ```
 
@@ -92,7 +92,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,7 +107,7 @@ 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 options hash with `:production => true` as an additional last 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 be avoided. 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:
 > **Recommended for use only in debugging situations. Do not use this in production apps.**
@@ -139,11 +139,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 +159,19 @@ or for all environments (for example, if `production: true` used):
 gem 'loba', require: false
 ```
 
-
 And then execute:
 
 ```bash
-$ bundle
+bundle
 ```
 
 ## 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,24 @@
+# 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.x.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/internal/platform.rb

@@ -3,12 +3,14 @@ module Loba
     # Internal class for managing logging across Rails and non-Rails applications
     class Platform
       class << self
-        # Returns true if Rails appears to be available
+        # Checks if Rails is present
+        # @return [Boolean] true if Rails appears to be available; otherwise, false
         def rails?
           defined?(Rails) ? true : false
         end
 
-        # Returns true if logging is to be allowed
+        # Checks if logging output is permitted.
+        # @return [Boolean] true if logging is to be allowed; otherwise, false
         def logging_ok?(force_true = false)
           return true if force_true
           return true unless rails?
@@ -20,12 +22,23 @@ module Loba
           end
         end
 
-        # Returns a logging mechanism appropriate for the application
+        # Provides logging mechanism appropriate in the application.
+        #
+        # Returned lambda takes 2 arguments:
+        #   * arg [String] value to be output (and potentially logged)
+        #   * force_log [Boolean] when false (default), never logs to Rails.logger;
+        #       when true, logs to Rails.logger if present
+        # @return [Lambda] procedure for logging output
         def logger
           if rails? && Rails.logger.present?
-            ->(arg) { Rails.logger.debug arg }
+            lambda do |arg, force_log = false|
+              puts arg
+              return unless force_log
+
+              Rails.logger.debug arg
+            end
           else
-            ->(arg) { puts arg }
+            ->(arg, _force_log = false) { puts arg }
           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

@@ -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)

data/lib/loba/internal.rb

@@ -3,11 +3,12 @@ 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]

data/lib/loba/version.rb

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

data/lib/loba.rb

@@ -13,6 +13,8 @@ module Loba
   # help with quick, minimalist profiling.
   # @param production [Boolean] set to true if this timestamp notice is
   #   to be recorded when running in :production environment
+  # @param log [Boolean] when false, will not write to Rails.logger if present;
+  #   when true, will write to Rails.logger if present
   # @return [NilClass] nil
   # @example Basic use
   #   def hello
@@ -24,15 +26,21 @@ module Loba
   #     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)
+  # @example Forced to output to log (if Rails.logger present) 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'
+  def timestamp(production: false, log: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     return unless Internal::Platform.logging_ok?(production)
 
-    # produce timestamp notice
-    @loba_logger ||= Internal::Platform.logger
+    # NOTE: while tempting, memoizing loba_logger can lead to surprises if
+    #   Rails presence isn't constant
+    loba_logger = Internal::Platform.logger
 
     begin
       stats = Internal::TimeKeeper.instance.ping
-      @loba_logger.call(
+      loba_logger.call(
         # 60: light_black / grey
         "#{Rainbow('[TIMESTAMP]').black.bg(60)}" \
         "#{Rainbow(' #=').yellow.bg(:default)}" \
@@ -41,10 +49,11 @@ module Loba
         "#{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
+        "#{Rainbow("    \t(in #{caller(1..1).first})").color(60)}", # warning: nested interpolation
+        !!log
       )
     rescue StandardError => e
-      @loba_logger.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
+      loba_logger.call Rainbow("[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}").red
     end
 
     nil
@@ -52,6 +61,7 @@ module Loba
   module_function :timestamp
 
   # Shorthand alias for Loba.timestamp.
+  # @!method ts(production: false, log: false)
   alias ts timestamp
   module_function :ts
 
@@ -65,6 +75,8 @@ module Loba
   #   content being evaluated; otherwise, false
   # @param production [Boolean] set to true if this timestamp notice is
   #   to be recorded when running in :production environment
+  # @param log [Boolean] when false, will not write to Rails.logger if present;
+  #   when true, will write to Rails.logger if present
   # @return [NilClass] nil
   # @example Using Symbol as argument
   #   class HelloWorld
@@ -96,25 +108,28 @@ module Loba
   #   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)
+  def value(argument, label: nil, inspect: true, production: false, log: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     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(
+
+    Internal::Platform.logger.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)}"
+      "#{Rainbow("    \t(in #{text[:line]})").color(60)}",
+      !!log
     )
 
     nil
@@ -122,6 +137,7 @@ module Loba
   module_function :value
 
   # Shorthand alias for Loba.value.
+  # @!method val(argument, label: nil, inspect: true, production: false, log: false)
   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.0.0
 platform: ruby
 authors:
 - Richard Newman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-05 00:00:00.000000000 Z
+date: 2023-07-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,6 +49,7 @@ files:
 - CODE_OF_CONDUCT.md
 - LICENSE
 - README.md
+- SECURITY.md
 - lib/loba.rb
 - lib/loba/internal.rb
 - lib/loba/internal/platform.rb
@@ -78,6 +65,7 @@ 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
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -86,14 +74,14 @@ 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
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: 'Loba: Easy tracing for debugging.'