loba 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 140168f9589fcef334a886a988b973ad67a01642
-  data.tar.gz: d07c018d2ba7208329f6d2bc428d7709411e4e3b
+  metadata.gz: b9de2bca8c9af5a371942f7ddf2f60d29cf6eaa7
+  data.tar.gz: 463649f58af8da129580719b0d9cf9cf07ca1a4b
 SHA512:
-  metadata.gz: 3a6306138c2e1ec190d63d19302c5787ee4e1b617cabf15f88ea2d5699f306fd3f7c94103713b4b8595b5c51dab7ad8990a4d32d1f45844a95a03ff34094b5e5
-  data.tar.gz: 9131d9074be00bfb1c9cc6804addb48b649e51bb3f1a3b38ce675336e4d506da44bc26647c2d8cbe1e93951b56cbee4e545e118737c3d1394f4f8ba0073634ef
+  metadata.gz: 8fa11f7116da2e56106805244ffed2b37f94f99a394d3391a3d39b689357a5708a76691f751ed4ad60ce1cc5b5cfab4d283a87a1b4d63b72ae6dcab7c94f0277
+  data.tar.gz: 2bd9887db8c466e8bc2b8970014b67437045c472ce0a8ef3fab7cc49f9cfb53f8b8c876e29cd65911a31dad42490a8acea12b8936329827d43c488ccf89be19b

data/README.md

@@ -1,3 +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)
@@ -17,8 +18,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.  
 
@@ -47,9 +48,11 @@ For example,
 To invoke,
 
 ```ruby
-Loba.ts    # no arguments, generally (see Environment Notes below)
+Loba.ts    # or with optional 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`
@@ -103,7 +106,7 @@ 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 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.
 
 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.
 
@@ -115,12 +118,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, nil, production: true
     puts "Hello, #{@y}" if @x == 42
 Loba.ts true
   end
@@ -136,24 +139,28 @@ 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:
 
 ```ruby
-gem 'loba', require: false, github: 'rdnewman/loba'   # until I publish it on RubyGems
+gem 'loba', require: false
 ```
 
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install loba
+```bash
+$ gem install loba
+```
 
 ## Development
 
@@ -161,10 +168,26 @@ 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
+|version|notes|
+|-------|-----|
+|0.3.1|updated dependences; added inspect to Loba.val; amended parameters*|
+|0.3.0|(yanked)|
+|0.2.0|release on RubyGems.org|
+|0.1.0|initial development|
+
+### Deprecations
 
