debug_me 1.0.2 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03f8c0541fab13dc5ea656fdd5ef697075132bb00a4662345d4d27f3f935bc99
+  data.tar.gz: 0d1d53bbedf84a6d9e17fcccb1565eaecd25ff0fa58ce09daeafb7386482999b
+SHA512:
+  metadata.gz: 6531b542b0b28d5dd0d5b0dee66b3e15d316a0ee05b54be0dedfb1a38f7a78e1cf9ba366404dd2a5d8867e5bb35af7add5254b1a58187a5be610b0f750b1ad24
+  data.tar.gz: 36df84f99c1ab56ea168a7e693904244cf2b5c46660da6326e0649c5cdf5685190eb01155f1cbee548914babbbe02e9726ef6418de67e490a9a9f75d387c30fd

data/README.md

@@ -1,13 +1,24 @@
 # DebugMe
 
-This thing is pretty old.  There are much better
+A tool to print the labeled value of variables.
+
+This thing is pretty old; but, so am I.  Even with the gray
+in our hair we still do the job.
+
+There are much more complex/comprehensive
 ways of debugging in a complex application.  But,
 you know, I keep returning to this little method
 time after time.  I guess that marks me as a geezer.
 
-A tool to print the labeled value of variables.
 
-Works with local, instance and class variables.
+DebugMe::debug_me(){} works with local, instance and class variables.
+
+## Recent Changes
+
+* 1.1.0 Changes the output formatting w/r/t the use of levels option; add :backtrace option for full backtrace
+* 1.0.6 Added support for variable backtrack length via the :levels option
+* 1.0.5 Added support for an instance of a Logger class.
+* 1.0.4 Added :strftime to the options; changed the default format from decimal seconds since epic to something that is more easy comprehend on a clock.
 
 ## Installation
 
@@ -35,6 +46,11 @@ debug_me # Prints only the header banner consisting of tag, method name, file na
 
 debug_me('INFO') # Also prints only the header but with a different tag
 
+debug_me(levels: 5) # Along with the header, show the call stack back this many levels
+debug_me{:backtrace}          # show the entire call stack
+debug_me{[ :backtrace ]} will # show the entire call stack
+debug_me(levels: 5){[ :backtrace ]} # will only show the first 5 levels of the backtrace - ie. the levels parameter supersedes :backtrace
+
 debug_me {} # prints the default header and __ALL__ variables
 
 debug_me {:just_this_variable} # prints the default header and the value of only one specific variable
@@ -45,9 +61,9 @@ debug_me { [:this_one, :that_one, :that_other_one] } # prints default header and
 # Each element of the array is 'eval'ed with the context binding of the caller
 debug_me(){[ :my_var, 'my_complex_var_or_method[my_var]' ]}
 
-debug_me(:header => false) {} # disables the printing of the header; prints all variables
+debug_me(header: false) {} # disables the printing of the header; prints all variables
 
-debug_me(:tag => 'MyTag', :header => false) {} # disables header, sets different tag, prints all variables
+debug_me(tag: 'MyTag', :header => false) {} # disables header, sets different tag, prints all variables
 
 debug_me('=== LOOK ===') {} # changes the tag and prints all variables with a header line
 
@@ -55,8 +71,140 @@ debug_me('=== LOOK ===') {:@foo} # changes the tag, prints a header line and a s
 
 debug_me('=== LOOK ===') {:@@foo} # changes the tag, prints a header line and a specific class variable
 
