puts_debuggerer 0.8.1 → 0.10.2

data/lib/puts_debuggerer/core_ext/kernel.rb

@@ -0,0 +1,217 @@
+require 'stringio'
+
+module Kernel
+  # Prints object with bonus info such as file name, line number and source
+  # expression. Optionally prints out header and footer.
+  # Lookup PutsDebuggerer attributes for more details about configuration options.
+  #
+  # Simply invoke global `pd` method anywhere you'd like to see line number and source code with output.
+  # If the argument is a pure string, the print out is simplified by not showing duplicate source.
+  #
+  # Quickly locate printed lines using Find feature (e.g. CTRL+F) by looking for:
+  # * \[PD\]
+  # * file:line_number
+  # * ruby expression.
+  #
+  # This gives you the added benefit of easily removing your pd statements later on from the code.
+  #
+  # Happy puts_debuggerering!
+  #
+  # Example Code:
+  #
+  #   # /Users/User/finance_calculator_app/pd_test.rb # line 1
+  #   bug = 'beattle'                                 # line 2
+  #   pd "Show me the source of the bug: #{bug}"      # line 3
+  #   pd 'What line number am I?'                     # line 4
+  #
+  # Example Printout:
+  #
+  #   [PD] /Users/User/finance_calculator_app/pd_test.rb:3
+  #      > pd "Show me the source of the bug: #{bug}"
+  #     => "Show me the source of the bug: beattle"
+  #   [PD] /Users/User/finance_calculator_app/pd_test.rb:4 "What line number am I?"
+  def pd(*objects)
+    options = PutsDebuggerer.determine_options(objects) || {}
+    object = PutsDebuggerer.determine_object(objects)
+    run_at = PutsDebuggerer.determine_run_at(options)
+    printer = PutsDebuggerer.determine_printer(options)
+    pd_inspect = options.delete(:pd_inspect)
+    logger_formatter_decorated = PutsDebuggerer.printer.is_a?(Logger) && PutsDebuggerer.printer.formatter != PutsDebuggerer.logger_original_formatter
+    logging_layouts_decorated = PutsDebuggerer.printer.is_a?(Logging::Logger) && PutsDebuggerer.printer.appenders.map(&:layout) != (PutsDebuggerer.logging_original_layouts.values)
+  
+    string = nil
+    if PutsDebuggerer::RunDeterminer.run_pd?(object, run_at)
+      __with_pd_options__(options) do |print_engine_options|
+        run_number = PutsDebuggerer::RunDeterminer.run_number(object, run_at)
+        formatter_pd_data = __build_pd_data__(object, print_engine_options: print_engine_options, source_line_count: PutsDebuggerer.source_line_count, run_number: run_number, pd_inspect: pd_inspect, logger_formatter_decorated: logger_formatter_decorated, logging_layouts_decorated: logging_layouts_decorated)
+        stdout = $stdout
+        $stdout = sio = StringIO.new
+        PutsDebuggerer.formatter.call(formatter_pd_data)
+        $stdout = stdout
+        string = sio.string
+        if PutsDebuggerer.printer.is_a?(Proc)
+          PutsDebuggerer.printer.call(string)
+        elsif PutsDebuggerer.printer.is_a?(Logger)
+          logger_formatter = PutsDebuggerer.printer.formatter
+          begin
+            PutsDebuggerer.printer.formatter = PutsDebuggerer.logger_original_formatter
+            PutsDebuggerer.printer.debug(string)
+          ensure
+            PutsDebuggerer.printer.formatter = logger_formatter
+          end
+        elsif PutsDebuggerer.printer.is_a?(Logging::Logger)
+          logging_layouts = PutsDebuggerer.printer.appenders.reduce({}) do |hash, appender|
+            hash.merge(appender => appender.layout)
+          end
+          begin
+            PutsDebuggerer.logging_original_layouts.each do |appender, original_layout|
+              appender.layout = original_layout
+            end
+            PutsDebuggerer.printer.debug(string)
+          ensure
+            PutsDebuggerer.logging_original_layouts.each do |appender, original_layout|
+              appender.layout = logging_layouts[appender]
+            end
+          end        
+        elsif PutsDebuggerer.printer != false
+          send(PutsDebuggerer.send(:printer), string)
+        end
+      end
+    end
+  
+    printer ? object : string
+  end
+
+  # Implement caller backtrace method in Opal since it returns an empty array in Opal v1
+  if RUBY_PLATFORM == 'opal'
+    def caller
+      begin
+        raise 'error'
+      rescue => e
+        e.backtrace[2..-1]
+      end
+    end
+  end
+  
+  def pd_inspect
+    pd self, printer: false, pd_inspect: true
+  end
+  alias pdi pd_inspect
+  
+  # Provides caller line number starting 1 level above caller of
+  # this method.
+  #
+  # Example:
+  #
+  #   # lib/example.rb                        # line 1
+  #   puts "Print out __caller_line_number__" # line 2
+  #   puts __caller_line_number__             # line 3
+  #
+  # prints out `3`
+  def __caller_line_number__(caller_depth=0)
+    return if RUBY_PLATFORM == 'opal'
+    caller[caller_depth] && caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_LINE_NUMBER_REGEX, 1].to_i
+  end
+  
+  # Provides caller file starting 1 level above caller of
+  # this method.
+  #
+  # Example:
+  #
+  #   # File Name: lib/example.rb
+  #   puts __caller_file__
+  #
+  # prints out `lib/example.rb`
+  def __caller_file__(caller_depth=0)
+    regex = RUBY_PLATFORM == 'opal' ? PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX_OPAL : PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX
+    caller[caller_depth] && caller[caller_depth][regex, 1]  
+  end
+  
+  
+  # Provides caller source line starting 1 level above caller of
+  # this method.
+  #
+  # Example:
+  #
+  #   puts __caller_source_line__
+  #
+  # prints out `puts __caller_source_line__`
+  def __caller_source_line__(caller_depth=0, source_line_count=nil, source_file=nil, source_line_number=nil)
+    source_line_number ||= __caller_line_number__(caller_depth+1)
+    source_file ||= __caller_file__(caller_depth+1)
+    source_line = ''
+    if source_file == '(irb)'
+      source_line = conf.io.line(source_line_number) # TODO handle multi-lines in source_line_count
+    else
+      source_line = PutsDebuggerer::SourceFile.new(source_file).source(source_line_count, source_line_number)
+    end
+    source_line
+  end
+  
+  private
+  
+  def __with_pd_options__(options=nil)
+    options ||= {}
+    permanent_options = PutsDebuggerer.options
+    PutsDebuggerer.options = options.select {|option, _| PutsDebuggerer.options.keys.include?(option)}
+    print_engine_options = options.delete_if {|option, _| PutsDebuggerer.options.keys.include?(option)}
+    yield print_engine_options
+    PutsDebuggerer.options = permanent_options
+  end
+  
+  def __build_pd_data__(object, print_engine_options:nil, source_line_count:nil, run_number:nil, pd_inspect:false, logger_formatter_decorated:false, logging_layouts_decorated:false)
+    depth = RUBY_PLATFORM == 'opal' ? PutsDebuggerer::CALLER_DEPTH_ZERO_OPAL : PutsDebuggerer::CALLER_DEPTH_ZERO
+    if pd_inspect
+      depth += 1
+      depth += 4 if logger_formatter_decorated
+      depth += 8 if logging_layouts_decorated
+    end
+  
+    pd_data = {
+      announcer: PutsDebuggerer.announcer,
+      file: __caller_file__(depth)&.sub(PutsDebuggerer.app_path.to_s, ''),
+      line_number: __caller_line_number__(depth),
+      pd_expression: __caller_pd_expression__(depth, source_line_count),
+      run_number: run_number,
+      object: object,
+      object_printer: PutsDebuggerer::OBJECT_PRINTER_DEFAULT.call(object, print_engine_options, source_line_count, run_number)
+    }
+    pd_data[:caller] = __caller_caller__(depth)
+    ['header', 'wrapper', 'footer'].each do |boundary_option| 
+      pd_data[boundary_option.to_sym] = PutsDebuggerer.send(boundary_option) if PutsDebuggerer.send("#{boundary_option}?")
+    end
+    pd_data
+  end
+  
+  # Returns the caller stack trace of the caller of pd
+  def __caller_caller__(depth)
+    return unless PutsDebuggerer.caller?
+    start_depth = depth.to_i + 1
+    caller_depth = PutsDebuggerer.caller == -1 ? -1 : (start_depth + PutsDebuggerer.caller)
+    caller[start_depth..caller_depth].to_a
+  end
+  
+  def __format_pd_expression__(expression, object)
+    "\n   > #{expression}\n  =>"
+  end
+  
+  def __caller_pd_expression__(depth=0, source_line_count=nil)
+    # Caller Source Line Depth 2 = 1 to pd method + 1 to caller
+    source_line = __caller_source_line__(depth+1, source_line_count)
+    source_line = __extract_pd_expression__(source_line)
+    source_line = source_line.gsub(/(^'|'$)/, '"') if source_line.start_with?("'") && source_line.end_with?("'")
+    source_line = source_line.gsub(/(^\(|\)$)/, '') if source_line.start_with?("(") && source_line.end_with?(")")
+    source_line
+  end
+  
+  # Extracts pd source line expression.
+  #
+  # Example:
+  #
+  # __extract_pd_expression__("pd (x=1)")
+  #
+  # outputs `(x=1)`
+  def __extract_pd_expression__(source_line)
+    source_line.to_s.strip
+  end  
+end

