loba 0.2.0

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2
+addons:
+    code_climate:
+        repo_token: 8e4f3d6c483544a1479af37a53ca72b968cf77cdf7a050e3e163cf526444d832
+after_success:
+  - bundle exec codeclimate-test-reporter

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at richard@newmanworks.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'yard'
+end
+
+group :test do
+  gem 'codeclimate-test-reporter', require: nil
+  gem 'simplecov', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+[![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)
+[![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)
+
+# Loba
+
+![Loba is "write" in zulu](readme/zulu.png)
+
+Easy tracing for debugging: handy methods for adding trace lines to output or Rails logs.
+
+(Installation is pretty much what you'd expect for a gem, but read Environment Notes below first.)
+
+## Overview
+
+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?
+
+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 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 uses the [colorize gem](https://rubygems.org/gems/colorize) 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.
+
+#### Timestamp notices:  `Loba.ts`
+
+Outputs a timestamped notice, useful for quick traces to see the code path and easier than, say, [Kernel#set_trace_func](http://ruby-doc.org/core-2.2.3/Kernel.html#method-i-set_trace_func). Also does a simple elapsed time check since the previous timestamp notice to help with quick, minimalist profiling.
+
+For example,
+
+```
+[TIMESTAMP] #=0002, diff=93.478016, at=1451444972.970602     (in=/home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
+```
+
+To invoke,
+
+```ruby
+Loba.ts    # no arguments, generally (see Environment Notes below)
+```
+
+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
+
+```ruby
+Loba.val :var_sym   # the :var_sym argument is the variable or method name given as a symbol
+```
+
+For example,
+
+```
+[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.
+
+#### Snippet example
+
+```ruby
+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
+    @y = "Charlie"
+  end
+
+  def hello
+Loba.val :@x
+    puts "Hello, #{@y}" if @x == 42
+Loba.ts
+  end
+end
+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')
+Hello, Charlie
+[TIMESTAMP] #=0002, diff=0.000720, at=1451615389.506132   (in=/home/usracct/src/lobademo/hello_world.rb:11:in 'hello'
+```
+
+## Environment Notes
+
+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.
+
+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.
+
+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.
+
+The following is the code example snippet but always logging even in Rails production environments:
+
+```ruby
+class HelloWorld
+  def initialize
+    @x = 42
+Loba.ts(true)
+    @y = "Charlie"
+  end
+
+  def hello
+Loba.val :@x, nil, true
+    puts "Hello, #{@y}" if @x == 42
+Loba.ts true
+  end
+end
+HelloWorld.new.hello
+```
+
+## Installation
+
+See above Environment Notes if using with Rails.
+
+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
+end
+```
+
+or for all environments:
+
+```ruby
+gem 'loba', require: false, github: 'rdnewman/loba'   # until I publish it on RubyGems
+```
+
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ 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.
+
+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
+
+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
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "loba"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/loba/version.rb

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

data/lib/loba.rb

@@ -0,0 +1,203 @@
+require 'loba/version'
+require 'singleton'
+require 'binding_of_caller'
+require 'colorize'
+
+# 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.
+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
+  # @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)
+    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
+    end
+    nil
+  end
+  module_function :ts
+
+  # 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
+  # @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
+  #       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
+  #       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.val 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, production_is_ok = false)
+    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)
+                 binding.of_caller(depth+1).eval(argument.to_s)
+               else
+                 argument
+               end
+
+      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
+
+    class << self
+      LOBA_CLASS_NAME = 'self.class.name'
+      def calling_class_name(depth = 0)
+        m = binding.of_caller(depth+1).eval(LOBA_CLASS_NAME)
+        if m.nil? || m.empty?
+          '<anonymous class>'
+        elsif m == 'Class'
+          binding.of_caller(depth+1).eval('self.name')
+        else
+          m
+        end
+      end
+
+      LOBA_METHOD_NAME = 'self.send(:__method__)'
+      def calling_method_name(depth = 0)
+        m = binding.of_caller(depth+1).eval(LOBA_METHOD_NAME)
+        (m.nil? || m.empty?) ? '<anonymous method>' : m
+      end
+
+      def calling_method_type(depth = 0)
+        if binding.of_caller(depth+1).eval('self.class.name') == 'Class'
+          :class
+        else
+          :instance
+        end
+      end
+
+      def calling_line_number(depth = 0)
+        binding.of_caller(depth+1).eval('__LINE__')
+      end
+
+      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)}]"
+      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

data/loba.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'loba/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "loba"
+  spec.version       = Loba::VERSION
+  spec.platform      = Gem::Platform::RUBY
+  spec.authors       = ["Richard Newman"]
+  spec.email         = ["richard@newmanworks.com"]
+
+  spec.summary       = %q{Loba: Easy tracing for debugging.}
+  spec.description   = %q{Handy methods for adding trace lines to output or Rails logs.}
+  spec.homepage      = "https://github.com/rdnewman/loba"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = '>= 2.1.0'
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec-rails", "~> 3.0"
+
+  spec.add_dependency "binding_of_caller", "~> 0.7"
+  spec.add_dependency "colorize", "~> 0.7"
+end

data/readme/ts.md

@@ -0,0 +1,29 @@
+#### Timestamp notices:  `Loba.ts`
+Outputs a timestamped notice, useful for quick traces to see the code path and easier than, say, [Kernel#set_trace_func](http://ruby-doc.org/core-2.2.3/Kernel.html#method-i-set_trace_func).
+Also does a simple elapsed time check since the previous timestamp notice to help with quick, minimalist profiling.
+
+For example,
+
+```
+[TIMESTAMP] #=0002, diff=93.478016, at=1451444972.970602    (in=/home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
+```
+
+To invoke,
+
+```
+Loba.ts    # no arguments
+```
+
+The resulting notice output format is
+
+```
+[TIMESTAMP] #=nnnn, diff=ss.ssssss, at=tttttttttt.tttttt    (in=/path/to/code/somecode.rb:LL:in 'some_method')
+```
+
+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.

data/readme/val.md

@@ -0,0 +1,103 @@
+#### Value notices:  `Loba.val`
+
+Inserts line to Rails.logger.debug (or to STDOUT if Rails.logger not available) showing value with method and class identification
+
+```
+Loba.val :var_sym         # the :var_sym argument is the variable or method name given as a symbol (see below)
+```
+
+or
+
+```
+Loba.val some_identifier  # directly give a variable or method name instead of a symbol (see below)
+```
+
+or
+
+```
+Loba.val some_identifier "My label:"  # same as direct variable, but allows a custom label
+```
+
+Will produce a notice similar to the following:
+
+```
+[Target.some_calculation] my_var: 54       (in /home/usracct/src/myapp/app/models/target.rb:55:in `some_calculation')
+```
+
+###### Example 1: Using simple Symbol as argument
+```ruby
+class HelloWorld
+  def hello(name)
+Loba.val :name       # best to put Loba statement to far left for easy removal when done
+    puts "Hello, #{name}!"
+  end
+end
+HelloWorld.new.hello("Charlie")
+#=> [HelloWorld#hello] name: Charlie        (in /path/to/file/hello_world.rb:3:in `hello')
+#=> Hello, Charlie!
+```
+
+###### Example 2: Using more complex Symbol as argument
+```ruby
+class HelloWorld
+  def hello(name)
+    myHash = {somename: name}
+# Loba.val :myHash[name]  won't work directly, but...
+Loba.val "myHash[name]".to_sym   # will work -- just express the name as a String and cast to a Symbol
+    puts "Hello, #{name}!"
+  end
+end
+HelloWorld.new.hello("Charlie")
+#=> [HelloWorld#hello] myHash[name]: Charlie        (in /path/to/file/hello_world.rb:5:in `hello')
+#=> Hello, Charlie!
+```
+
+###### Example 3: Using a non-Symbol as argument without a label
+```ruby
+class HelloWorld
+  def hello(name)
+Loba.val name
+    puts "Hello, #{name}!"
+  end
+end
+HelloWorld.new.hello("Charlie")
+#=> [HelloWorld#hello] Charlie        (in /path/to/file/hello_world.rb:3:in `hello')
+#=> Hello, Charlie!
+```
+
+###### Example 4: Using a non-Symbol as argument with a label
+```ruby
+class HelloWorld
+  def hello(name)
+Loba.val name, "Name:"
+    puts "Hello, #{name}!"
+  end
+end
+HelloWorld.new.hello("Charlie")
+#=> [HelloWorld#hello] Name: Charlie        (in /path/to/file/hello_world.rb:3:in `hello')
+#=> Hello, Charlie!
+```
+
+##### Notice format:
+
+The resulting notice output format is
+
+```
+[ccccc.mmmmm] vvvvv: rrrrr         (in /path/to/code/somecode.rb:LL:in 'some_method')
+```
+
+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.
+
+
+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.