-debug_me(:ivar => false, :cvar => false) {} # print only the local variables with the default tag and a header line
+debug_me(ivar: false, cvar: false) {} # print only the local variables with the default tag and a header line
+
+```
+
+Most of the examples above use symbols to designate the variables that you want
+to be shown with their name as a label.  You can also use strings.  With strings
+you are not limited to just variables.  Consider these examples:
+
+```ruby
+debug_me {[ 'some_array.size', 'SomeDatabaseModel.count' ]}
+
+# What a backtrace with your variables?
+
+debug_me {[
+  :my_variable,
+  'some_hash.keys.reject{|k| k.to_s.start_with?('A')}',
+  'caller' ]}  # yes, caller is a kernel method that will give a backtrace
+
+# You can also get into trouble so be careful.  The symbols and strings
+# are evaluated in the context of the caller.  Within the string any
+# command or line of code can be given.  SO DO NOT try to use
+# something silly like debug_me{ 'system("rm -fr /")'}
+
+```
+
+## Default Options
+
+The default options is a global constant `DebugMeDefaultOptions` that is outside of the `DebugMe` name space.  I did that so that if you do `include DebugMe` to make access to the method easier you could still have the constant with a function specific name that would be outside of anything that you may have already coded in you program.
+
+Notice that this constant is outside of the DebugMe's module namespace.
 
+```ruby
+DebugMeDefaultOptions = {
+  tag:    'DEBUG',  # A tag to prepend to each output line
+  time:   true,     # Include a time-stamp in front of the tag
+  strftime:  '%Y-%m-%d %H:%M:%S.%6N', # timestamp format
+  header: true,     # Print a header string before printing the variables
+  levels: 0,        # Number of additional backtrack entries to display
+  skip1:  false,    # skip 1 blank line in front of a new output block
+  skip2:  false,    # skip 2 blank lines in front of a new output block
+  lvar:   true,     # Include local variables
+  ivar:   true,     # Include instance variables in the output
+  cvar:   true,     # Include class variables in the output
+  cconst: true,     # Include class constants
+  logger: nil,      # Pass in a logger class instance like Rails.logger
+  file:   $stdout   # The output file
+}
+```
+
+If you want the output of the method to always go to STDERR then do this:
+
+```ruby
+require 'debug_me'
+DebugMeDefaultOptions[:file] = $stderr  # or STDERR
+```
+If you want the `debug_me` output to go to a real file:
+
+```ruby
+DebugMeDefaultOptions[:file] = File.open('debug_me.log', 'w')
+
+```
+
+## Using a Logger class instance
+
+If you are working in Rails and want all the `debug_me` output to go to the Rails.logger its as easy as:
+```ruby
+DebugMeDefaultOptions[:logger] = Rails.logger
+
+```
+
+Or while working in rails you only want to add a marker to the Rails.logger do this:
+```ruby
+debug_me(logger: Rails.logger, tag: 'Hello World')
+```
+
+If you are working in Rails and want to use both the standard `debug_me` functions and occassionally put stuff into the Rails.logger but do not want to always remember the option settings then do something line this in a `config/initializers/aaaaa_debug_me.rb` file:
+
+```ruby
+# config/initializers/aaaaa_debug_me.rb
+
+require 'debug_me'
+
+module DebugMe
+  def log_me(message, options={}, &block)
+    options = {logger: Rails.logger, time: false, header: false, tag: message}
+    block_given? ? debug_me(options, block) : debug_me(options)
+  end
+end
+
+include DebugMe
+
+# Just setup the base name.  The parent path will be added below ...
+debug_me_file_name  = 'debug_me'
+
+# NOTE: you could add a timestamp to the filename
+# debug_me_file_name += '_' + Time.now.strftime('%Y%m%d%H%M%S')
+
+debug_me_file_name += '_' + Process.argv0.gsub('/',' ').split(' ').last
+# NOTE: by using the Process.argv0 ... you get multiple log files for
+#       rails, rake, sidekiq etc.
+
+debug_me_file_name += '.log'
+
+debug_me_filepath = Rails.root + 'log' + debug_me_file_name
+
+debug_me_file = File.open(debug_me_filepath, 'w')
+
+debug_me_file.puts <<~RULER
+
+  ==================== Starting New Test Run --------->>>>>>
+
+RULER
+
+# Set application wide options in the DebugMeDefaultOptions hash
+DebugMeDefaultOptions[:file] = debug_me_file
+
+debug_me{['ENV']}
+
+```
+
+What that does for your Rails application is dump all of your system environment variables and their values to a debug_me log file in the log directory of the application.
+
+It also adds a new method `log_me` which you can use to send stuff to the `Rails.logger` instance.  The method used by `debug_me` for the `logger` instance is always the `debug` method.
+
+## Conclusion
+
+The rest of the default options are obvious.
+
+You can always over-ride the default options on a case by case basis like this:
+
+```
+debug_me {...}
+...
+debug_me(header: false){...}
 ```
 
 ## Contributing

data/debug_me.gemspec

@@ -5,7 +5,7 @@ require 'debug_me/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'debug_me'
-  spec.version       = DebugMe::VERSION
+  spec.version       = DebugMe::DEBUG_ME_VERSION
   spec.authors       = ['Dewayne VanHoozer']
   spec.email         = ['dvanhoozer@gmail.com']
   spec.summary       = 'A tool to print the labeled value of variables.'
@@ -21,6 +21,6 @@ time after time.  I guess that marks me as a geezer.'
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.7'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
 end

data/lib/debug_me.rb

@@ -1,43 +1,66 @@
 require 'pp'
 require_relative 'debug_me/version'
 
+DebugMeDefaultOptions = {
+  tag:    'DEBUG',  # A tag to prepend to each output line
+  time:   true,     # Include a time-stamp in front of the tag
+  strftime:  '%Y-%m-%d %H:%M:%S.%6N', # timestamp format
+  header: true,     # Print a header string before printing the variables
+  levels: 0,        # Number of additional backtrack entries to display
+  skip1:  false,    # skip 1 lines between different outputs
+  skip2:  false,    # skip 2 lines between different outputs
+  lvar:   true,     # Include local variables
+  ivar:   true,     # Include instance variables in the output
+  cvar:   true,     # Include class variables in the output
+  cconst: true,     # Include class constants
+  logger: nil,      # Pass in an instance of logger class like Rails.logger
+                    # must respond_to? :debug
+  file:   $stdout   # The output file
+}
+
 module DebugMe
   def debug_me(options = {}, &block)
-    default_options = {
-      tag: 'DEBUG:',   # A tag to prepend to each output line
-      time: true,      # Include a time-stamp in front of the tag
-      header: true,    # Print a header string before printing the variables
-      lvar: true,      # Include local variables
-      ivar: true,      # Include instance variables in the output
-      cvar: true,      # Include class variables in the output
-      cconst: true,    # Include class constants
-      file: $stdout    # The output file
-    }
-
 
     if 'Hash' == options.class.to_s
-      options = default_options.merge(options)
+      options = DebugMeDefaultOptions.merge(options)
     else
-      options = default_options.merge(tag: options)
+      options = DebugMeDefaultOptions.merge(tag: options)
     end
 
-    out_string = ''
+    skip        = ''
+    skip        = "\n"    if options[:skip1]
+    skip        = "\n\n"  if options[:skip2]
+    out_string  = ''
 
     f = options[:file]
+    l = options[:logger]
     s = ''
-    s += "#{sprintf('%010.6f', Time.now.to_f)} " if options[:time]
-    s += " #{options[:tag]}"
-    wf = caller # where_from under 1.8.6 its a stack trace array under 1.8.7 is a string
-    wf = wf[0] if 'Array' == wf.class.to_s
-
-    out_string = sprintf("%s Source: %s\n",s,wf) if options[:header]
+    s += Time.now.strftime(options[:strftime])+' ' if options[:time]
+    s += "#{options[:tag]}"
+    bt = caller # where_from under 1.8.6 its a stack trace array under 1.8.7+ as a string
+    bt_out = []
 
-    if block_given?
+    if options[:header]
+      cf = bt.is_a?(Array) ? bt[0] : bt
+      out_string = sprintf("%s Source:  %s\n", skip+s, cf)
+      if options[:levels] > 0
+        levels = options[:levels].to_i
+        bt[1..levels].each_with_index do |cff, level |
+          bt_out << [level, cff]
+        end
+      end
+    end
 
-      block_value = [block.call].flatten.compact
+    if block_given? || bt_out.size > 0
+      block_value = []
+      block_value << 'backtrace' if bt_out.size > 0
+      if block_given?
+        [block.call].flatten.compact.each do |v|
+          block_value << v
+        end
+      end
 
       if block_value.empty?
-        block_value = []
         block_value += [eval('local_variables', block.binding)] if options[:lvar]
         block_value += [eval('instance_variables', block.binding)] if options[:ivar]
         block_value += [self.class.send('class_variables')] if options[:cvar]
@@ -48,7 +71,12 @@ module DebugMe
       block_value.map!(&:to_s)
 
       block_value.each do |v|
-        ev = eval("defined?(#{v})",block.binding).nil? ? '<undefined>' : eval(v, block.binding)
+
+        ev  = if 'backtrace' == v
+                bt_out.size > 0 ? bt_out : bt[1..10000]
+              else
+                eval("defined?(#{v})",block.binding).nil? ? '<undefined>' : eval(v, block.binding)
+              end
         out_string += sprintf( "%s %s -=> %s", s,v,ev.pretty_inspect)
       end
 
@@ -59,10 +87,14 @@ module DebugMe
       f.flush
     end
 
+    unless l.nil?
+      l.debug(out_string) if l.respond_to? :debug
+    end
+
     return out_string
   end ## def debug_me( options={}, &block )
 
   # def log_me(msg, opts={})
-  #   debug_me({:tag => msg, :header => false}.merge(opts))
+  #   debug_me({tag: msg, header: false}.merge(opts))
   # end
 end # module DebugMe

data/lib/debug_me/version.rb

@@ -1,3 +1,8 @@
 module DebugMe
-  VERSION = '1.0.2'
+  # I know.  Its weird to duplicate the name space; but,
+  # doing this allows you to include DebugMe in your code
+  # to get direct access to the debug_me method without
+  # poluting your code with an object name that is so
+  # common.
+  DEBUG_ME_VERSION = '1.1.0'
 end

data/tests/debug_me_test.rb

@@ -1,5 +1,9 @@
 #!/usr/bin/env ruby
 
+require 'amazing_print'
+require 'logger'
+require 'pathname'
+
 require_relative '../lib/debug_me'
 include DebugMe
 
@@ -34,6 +38,27 @@ describe DebugMe do
 
   end # describe "source header included" do
 
+
+
+  describe "Add more from the call stack" do
+
+    before do
+      @my_world_view = WorldView.new
+    end
+
+    it 'supports multiple levels from the call stack' do
+      result = @my_world_view.one
+      # debug_me returns everything as one big long string
+      # with embedded new lines.  In the WorldView class
+      # method six is called from five, which is called from four, three, two, one.
+      # The ":levels" options is set to 5 so expect the
+      # normal source header followed by 5 additional
+      # entries from the call stack.
+      assert_equal(result.split("\n").size, 6)
+    end
+  end
+
+
   describe "source header excluded" do
 
   	before do
@@ -224,6 +249,45 @@ describe DebugMe do
 
   end # describe "works with class CONSTANTS" do
 
+  describe "works with a Logger class" do
+
+    it 'default logger class is nil' do
+      DebugMeDefaultOptions[:logger].must_equal nil
+    end
+
+    it 'works with standard ruby Logger class' do
+      logger_output_path = Pathname.pwd + 'logger_class_output.txt'
+      logger_output_path.exist?.must_equal false
+
+      logger        = Logger.new(logger_output_path)
+      logger.level  = Logger::DEBUG
+
+      out_string    = debug_me(
+                                logger: logger,         # Use instance of Ruby's Logger
+                                time:   false,          # turn off debug_me's timestamp
+                                file:   nil,            # don't write to STDOUT the default
+                                tag:    'Hello World'   # say hello
+                              )
+      # Generates an entry like this:
+=begin
+      # Logfile created on 2020-04-27 16:16:38 -0500 by logger.rb/v1.4.2
+      D, [2020-04-27T16:16:38.580889 #54662] DEBUG -- : Hello World Source: debug_me_test.rb:244:in `block (3 levels) in <main>'
+=end
+
+      lines   = logger_output_path.read.split("\n")
+
+      lines.size.must_equal 2
+
+      lines[0].start_with?('# Logfile created on').must_equal   true
+      lines[1].start_with?('D, [').must_equal                   true
+      lines[1].include?('DEBUG').must_equal                     true
+      lines[1].include?('Hello World').must_equal               true
+      lines[1].include?('debug_me_test.rb').must_equal          true
+      lines[1].include?(out_string.chomp).must_equal            true
+
+      logger_output_path.delete
+    end
 