data/lib/puts_debuggerer/core_ext/logger.rb

@@ -0,0 +1,3 @@
+# in case 'logger' is not required
+class Logger 
+end

data/lib/puts_debuggerer/core_ext/logging/logger.rb

@@ -0,0 +1,5 @@
+# in case 'logging' is not required
+module Logging
+  class Logger
+  end
+end

data/lib/puts_debuggerer/run_determiner.rb

@@ -0,0 +1,109 @@
+module PutsDebuggerer
+  module RunDeterminer
+    OBJECT_RUN_AT = {}
+
+    class << self
+      attr_reader :run_at_global_number
+  
+      def run_at_global_number=(value)
+        @run_at_global_number = value
+      end
+  
+      def init_run_at_global_number
+        @run_at_global_number = 1
+      end
+  
+      def increment_run_at_global_number
+        @run_at_global_number += 1
+      end
+  
+      def reset_run_at_global_number
+        @run_at_global_number = nil
+      end
+  
+      def run_at_number(object, run_at)
+        OBJECT_RUN_AT[[object,run_at]]
+      end
+  
+      def init_run_at_number(object, run_at)
+        OBJECT_RUN_AT[[object,run_at]] = 1
+      end
+  
+      def increment_run_at_number(object, run_at)
+        OBJECT_RUN_AT[[object,run_at]] += 1
+      end
+  
+      def reset_run_at_number(object, run_at)
+        OBJECT_RUN_AT.delete([object, run_at])
+      end
+  
+      def reset_run_at_numbers
+        OBJECT_RUN_AT.clear
+      end
+      
+      def run_number(object, run_at)
+        run_at_global_number || run_at_number(object, run_at)      
+      end            
+            
+      def run_pd?(object, run_at)
+        run_pd = false
+        if run_at.nil?
+          run_pd = true
+        else
+          run_number = determine_run_number(object, run_at) 
+          run_pd = determine_run_pd(run_at, run_number)
+        end
+        run_pd
+      end      
+      
+      def determine_run_number(object, run_at)
+        if PutsDebuggerer.run_at? # check if global option is set
+          determine_global_run_number
+        else
+          determine_local_run_number(object, run_at)
+        end
+      end
+      
+      def determine_global_run_number
+        if PutsDebuggerer::RunDeterminer.run_at_global_number.nil?
+          PutsDebuggerer::RunDeterminer.init_run_at_global_number
+        else
+          PutsDebuggerer::RunDeterminer.increment_run_at_global_number
+        end
+        PutsDebuggerer::RunDeterminer.run_at_global_number      
+      end
+      
+      def determine_local_run_number(object, run_at)
+        if PutsDebuggerer::RunDeterminer.run_at_number(object, run_at).nil?
+          PutsDebuggerer::RunDeterminer.init_run_at_number(object, run_at)
+        else
+          PutsDebuggerer::RunDeterminer.increment_run_at_number(object, run_at)
+        end
+        PutsDebuggerer::RunDeterminer.run_at_number(object, run_at)
+      end
+      
+      def determine_run_pd(run_at, run_number)
+        if run_at.is_a?(Integer)
+          determine_run_pd_integer(run_at, run_number)
+        elsif run_at.is_a?(Array)
+          determine_run_pd_array(run_at, run_number)
+        elsif run_at.is_a?(Range)
+          determine_run_pd_range(run_at, run_number)
+        end      
+      end
+      
+      def determine_run_pd_integer(run_at, run_number)
+        run_pd = true if run_at == run_number      
+      end
+      
+      def determine_run_pd_array(run_at, run_number)
+        run_pd = true if run_at.include?(run_number)
+      end
+      
+      def determine_run_pd_range(run_at, run_number)
+        run_pd = true if run_at.cover?(run_number) || (run_at.end == -1 && run_number >= run_at.begin)
+      end
+      
+    end
+  end
+end

