loba 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b9de2bca8c9af5a371942f7ddf2f60d29cf6eaa7
-  data.tar.gz: 463649f58af8da129580719b0d9cf9cf07ca1a4b
+SHA256:
+  metadata.gz: e0f471467c64346c7c47d0b6496bf9f15677d8a2a107f8fe71dbf1901edd998d
+  data.tar.gz: b9c3ac98add22965ffcb61b3fcc9972d9144464690a70c78e66dd4f4b35483f9
 SHA512:
-  metadata.gz: 8fa11f7116da2e56106805244ffed2b37f94f99a394d3391a3d39b689357a5708a76691f751ed4ad60ce1cc5b5cfab4d283a87a1b4d63b72ae6dcab7c94f0277
-  data.tar.gz: 2bd9887db8c466e8bc2b8970014b67437045c472ce0a8ef3fab7cc49f9cfb53f8b8c876e29cd65911a31dad42490a8acea12b8936329827d43c488ccf89be19b
+  metadata.gz: a34112c0ce8214bc5dde3d5ad72bf1c457c954c0972b08d1fa0d43ff2d3b693b6db4a1d4ea4a86745712c5bb6d879f6cb885d1f3ac9453a50a4b2904c7eb3084
+  data.tar.gz: 85551529acd430a5e42849c87f76f2b811c63a038619b11f128e628f29f57d4ac86ddbface5eb878b5075b2920a6c5c5b467de4f9f25aeaa10991b3cdfe70cab

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Richard Newman
+Copyright (c) 2015-2021 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,5 +1,4 @@
 [![Gem Version](https://badge.fury.io/rb/loba.svg)](https://badge.fury.io/rb/loba)
-[![Dependency Status](https://gemnasium.com/rdnewman/loba.svg)](https://gemnasium.com/rdnewman/loba)
 [![Build Status](https://travis-ci.org/rdnewman/loba.svg?branch=master)](https://travis-ci.org/rdnewman/loba)
 [![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)
@@ -21,13 +20,13 @@ There are two kinds of questions I usually want to answer when trying to diagnos
 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 terse to minimize typing.
 
-Loba statements are intended to be minimally invasive and atomic.  They should not have any (much) more impact than a regular `puts` or `Rails.logger.debug` statement.
+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 expected to be removed when you're done with them.  No point in cluttering up production code.
+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 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 uses the [colorize gem](https://rubygems.org/gems/colorize) to help make trace statements more visible.
 
@@ -48,7 +47,7 @@ For example,
 To invoke,
 
 ```ruby
-Loba.ts    # or with optional arguments
+Loba.ts    # or with optional keyword arguments
 ```
 
 `Loba.timestamp` is an alias for `Loba.ts`.
@@ -78,7 +77,7 @@ require 'loba'    # not generally necessary in Rails projects
 class HelloWorld
   def initialize
     @x = 42
-Loba.ts          # see? it's easier to see what to remove later
+Loba.ts          # Loba statement put to the far left as a reminder to remove when done
     @y = "Charlie"
   end
 
@@ -93,9 +92,9 @@ HelloWorld.new.hello
 
 Output:
 
-```  
+```
 [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/richard/src/loba/spec/hello_world.rb:9:in `hello')
+[HelloWorld#hello] @x: 42       (in /home/usracct/src/loba/spec/hello_world.rb:9:in `hello')
 Hello, Charlie
 [TIMESTAMP] #=0002, diff=0.000720, at=1451615389.506132   (in=/home/usracct/src/lobademo/hello_world.rb:11:in 'hello'
 ```
@@ -106,9 +105,14 @@ This section is only relevant in Rails environments.
 
 The expectation is that Loba statements are just for development or test trace statements.  Generally, it's a bad idea to leave diagnostic code in Rails production; still, it can happen. And, occasionally, it can be useful to have trace statements in production too if you have an issue that is difficult to reproduce.
 
-`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 rendering 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 done sparingly if at all.
+`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.
 
-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 perhaps a Good Thing, if you never want them left in.
+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.
 
 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.
 
@@ -123,7 +127,7 @@ Loba.ts production: true
   end
 
   def hello
-Loba.val :@x, nil, production: true
+Loba.val :@x, production: true
     puts "Hello, #{@y}" if @x == 42
 Loba.ts true
   end
@@ -135,7 +139,14 @@ HelloWorld.new.hello
 
 See above Environment Notes if using with Rails.
 
-Add this line to your application's Gemfile:
+
+Install as below to be generally available (recommended to restrict to only local use):
+
+```bash
+$ gem install loba
+```
+
+To bundle, add this line to your application's Gemfile:
 
 ```ruby
 group :development, :test do
@@ -143,7 +154,7 @@ group :development, :test do
 end
 ```
 
-or for all environments:
+or for all environments (for example, if `production: true` used):
 
 ```ruby
 gem 'loba', require: false
@@ -156,12 +167,6 @@ And then execute:
 $ bundle
 ```
 
-Or install it yourself as:
-
-```bash
-$ gem install loba
-```
-
 ## 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.
@@ -171,6 +176,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Changelog
 |version|notes|
 |-------|-----|
+|1.0.0|updated for more recent rubies; uses Ruby 2.x-style keyword arguments for specifying options|
 |0.3.1|updated dependences; added inspect to Loba.val; amended parameters*|
 |0.3.0|(yanked)|
 |0.2.0|release on RubyGems.org|
@@ -178,8 +184,11 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### Deprecations
 
+#### 1.0.0
+In v0.3.x, to allow Loba notes to write to the log while in :production, an options hash as `{:production => true}` was introduced; this is now specified directly via Ruby-2.x style keywords, e.g., `production: true`. THIS IS A BREAKING CHANGE FROM v0.3.1 and earlier versions.
+
 #### 0.3.0
-In prior versions, to allow Loba notes to write to the log while in :production, an optional third parameter could be supplied as merely a boolean value.  In 0.3.0 and later versions, this must now be specified as part of an options hash as `{:production => true}`
+In prior versions, to allow Loba notes to write to the log while in :production, an optional third argument could be supplied as merely a boolean value.  In 0.3.0 and later versions, this must now be specified as part of an options hash as `{:production => true}`
 
 ### Semantic versions
 

data/lib/loba.rb

@@ -1,6 +1,6 @@
 require 'loba/version'
+require 'loba/internal'
 
-require 'singleton'
 require 'binding_of_caller'
 require 'colorize'
 
@@ -8,66 +8,65 @@ require 'colorize'
 # If a Rails application, will use Rails.logger.debug.
 # If not a Rails application, will use STDOUT.
 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 options [Hash] options for use
-  # @option options [Boolean] :production (false) true if this timestamp notice is enabled when running in :production environment
+  # 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.ts
+  #     Loba.timestamp
   #   end
   #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
-  def ts(options = {})
-
-    # evaluate options
-    filtered_options = Internal.filter_options(options, [:production])
-    production_is_ok = filtered_options[:production]
-
-    # log if possible
-    if Internal::Platform.logging_ok?(production_is_ok)
-      @loba_logger ||= Internal::Platform.logger
-      @loba_timer ||= Internal::TimeKeeper.instance
-
-      begin
-        @loba_timer.timenum += 1
-        timenow    = Time.now()
-        stamptag   = '%04d'%(@loba_timer.timenum)
-        timemark   = '%.6f'%(timenow.round(6).to_f)
-        timechg    = '%.6f'%(timenow - @loba_timer.timewas)
-        @loba_logger.call "[TIMESTAMP]".black.on_light_black +
-                          " #=".yellow +
-                          "#{stamptag}" +
-                          ", diff=".yellow +
-                          "#{timechg}" +
-                          ", at=".yellow +
-                          "#{timemark}" +
-                          "    \t(in=#{caller[0]})".light_black
-        @loba_timer.timewas = timenow
-      rescue StandardError => e
-        @loba_logger.call "[TIMESTAMP] #=FAIL, in=#{caller[0]}, err=#{e}".colorize(:red)
-      end
+  # @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 '[TIMESTAMP]'.black.on_light_black +
+                        ' #='.yellow +
+                        format('%04d', stats[:number]).to_s +
+                        ', diff='.yellow +
+                        format('%.6f', stats[:change]).to_s +
+                        ', at='.yellow +
+                        format('%.6f', stats[:now].round(6).to_f).to_s +
+                        "    \t(in=#{caller(1..1).first})".light_black
+    rescue StandardError => e
+      @loba_logger.call "[TIMESTAMP] #=FAIL, in=#{caller(1..1).first}, err=#{e}".colorize(:red)
     end
+
     nil
   end
-  module_function :ts
-
-  # Alias for Loba.ts
-  alias_method :timestamp, :ts
   module_function :timestamp
 
-  # Outputs a value notice showing value of provided argument including method and class identification
-  # @param argument [various] 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] an optional, explicit label to be used instead of attempting to infer from the argument
-  # @param options [Hash] options for use
-  # @option options [Boolean] :inspect (true) true if this value notice is to use #inspect against the content being evaluated
-  # @option options [Boolean] :production (false) true if this value notice is enabled when running in :production environment
+  # 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.val :name       # best to put Loba statement to far left for easy removal when done
+  #   Loba.value :name # putting Loba statement to far left helps remember to remove later
   #       puts "Hello, #{name}!"
   #     end
   #   end
@@ -77,7 +76,7 @@ module Loba
   # @example Using non-Symbol as argument
   #   class HelloWorld
   #     def hello(name)
-  #   Loba.val name
+  #   Loba.val name # Loba.val is a shorthand alias for Loba.value
   #       puts "Hello, #{name}!"
   #     end
   #   end
@@ -87,194 +86,34 @@ module Loba
   # @example Using non-Symbol as argument with a label
   #   class HelloWorld
   #     def hello(name)
-  #   Loba.val name, "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 val(argument = :nil, label = nil, options = {inspect: true})
-
-    # evaluate options
-    filtered_options = Internal.filter_options(options, [:production, :inspect])
-    production_is_ok = filtered_options[:production]
-    will_inspect = filtered_options[:inspect]
-
-    # log if possible
-    if Internal::Platform.logging_ok?(production_is_ok)
-      depth = 0
-      @loba_logger ||= Internal::Platform.logger
-
-      tag = Internal.calling_tag(depth+1)
-      name = argument.is_a?(Symbol) ? "#{argument}:" : nil
-
-      text = if label.nil?
-               name
-             else
-               label.strip!
-               label += ':' unless label[-1] == ':'
-             end
-
-      result = if argument.is_a?(Symbol)
-                 if will_inspect
-                   binding.of_caller(depth+1).eval(argument.to_s).inspect
-                 else
-                   binding.of_caller(depth+1).eval(argument.to_s)
-                 end
-               else
-                 will_inspect ? argument.inspect : argument
-               end
+  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 "#{text[:tag]} ".green +
+                      "#{text[:label]} ".light_green +
+                      text[:value] +
+                      "    \t(in #{text[:line]})".light_black
 
-      source_line = Internal.calling_source_line(depth+1)
-
-      @loba_logger.call "#{tag} ".green +
-                        "#{text.nil? ? '' : "#{text}"} ".light_green +
-                        "#{result.nil? ? '-nil-' : result}" +
-                        "    \t(in #{source_line})".light_black
-    end
     nil
   end
-  module_function :val
-
-
-  module Internal
+  module_function :value
 
-    class << self
-
-      # Prepare display of class name from where Loba was invoked
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_class_name(depth = 0)
-        m = binding.of_caller(depth+1).eval('self.class.name')
-        if m.nil? || m.empty?
-          '<anonymous class>'
-        elsif m == 'Class'
-          binding.of_caller(depth+1).eval('self.name')
-        else
-          m
-        end
-      end
-
-      # Prepare display of method name from where Loba was invoked
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_method_name(depth = 0)
-        m = binding.of_caller(depth+1).eval('self.send(:__method__)')
-        (m.nil? || m.empty?) ? '<anonymous method>' : m
-      end
-
-      # Prepare display of whether the method from where Loba was invoked is for a class or an instance
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_method_type(depth = 0)
-        if binding.of_caller(depth+1).eval('self.class.name') == 'Class'
-          :class
-        else
-          :instance
-        end
-      end
-
-      # Prepare display of line number from where Loba was invoked [UNUSED]
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_line_number(depth = 0)
-        binding.of_caller(depth+1).eval('__LINE__')
-      end
-
-      # Assemble display that shows the method invoking Loba
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_tag(depth = 0)
-        delim = {class: '.', instance: '#'}
-        "[#{calling_class_name(depth+1)}#{delim[calling_method_type(depth+1)]}#{calling_method_name(depth+1)}]"
-      end
-
-      # Identify source code line from where Loba was invoked
-      # @param depth [integer] internal tracking of call stack depth
-      def calling_source_line(depth = 0)
-        caller[depth]
-      end
-
-      # Filters options argument for deprecated or unexpected use
-      # @param options [various] options argument to filter
-      # @param allowed_keys [array] array of expected keys in options
-      def filter_options(options, allowed_keys = [])
-        result = {}
-        allowed_keys.each { |key| result[key] = false }
-
-        case options
-        when Hash
-          allowed_keys.each do |key|
-            result[key] = !!options[key] unless options[key].nil?
-          end
-        when TrueClass
-          if allowed_keys.include? :production
-            Internal::Deprecated._0_3_0(true)
-            result[:production] = true
-          end
-        when FalseClass
-          Internal::Deprecated._0_3_0(false)
-        else   # to be safe, treat as false
-          Internal::Deprecated._0_3_0(false)
-        end
-
-        result
-      end
-
-    end
-
-    # Internal class for deprecation warnings.
-    class Deprecated
-      class << self
-        # Deprecations as of version 0.3.0
-        # @param value [boolean] deprecated value supplied in original call to use in deprecation message
-        def _0_3_0(value)
-          bool = value ? "true" : "false"
-          verb = value ? "enabled" : "disabled"
-          warn "DEPRECATION WARNING: use {:production => #{bool}} instead to indicate notice is #{verb} in production"
-        end
-      end
-    end
-
-    # Internal class for tracking time stamps; should not be used directly
-    # @!attribute [rw] timewas
-    #   Previous timestamped Time value
-    # @!attribute [rw] timenum
-    #   Count of timestamping occurances so far
-    class TimeKeeper
-      include Singleton
-      attr_accessor :timewas, :timenum
-      def initialize
-        @timewas, @timenum = Time.now, 0
-      end
-    end
-
-    # Internal class for managing logging across Rails and non-Rails applications
-    class Platform
-      class << self
-        # Returns true if Rails appears to be available
-        def rails?
-          defined?(Rails)
-        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
-            true   # not Rails production if Rails isn't recognized
-          end
-        end
-
-        # Returns a logging mechanism appropriate for the application
-        def logger
-          if (rails? && Rails.logger.present?)
-            ->(arg){Rails.logger.debug arg}
-          else
-            ->(arg){puts arg}
-          end
-        end
-      end
-    end
-
-  end   # module Internal
-
-end   # module Loba
+  # Shorthand alias for Loba.value.
+  alias val value
+  module_function :val
+end