+  end
 
 end # describe DebugMe do

data/tests/world_view.rb

@@ -3,20 +3,23 @@ class WorldView
   A = 1
   B = 2
   C = 3
+
   def initialize
-    @a,@b,@c = 1,2,3
-    @@d, @@e, @@f = 4,5,6
+    @a,@b,@c       = 1,2,3
+    @@d, @@e, @@f   = 4,5,6
   end
+
   def everything
     debug_me(
-      file:nil,
-      header:true,
-      lvar: true,
-      ivar: true,
-      cvar: true,
+      file:   nil,
+      header: true,
+      lvar:   true,
+      ivar:   true,
+      cvar:   true,
       cconst: true
     ){}
   end
+
   def my_constants
     debug_me(
       file:nil,
@@ -26,6 +29,15 @@ class WorldView
       cvar: false,
       cconst: true
     ){}
+  end
+
+  def one;    two;    end
+  def two;    three;  end
+  def three;  four;   end
+  def four;   five;   end
+  def five;   six;    end
 
+  def six
+    debug_me(tag:'How did I get here?', levels: 5)
   end
 end # class WorldView

metadata

@@ -1,63 +1,56 @@
 --- !ruby/object:Gem::Specification
 name: debug_me
 version: !ruby/object:Gem::Version
-  version: 1.0.2
-  prerelease: 
+  version: 1.1.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2015-01-19 00:00:00.000000000 Z
+date: 2021-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
-description: ! 'This thing is pretty old.  There are much better
-
+        version: '0'
+description: |-
+  This thing is pretty old.  There are much better
   ways of debugging in a complex application.  But,
-
   you know, I keep returning to this little method
-
-  time after time.  I guess that marks me as a geezer.'
+  time after time.  I guess that marks me as a geezer.
 email:
 - dvanhoozer@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rultor.yml
+- ".gitignore"
+- ".rultor.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -71,26 +64,24 @@ files:
 homepage: http://github.com/MadBomber/debug_me
 licenses:
 - You want it, its yours
-post_install_message: 
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
-signing_key: 
-specification_version: 3
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
 summary: A tool to print the labeled value of variables.
 test_files: []