data/lib/puts_debuggerer/source_file.rb

@@ -0,0 +1,32 @@
+module PutsDebuggerer
+  class SourceFile  
+    def initialize(file_path)
+      @file = File.new(file_path) if file_path
+    end
+    
+    def source(source_line_count, source_line_number)
+      @source = ''      
+      return @source if RUBY_PLATFORM == 'opal'
+      # For Opal Ruby compatibility, skip source lines if file does not respond to readline (as in Opal)
+      lines = source_lines(source_line_count, source_line_number)
+      @source = lines.join(' '*5) if @file.respond_to?(:readline)
+      @source    
+    end
+    
+    def source_lines(source_line_count, source_line_number)
+      lines = []
+      begin
+        while @file.lineno < source_line_number + source_line_count
+          file_line_number = @file.lineno + 1
+          file_line = @file.readline
+          if file_line_number >= source_line_number && file_line_number < source_line_number + source_line_count
+            lines << file_line
+          end
+        end
+      rescue EOFError
+        # Done
+      end
+      lines
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puts_debuggerer
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.10.2
 platform: ruby
 authors:
 - Andy Maleh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-06-30 00:00:00.000000000 Z
+date: 2020-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -67,86 +67,145 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
 - !ruby/object:Gem::Dependency
-  name: jeweler
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.16.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: undercover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.3.4
+- !ruby/object:Gem::Dependency
+  name: logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: rake-tui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
-  Yes, many of us avoid debuggers like the plague and clamp on to our puts statements like an umbrella in a stormy day. Why not make it official and have puts debugging become its own perfectly legitimate thing?!!
-
-  Enter puts_debuggerer. A guilt-free puts debugger Ruby gem FTW!
-
-  In other words, puts_debuggerer is a Ruby library for improved puts debugging, automatically displaying bonus useful information such as source line number and source code.
-
-  Partially inspired (only partially ;) by this blog post:
-  https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
-  (Credit to Tenderlove.)
+  Debuggers are great! They help us troubleshoot complicated programming problems by inspecting values produced by code, line by line. They are invaluable when trying to understand what is going on in a large application composed of thousands or millions of lines of code.
+  In day-to-day test-driven development and simple debugging though, a puts statement can be a lot quicker in revealing what is going on than halting execution completely just to inspect a single value or a few. This is certainly true when writing the simplest possible code that could possibly work, and running a test every few seconds or minutes. Problem is you need to locate puts statements in large output logs, know which methods were invoked, find out what variable names are being printed, and see nicely formatted output. Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, and formats output nicely courtesy of awesome_print.
+  Partially inspired by this blog post: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html (Credit to Tenderlove.)
 email: andy.am@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
+- VERSION
+- lib/pd.rb
 - lib/puts_debuggerer.rb
+- lib/puts_debuggerer/core_ext/kernel.rb
+- lib/puts_debuggerer/core_ext/logger.rb
+- lib/puts_debuggerer/core_ext/logging/logger.rb
+- lib/puts_debuggerer/run_determiner.rb
+- lib/puts_debuggerer/source_file.rb
 homepage: http://github.com/AndyObtiva/puts_debuggerer
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,9 +220,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.10
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Ruby library for improved puts debugging, automatically displaying bonus
   useful information such as source line number and source code.