loba 0.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 140168f9589fcef334a886a988b973ad67a01642
-  data.tar.gz: d07c018d2ba7208329f6d2bc428d7709411e4e3b
+SHA256:
+  metadata.gz: 196b8d0b75303a31baa40559f2ece4bb2e53ef288f78822e2436b95926826532
+  data.tar.gz: c06af1fc1450f468abd679b86d35da01464e07d80ea35fc651b9180b1eef8291
 SHA512:
-  metadata.gz: 3a6306138c2e1ec190d63d19302c5787ee4e1b617cabf15f88ea2d5699f306fd3f7c94103713b4b8595b5c51dab7ad8990a4d32d1f45844a95a03ff34094b5e5
-  data.tar.gz: 9131d9074be00bfb1c9cc6804addb48b649e51bb3f1a3b38ce675336e4d506da44bc26647c2d8cbe1e93951b56cbee4e545e118737c3d1394f4f8ba0073634ef
+  metadata.gz: 5355b4ffd23f1a7d07ff28a7ecd382f5b8b6b0e103b600fa91b96233483bc60588ab108206a2e798f64084509faab69cb15aad99c87089f3a65fbebe0af48e16
+  data.tar.gz: a51c4de30e76e85a45a319b58aa402ea32a2d5b32dd15914f2c409e4261ece721659ce4e4791bb09ac0083398a0766ff622199f1c007f78344370f2d89df92c5

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# 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/),
+and, as of version 0.3.0 and later, this project adheres to [Semantic Versioning (2.0.0)](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.1] - 2021-09-05
+### Added
+- Optional specs for developers to check Loba performance (no surprising issues found)
+
+### 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
+
+## [1.2.0] - 2021-09-05 [YANKED]
+
+## [1.1.0] - 2021-08-20
+### Added
+- CHANGELOG.md to follow "Keep a Changelog" convention
+- minor unit tests
+
+### Changed
+- Replaced colorize gem with rainbow gem for MIT license purity
+- "Changelog" section of README.md to refer to new CHANGELOG.md
+- `Loba.ts`: "(in ...)" of notice now has a space instead of a "=" (matches `Loba.val`)
+- `Loba.ts`: string continuation instead of concatenation for performance
+- `Loba.val`: string continuation instead of concatenation for performance
+
+## [1.0.0] - 2021-08-18
+### Added
+- `Loba.val`: added `Loba.value` as an alias
+
+### Changed
+- `Loba.ts`: use Ruby 2.x-style keyword arguments instead of an options hash [BREAKING CHANGE]
+- `Loba.val`: use Ruby 2.x-style keyword arguments instead of an options hash [BREAKING CHANGE]
+- Updated for more recent Ruby versions (>= 2.5)
+- Updated gem dependencies
+- Expanded unit testing
+- Refactored code to better compartmentalize for easier maintainability
+- Updated user documentation, including corrections and better `production: true` warning
+- Updated YARD documentation
+
+### Removed
+- Gemnasium link from README
+- Last positional argument as `true` or `false` to control presence in production environments
+- Options hash support to control `production: true` and `inspect: false` [BREAKING CHANGE]
+
+## [0.3.1] - 2017-04-07
+### Added
+- YARD documentation
+- `Loba.val`: `inspect` option to control use of `.inspect` on an argument value
+- `Loba.ts`: added `Loba.timestamp` as an alias
+
+### Changed
+- Converted to options hash instead of implicit positional arguments
+- `Loba.val`: nil values now display as `-nil-` instead of blank output
+
+### Deprecated
+- Last positional argument as `true` or `false` to control presence in production environments
+
+## [0.3.0] - 2017-04-07 [YANKED]
+
+## [0.2.0] - 2016-12-02
+### Added
+- Initial publication to RubyGems.org
+- Gem badge to README
+- Code Climate integration
+
+### Changed
+- Improved and corrected documentation
+- Various bug fixes
+- Generalized for Ruby and reduced Rails centricity
+
+## 0.1.0 - 2016-01-06
+### Added
+- Initial implementation
+
+[Unreleased]: https://github.com/rdnewman/loba/compare/v1.2.1...HEAD
+[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
+[1.0.0]: https://github.com/rdnewman/loba/compare/v0.3.1...v1.0.0
+[0.3.1]: https://github.com/rdnewman/loba/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/rdnewman/loba/compare/0.2.0...v0.3.0
+[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/0.2.0

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,13 +1,13 @@
-[![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)
+[![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)
 [![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/master.svg)](https://hakiri.io/github/rdnewman/loba/master)
+[![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)
+![Loba is "write" in Zulu](readme/zulu.png)
 
 Easy tracing for debugging: handy methods for adding trace lines to output or Rails logs.
 
@@ -17,18 +17,18 @@ 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 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.
+Loba uses the [rainbow gem](https://rubygems.org/gems/rainbow) to help make trace statements more visible.
 
 ## Usage
 
@@ -47,9 +47,11 @@ For example,
 To invoke,
 
 ```ruby
-Loba.ts    # no arguments, generally (see Environment Notes below)
+Loba.ts    # or with optional keyword arguments
 ```
 
+`Loba.timestamp` is an alias for `Loba.ts`.
+
 You can read [more detail](readme/ts.md) on this command.
 
 #### Variable or method return inspection:  `Loba.val`
@@ -75,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
 
@@ -90,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'
 ```
@@ -103,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 with a `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.
+
+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 perhaps 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'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.
 
@@ -115,12 +122,12 @@ The following is the code example snippet but always logging even in Rails produ
 class HelloWorld
   def initialize
     @x = 42
-Loba.ts(true)
+Loba.ts production: true
     @y = "Charlie"
   end
 
   def hello
-Loba.val :@x, nil, true
+Loba.val :@x, production: true
     puts "Hello, #{@y}" if @x == 42
 Loba.ts true
   end
@@ -132,28 +139,33 @@ 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
-  gem 'loba', require: false, github: 'rdnewman/loba'   # until I publish it on RubyGems
+  gem 'loba', require: false
 end
 ```
 
-or for all environments:
+or for all environments (for example, if `production: true` used):
 
 ```ruby
-gem 'loba', require: false, github: 'rdnewman/loba'   # until I publish it on RubyGems
+gem 'loba', require: false
 ```
 
 
 And then execute:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install loba
+```bash
+$ bundle
+```
 
 ## Development
 
@@ -161,10 +173,13 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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).
 
-## Contributing
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for details. This gem follows semantic versioning.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/rdnewman/loba. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at <https://github.com/rdnewman/loba>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/loba/internal/platform.rb

@@ -0,0 +1,34 @@
+module Loba
+  module Internal
+    # 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) ? 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
+
+        # 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
+end

data/lib/loba/internal/time_keeper.rb

@@ -0,0 +1,33 @@
+require 'singleton'
+
+module Loba
+  module Internal
+    # Internal class for tracking time stamps; should not be used directly
+    # @!attribute [r] timewas
+    #   Previous timestamped Time value
+    # @!attribute [r] timenum
+    #   Count of timestamping occurances so far
+    class TimeKeeper
+      include Singleton
+      attr_reader :timewas, :timenum
+
+      def initialize
+        reset!
+      end
+
+      def ping
+        @timenum += 1
+        now = Time.now
+        change = now - @timewas
+        @timewas = now
+
+        { number: @timenum, now: now, change: change }
+      end
+
+      def reset!
+        @timewas = Time.now
+        @timenum = 0
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+require 'binding_of_caller'
+
+module Loba
+  module Internal
+    module Value
+      # Internal helper functions for Value.phrases
+      module ValueHelper
+        module_function
+
+        # Assemble display that shows the method invoking Loba
+        # @param depth [Integer] depth in call stack to retrieve tag from
+        # @return [String] tag for where Loba was invoked, wrapped in "[" and "]"
+        def tag(depth: 0)
+          delim = { class: '.', instance: '#' }
+          '[' \
+            "#{class_name(depth: depth + 1)}" \
+            "#{delim[method_type(depth: depth + 1)]}" \
+            "#{method_name(depth: depth + 1)}" \
+            ']'
+        end
+
+        # Identify source code line from where Loba was invoked
+        # @param depth [Integer] depth in call stack to retrieve source code line from
+        # @return [Integer] source code line number where Loba was invoked
+        def line(depth: 0)
+          caller[depth]
+        end
+
+        # Prepare display of an argument's value.
+        # @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 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)
+          val = evaluate(argument: argument, inspect: inspect, depth: depth + 1)
+
+          # #inspect adds explicit quotes to strings, so strip back off since #inspect
+          # always returns a String
+          val = Loba::Internal.unquote(val) if inspect
+
+          # make nils obvious
+          val.nil? ? '-nil-' : val.to_s
+        end
+
+        # 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.
+        #
+        # @param argument [Symbol, Object] the value or variable for which information is
+        #   to be retrieved
+        #   * If a symbol, it is assumed to be a reference to a variable
+        #     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
+        #
+        # @return [String] label
+        def label(argument:, explicit_label: nil)
+          text = if explicit_label.nil?
+                   argument.is_a?(Symbol) ? "#{argument}:" : nil
+                 elsif explicit_label.respond_to?(:strip)
+                   s = explicit_label.strip
+                   s += ':' unless s[-1] == ':'
+                   s
+                 end
+
+          text.nil? ? '[unknown value]:' : text.to_s
+        end
+
+        # 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 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)
+          return inspect ? argument.inspect : argument unless argument.is_a?(Symbol)
+
+          evaluation = binding.of_caller(depth + 1).eval(argument.to_s)
+          inspect ? evaluation.inspect : evaluation
+        end
+
+        # Prepare display of class name from where Loba was invoked
+        # @param depth [Integer] depth in call stack to retrieve class name from
+        # @return [String] name of class where Loba was invoked
+        def 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 whether the method from where Loba was invoked is
+        # for a class or an instance
+        # @param depth [Integer] depth in call stack
+        # @return [:class] if method in call stack is a class method
+        # @return [:instance] if method in call stack is an instance method
+        def method_type(depth: 0)
+          if binding.of_caller(depth + 1).eval('self.class.name') == 'Class'
+            :class
+          else
+            :instance
+          end
+        end
+
+        # Prepare display of method name from where Loba was invoked
+        # @param depth [Integer] depth in call stack to retrieve method name from
+        # @return [Symbol, String] name of class where Loba was invoked
+        def method_name(depth: 0)
+          m = binding.of_caller(depth + 1).eval('self.send(:__method__)')
+          m.nil? || m.empty? ? '<anonymous method>' : m
+        end
+      end
+    end
+  end
+end