-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.
+#### 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}`
+
+### Semantic versions
+
+As of version 0.3.0 and later, this gem follows semantic versioning [2.0.0](http://semver.org/spec/v2.0.0.html) conventions.
+
+## 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.rb

@@ -1,4 +1,5 @@
 require 'loba/version'
+
 require 'singleton'
 require 'binding_of_caller'
 require 'colorize'
@@ -10,14 +11,21 @@ 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_is_ok [Boolean] true if this timestamp notice is enabled when running in :production environment
+  # @param options [Hash] options for use
+  # @option options [Boolean] :production (false) true if this timestamp notice is enabled when running in :production environment
   # @return [NilClass] nil
   # @example Basic use
   #   def hello
   #     Loba.ts
   #   end
   #   #=> [TIMESTAMP] #=0001, diff=0.000463, at=1451615389.505411, in=/path/to/file.rb:2:in 'hello'
-  def ts(production_is_ok = false)
+  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
@@ -45,9 +53,16 @@ module Loba
   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
   # @return [NilClass] nil
   # @example Using Symbol as argument
   #   class HelloWorld
@@ -79,7 +94,14 @@ module Loba
   #   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, production_is_ok = false)
+  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
@@ -95,9 +117,13 @@ module Loba
              end
 
       result = if argument.is_a?(Symbol)
-                 binding.of_caller(depth+1).eval(argument.to_s)
+                 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
-                 argument
+                 will_inspect ? argument.inspect : argument
                end
 
       source_line = Internal.calling_source_line(depth+1)
@@ -115,9 +141,11 @@ module Loba
   module Internal
 
     class << self
-      LOBA_CLASS_NAME = 'self.class.name'
+
+      # 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(LOBA_CLASS_NAME)
+        m = binding.of_caller(depth+1).eval('self.class.name')
         if m.nil? || m.empty?
           '<anonymous class>'
         elsif m == 'Class'
@@ -127,12 +155,15 @@ module Loba
         end
       end
 
-      LOBA_METHOD_NAME = 'self.send(:__method__)'
+      # 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(LOBA_METHOD_NAME)
+        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
@@ -141,17 +172,63 @@ module Loba
         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
 
-      def calling_tag(depth = 0)
-        delim = {class: '.', instance: '#'}
-        "[#{calling_class_name(depth+1)}#{delim[calling_method_type(depth+1)]}#{calling_method_name(depth+1)}]"
+      # 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
 

data/lib/loba/version.rb

@@ -1,4 +1,3 @@
-#class Loba
 module Loba
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/loba.gemspec

@@ -21,9 +21,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.required_ruby_version = '>= 2.1.0'
 
-  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency 'bundler', '~> 1.11'
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec-rails", "~> 3.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
 
   spec.add_dependency "binding_of_caller", "~> 0.7"
   spec.add_dependency "colorize", "~> 0.7"

data/readme/ts.md

@@ -14,6 +14,8 @@ To invoke,
 Loba.ts    # no arguments
 ```
 
+`Loba.timestamp` is an alias for `Loba.ts`.
+
 The resulting notice output format is
 
 ```
@@ -21,9 +23,23 @@ The resulting notice output format is
 ```
 
 where
-* `nnn` ("#=") is a sequential numbering (1, 2, 3, ...) of timestamp notices,
-* `ss.ssssss` ("diff=") is number of seconds since the last timestamp notice was output (i.e., relative time),
-* `tttttttttt.tttttt` ("at=") is Time.now (as seconds) (i.e., absolute time),
-* `/path/to/code/somecode.rb` ("in=") is the source code file that invoked `Loba.ts`,
-* `LL` ("in=...:") is the line number of the source code file that invoked `Loba.ts`, and
-* `some_method`is the method in which `Loba.ts` was invoked.
+*   `nnn` ("#=") is a sequential numbering (1, 2, 3, ...) of timestamp notices,
+*   `ss.ssssss` ("diff=") is number of seconds since the last timestamp notice was output (i.e., relative time),
+*   `tttttttttt.tttttt` ("at=") is Time.now (as seconds) (i.e., absolute time),
+*   `/path/to/code/somecode.rb` ("in=") is the source code file that invoked `Loba.ts`,
+*   `LL` ("in=...:") is the line number of the source code file that invoked `Loba.ts`, and
+*   `some_method`is the method in which `Loba.ts` was invoked.
+
+
+##### Options
+
+As the last argument, an options hash may be provided:
+*   `production`: true if this value notice is enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
+
+###### Example 5: Using options hash
+```ruby
+Loba.ts production: true
+```
+```ruby
+Loba.ts {production: true}
+```

data/readme/val.md

@@ -15,7 +15,7 @@ Loba.val some_identifier  # directly give a variable or method name instead of a
 or
 
 ```
-Loba.val some_identifier "My label:"  # same as direct variable, but allows a custom label
+Loba.val some_identifier, "My label:"  # same as direct variable, but allows a custom label
 ```
 
 Will produce a notice similar to the following:
@@ -87,17 +87,31 @@ The resulting notice output format is
 ```
 
 where
-* `ccccc` is the name of the class from where `Loba.val` was invoked,
-* `mmmmm` is the name of the method from where `Loba.val` was invoked,
-* `vvvvv` is generally the name of the variable for which `Loba.val` is inspecting, or any custom label given,
-* `rrrrr` is the result of inspecting what `Loba.val` was invoked against,
-* `/path/to/code/somecode.rb` is the source code file that invoked `Loba.val`,
-* `LL` is the line number of the source code file that invoked `Loba.val`, and
-* `some_method`is the method in which `Loba.val` was invoked.
+*   `ccccc` is the name of the class from where `Loba.val` was invoked,
+*   `mmmmm` is the name of the method from where `Loba.val` was invoked,
+*   `vvvvv` is generally the name of the variable for which `Loba.val` is inspecting, or any custom label given,
+*   `rrrrr` is the result of inspecting what `Loba.val` was invoked against,
+*   `/path/to/code/somecode.rb` is the source code file that invoked `Loba.val`,
+*   `LL` is the line number of the source code file that invoked `Loba.val`, and
+*   `some_method`is the method in which `Loba.val` was invoked.
 
 
 Notes:
-* `ccccc`:  Ruby supports anonymous classes (e.g., `= Class.new`).  If an anonymous class, "<anonymous class>" will be output here.
-* `mmmmm`:  Ruby supports anonymous methods, procs, and lambdas.  If an anonymous method, et al, "<anonymous method>" will be output here.
-* `vvvvv`:  This depends on the argument being provided:  if a symbol, then this field will use that symbol to determine the name and present it here.  If not, nothing will appear for this field.
-* `rrrrr`:  The value of the variable given to `Loba.val`.  `inspect` may be used.
+*   `ccccc`:  Ruby supports anonymous classes (e.g., `= Class.new`).  If an anonymous class, "<anonymous class>" will be output here.
+*   `mmmmm`:  Ruby supports anonymous methods, procs, and lambdas.  If an anonymous method, et al, "<anonymous method>" will be output here.
+*   `vvvvv`:  This depends on the argument being provided:  if a symbol, then this field will use that symbol to determine the name and present it here.  If not, nothing will appear for this field.
+*   `rrrrr`:  The value of the variable given to `Loba.val`.  `inspect` may be used (see [options](#options) below).
+
+##### Options
+
+As the last argument, an options hash may be provided:
+*   `inspect`: true if this value notice is to use #inspect against the content being evaluated \[_default: `true`_\]
+*   `production`: true if this value notice is enabled when running in :production environment (see ["Environment Notes"](README.md#environment-notes)) \[_default: `false`_\]
+
+###### Example 5: Using options hash
+```ruby
+Loba.val name, "Name:", inspect: false, production: true
+```
+```ruby
+Loba.val :name, nil, {production: true}
+```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loba
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Richard Newman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-03 00:00:00.000000000 Z
+date: 2017-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -102,7 +102,6 @@ files:
 - lib/loba.rb
 - lib/loba/version.rb
 - loba.gemspec
-- readme/environments.md
 - readme/ts.md
 - readme/val.md
 - readme/zulu.png
@@ -126,9 +125,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: 'Loba: Easy tracing for debugging.'
 test_files: []
-has_rdoc: