puts_debuggerer 0.7.1 → 0.10.0

data/VERSION

@@ -0,0 +1 @@
+0.10.0

data/lib/pd.rb

@@ -0,0 +1 @@
+require 'puts_debuggerer'

data/lib/puts_debuggerer.rb

@@ -1,21 +1,70 @@
-require 'ripper'
-require 'awesome_print'
+require 'stringio'
+
+require 'puts_debuggerer/core_ext/kernel'
+require 'puts_debuggerer/run_determiner'
+require 'puts_debuggerer/source_file'
+
+# in case 'logger' is not required
+class Logger 
+end
+
+# in case 'logging' is not required
+module Logging
+  class Logger
+  end
+end
 
 module PutsDebuggerer
+  SOURCE_LINE_COUNT_DEFAULT = 1
   HEADER_DEFAULT = '*'*80
+  WRAPPER_DEFAULT = '*'*80
   FOOTER_DEFAULT = '*'*80
+  LOGGER_FORMATTER_DECORATOR = proc { |original_formatter|
+    proc { |severity, datetime, progname, msg|
+      original_formatter.call(severity, datetime, progname, msg.pd_inspect)
+    }
+  }
+  LOGGING_LAYOUT_DECORATOR = proc {|original_layout|
+    original_layout.clone.tap do |layout|
+      layout.singleton_class.class_eval do
+        alias original_format_obj format_obj
+        def format_obj(obj)
+          obj.pdi # alias to pd_inspect
+        end
+      end
+    end
+  }
+  RETURN_DEFAULT = true
+  OBJECT_PRINTER_DEFAULT = lambda do |object, print_engine_options=nil, source_line_count=nil, run_number=nil|
+    lambda do
+      if object.is_a?(Exception) && object.respond_to?(:full_message)
+        puts object.full_message
+      elsif PutsDebuggerer.print_engine.is_a?(Proc)
+        PutsDebuggerer.print_engine.call(object)
+      else
+        send(PutsDebuggerer.print_engine, object)
+      end
+    end
+  end
+  PRINTER_DEFAULT = :puts
+  PRINTER_RAILS = lambda do |output|
+    puts output if Rails.env.test?
+    Rails.logger.debug(output)
+  end
   PRINT_ENGINE_DEFAULT = :ap
-  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p or :puts) or lambda/proc'
+  PRINTER_MESSAGE_INVALID = 'printer must be a valid global method symbol (e.g. :puts), a logger, or a lambda/proc receiving a text arg'
+  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p, :ap or :pp) or lambda/proc receiving an object arg'
   ANNOUNCER_DEFAULT = '[PD]'
   FORMATTER_DEFAULT = -> (data) {
+      puts data[:wrapper] if data[:wrapper]
       puts data[:header] if data[:header]
-      print "#{data[:announcer]} #{data[:file]}:#{data[:line_number]}#{__format_pd_expression__(data[:pd_expression], data[:object])} "
+      print "#{data[:announcer]} #{data[:file]}:#{data[:line_number]}#{" (run:#{data[:run_number]})" if data[:run_number]}#{__format_pd_expression__(data[:pd_expression], data[:object])} "
       data[:object_printer].call
       puts data[:caller].map {|l| '     ' + l} unless data[:caller].to_a.empty?
       puts data[:footer] if data[:footer]
+      puts data[:wrapper] if data[:wrapper]
     }
   CALLER_DEPTH_ZERO = 4 #depth includes pd + with_options method + nested block + build_pd_data method
-  OBJECT_RUN_AT = {}
   STACK_TRACE_CALL_LINE_NUMBER_REGEX = /\:(\d+)\:in /
   STACK_TRACE_CALL_SOURCE_FILE_REGEX = /[ ]*([^:]+)\:\d+\:in /
 
@@ -39,6 +88,28 @@ module PutsDebuggerer
       @app_path = (path || Rails.root.to_s) rescue nil
     end
 
+    # Source Line Count.
+    # * Default value is `1`
+    #
+    # Example:
+    #
+    #   PutsDebuggerer.source_line_count = 2
+    #   pd (true ||
+    #     false), source_line_count: 2
+    #
+    # Prints out:
+    #
+    #   ********************************************************************************
+    #   [PD] /Users/User/example.rb:2
+    #      > pd (true ||
+    #          false), source_line_count: 2
+    #     => "true"
+    attr_reader :source_line_count
+
+    def source_line_count=(value)
+      @source_line_count = value || SOURCE_LINE_COUNT_DEFAULT
+    end
+
     # Header to include at the top of every print out.
     # * Default value is `nil`
     # * Value `true` enables header as `'*'*80`
@@ -58,19 +129,24 @@ module PutsDebuggerer
     #     => "1"
     attr_reader :header
 
-    def header=(value)
-      if value.equal?(true)
-        @header = HEADER_DEFAULT
-      elsif value == ''
-        @header = nil
-      else
-        @header = value
-      end
-    end
-
-    def header?
-      !!@header
-    end
+    # Wrapper to include at the top and bottom of every print out (both header and footer).
+    # * Default value is `nil`
+    # * Value `true` enables wrapper as `'*'*80`
+    # * Value `false`, `nil`, or empty string disables wrapper
+    # * Any other string value gets set as a custom wrapper
+    #
+    # Example:
+    #
+    #   PutsDebuggerer.wrapper = true
+    #   pd (x=1)
+    #
+    # Prints out:
+    #
+    #   [PD] /Users/User/example.rb:2
+    #      > pd x=1
+    #     => "1"
+    #   ********************************************************************************
+    attr_reader :wrapper
 
     # Footer to include at the bottom of every print out.
     # * Default value is `nil`
@@ -90,25 +166,87 @@ module PutsDebuggerer
     #     => "1"
     #   ********************************************************************************
     attr_reader :footer
+    
+    ['header', 'footer', 'wrapper'].each do |boundary_option|
+      define_method("#{boundary_option}=") do |value|
+        if value.equal?(true)
+          instance_variable_set(:"@#{boundary_option}", const_get(:"#{boundary_option.upcase}_DEFAULT"))
+        elsif value == ''
+          instance_variable_set(:"@#{boundary_option}", nil)
+        else
+          instance_variable_set(:"@#{boundary_option}", value)
+        end      
+      end
+      
+      define_method("#{boundary_option}?") do
+        !!instance_variable_get(:"@#{boundary_option}")
+      end
+    end
 
-    def footer=(value)
-      if value.equal?(true)
-        @footer = FOOTER_DEFAULT
-      elsif value == ''
-        @footer = nil
+    # Printer is a global method symbol, lambda expression, or logger to use in printing to the user.
+    # Examples of a global method are `:puts` and `:print`.
+    # An example of a lambda expression is `lambda {|output| Rails.logger.ap(output)}`
+    # Examples of a logger are a Ruby `Logger` instance or `Logging::Logger` instance
+    #
+    # Defaults to `:puts`
+    # In Rails, it defaults to: `lambda {|output| Rails.logger.ap(output)}`
+    #
+    # Example:
+    #
+    # # File Name: /Users/User/example.rb
+    # PutsDebuggerer.printer = lambda {|output| Rails.logger.error(output)}
+    # str = "Hello"
+    # pd str
+    #
+    # Prints out in the Rails app log as error lines:
+    #
+    # [PD] /Users/User/example.rb:5
+    #    > pd str
+    #   => Hello
+    attr_reader :printer
+
+    def printer=(printer)
+      if printer.nil?
+        @printer = printer_default
+      elsif printer.is_a?(Logger)
+        @printer = printer
+        @logger_original_formatter = printer.formatter || Logger::Formatter.new
+        printer.formatter = LOGGER_FORMATTER_DECORATOR.call(@logger_original_formatter)
+      elsif printer.is_a?(Logging::Logger)
+        @printer = printer
+        @logging_original_layouts = printer.appenders.reduce({}) do |hash, appender|
+          hash.merge(appender => appender.layout)
+        end
+        printer.appenders.each do |appender|
+          appender.layout = LOGGING_LAYOUT_DECORATOR.call(appender.layout)
+        end
+      elsif printer == false || printer.is_a?(Proc) || printer.respond_to?(:log) # a logger
+        @printer = printer
       else
-        @footer = value
+        @printer = method(printer).name rescue raise(PRINTER_MESSAGE_INVALID)
       end
     end
-
-    def footer?
-      !!@footer
+    
+    def printer_default
+      Object.const_defined?(:Rails) ? PRINTER_RAILS : PRINTER_DEFAULT    
     end
-
-    # Print engine to use in object printout (e.g. `p`, `ap`, `pp`).
-    # It is represented by the print engine's global method name as a symbol
-    # (e.g. `:ap` for awesome_print).
-    # Defaults to awesome_print loaded.
+    
+    # Logger original formatter before it was decorated with PutsDebuggerer::LOGGER_FORMATTER_DECORATOR 
+    # upon setting the logger as a printer.
+    attr_reader :logger_original_formatter
+    
+    # Logging library original layouts before being decorated with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR
+    # upon setting the Logging library logger as a printer.
+    attr_reader :logging_original_layouts
+
+    # Print engine is similar to `printer`, except it is focused on the scope of formatting
+    # the data object being printed (excluding metadata such as file name, line number,
+    # and expression, which are handled by the `printer`).
+    # As such, it is also a global method symbol or lambda expression.
+    # Examples of global methods are `:p`, `:ap`, and `:pp`.
+    # An example of a lambda expression is `lambda {|object| puts object.to_a.join(" | ")}`
+    #
+    # Defaults to [awesome_print](https://github.com/awesome-print/awesome_print).
     #
     # Example:
     #
@@ -128,17 +266,17 @@ module PutsDebuggerer
 
     def print_engine=(engine)
       if engine.nil?
-        if Object.const_defined?(:Rails)
-          @print_engine = lambda {|object| Rails.logger.ap(object)}
-        else
-          @print_engine = PRINT_ENGINE_DEFAULT
-        end
+        @print_engine = print_engine_default
       elsif engine.is_a?(Proc)
         @print_engine = engine
       else
         @print_engine = method(engine).name rescue raise(PRINT_ENGINE_MESSAGE_INVALID)
       end
     end
+    
+    def print_engine_default
+      Object.const_defined?(:AwesomePrint) ? PRINT_ENGINE_DEFAULT : :p    
+    end
 
     # Announcer (e.g. [PD]) to announce every print out with (default: "[PD]")
     #
@@ -164,12 +302,14 @@ module PutsDebuggerer
     # * :announcer (string)
     # * :caller (array)
     # * :file (string)
+    # * :wrapper (string)
     # * :footer (string)
     # * :header (string)
     # * :line_number (string)
     # * :pd_expression (string)
     # * :object (object)
     # * :object_printer (proc)
+    # * :source_line_count (integer)
     #
     # NOTE: data for :object_printer is not a string, yet a proc that must
     # be called to output value. It is a proc as it automatically handles usage
@@ -247,8 +387,11 @@ module PutsDebuggerer
     def options
       {
         header: header,
+        wrapper: wrapper,
         footer: footer,
+        printer: printer,
         print_engine: print_engine,
+        source_line_count: source_line_count,
         app_path: app_path,
         announcer: announcer,
         formatter: formatter,
@@ -325,53 +468,37 @@ module PutsDebuggerer
       !!@run_at
     end
 
-    attr_reader :run_at_global_number
-
-    def run_at_global_number=(value)
-      @run_at_global_number = value
+    def determine_options(objects)    
+      objects.delete_at(-1) if objects.size > 1 && objects.last.is_a?(Hash)
     end
 
-    def init_run_at_global_number(object, run_at)
-      @run_at_global_number = 1
+    def determine_object(objects)
+      objects.compact.size > 1 ? objects : objects.first
     end
 
-    def increment_run_at_global_number(object, run_at)
-      @run_at_global_number += 1
+    def determine_run_at(options)
+      ((options && options[:run_at]) || PutsDebuggerer.run_at)
     end
 
-    def reset_run_at_global_number(object, run_at)
-      @run_at_global_number = nil
-    end
-
-    def run_at_number(object, run_at)
-      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]]
-    end
-
-    def init_run_at_number(object, run_at)
-      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]] = 1
-    end
-
-    def increment_run_at_number(object, run_at)
-      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]] += 1
-    end
-
-    def reset_run_at_number(object, run_at)
-      PutsDebuggerer::OBJECT_RUN_AT.delete([object, run_at])
-    end
-
-    def reset_run_at_numbers
-      PutsDebuggerer::OBJECT_RUN_AT.clear
+    def determine_printer(options)
+      if options && options.has_key?(:printer)
+        options[:printer]
+      else
+        PutsDebuggerer.printer
+      end
     end
-
   end
 end
 
-PutsDebuggerer.print_engine = PutsDebuggerer::PRINT_ENGINE_DEFAULT
-PutsDebuggerer.announcer = PutsDebuggerer::ANNOUNCER_DEFAULT
-PutsDebuggerer.formatter = PutsDebuggerer::FORMATTER_DEFAULT
+# setting values to nil defaults them properly
+PutsDebuggerer.printer = nil
+PutsDebuggerer.print_engine = nil
+PutsDebuggerer.announcer = nil
+PutsDebuggerer.formatter = nil
 PutsDebuggerer.app_path = nil
 PutsDebuggerer.caller = nil
 PutsDebuggerer.run_at = nil
+PutsDebuggerer.source_line_count = nil
 
 # Prints object with bonus info such as file name, line number and source
 # expression. Optionally prints out header and footer.
@@ -402,48 +529,57 @@ PutsDebuggerer.run_at = nil
 #      > 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(object, options=nil)
-  run_at = ((options && options[:run_at]) || PutsDebuggerer.run_at)
-
-  if __run_pd__(object, run_at)
+def pd(*objects)
+  require 'awesome_print' if ['awesome_print', 'ap'].include?(PutsDebuggerer.print_engine.to_s) && RUBY_PLATFORM != 'opal'
+  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|
-      formatter_pd_data = __build_pd_data__(object, print_engine_options) #depth adds build method
+      run_number = PutsDebuggerer::RunDeterminer.run_number(object, run_at)
+      formatter_pd_data = __build_pd_data__(object, print_engine_options, PutsDebuggerer.source_line_count, run_number, pd_inspect, logger_formatter_decorated, logging_layouts_decorated) #depth adds build method
+      stdout = $stdout
+      $stdout = sio = StringIO.new
       PutsDebuggerer.formatter.call(formatter_pd_data)
-    end
-  end
-
-  object
-end
-
-def __run_pd__(object, run_at)
-  run_pd = false
-  if run_at.nil?
-    run_pd = true
-  else
-    if PutsDebuggerer.run_at_global_number.nil?
-      if PutsDebuggerer.run_at_number(object, run_at).nil?
-        PutsDebuggerer.init_run_at_number(object, run_at)
-      else
-        PutsDebuggerer.increment_run_at_number(object, run_at)
-      end
-      run_number = PutsDebuggerer.run_at_number(object, run_at)
-    else
-      if PutsDebuggerer.run_at_global_number.nil?
-        PutsDebuggerer.init_run_at_global_number
-      else
-        PutsDebuggerer.increment_run_at_global_number
+      $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
-      run_number = PutsDebuggerer.run_at_global_number
-    end
-    if run_at.is_a?(Integer)
-      run_pd = true if run_at == run_number
-    elsif run_at.is_a?(Array)
-      run_pd = true if run_at.include?(run_number)
-    elsif run_at.is_a?(Range)
-      run_pd = true if run_at.cover?(run_number) || (run_at.end == -1 && run_number >= run_at.begin)
     end
   end
-  run_pd
+
+  printer ? object : string
 end
 
 # Provides caller line number starting 1 level above caller of
@@ -457,7 +593,7 @@ end
 #
 # prints out `3`
 def __caller_line_number__(caller_depth=0)
-  caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_LINE_NUMBER_REGEX, 1].to_i
+  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
@@ -470,7 +606,7 @@ end
 #
 # prints out `lib/example.rb`
 def __caller_file__(caller_depth=0)
-  caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]
+  result = caller[caller_depth] && caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]  
 end
 
 
@@ -482,23 +618,14 @@ end
 #   puts __caller_source_line__
 #
 # prints out `puts __caller_source_line__`
-def __caller_source_line__(caller_depth=0, source_file=nil, source_line_number=nil)
+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 = nil
+  source_line = ''
   if source_file == '(irb)'
-    source_line = conf.io.line(source_line_number)
+    source_line = conf.io.line(source_line_number) # TODO handle multi-lines in source_line_count
   else
-    f = File.new(source_file)
-    source_line = ''
-    done = false
-    f.each_line do |line|
-      if !done && f.lineno == source_line_number
-        source_line << line
-        done = true if Ripper.sexp_raw(source_line) || source_line.include?('%>') #the last condition is for erb support (unofficial)
-        source_line_number+=1
-      end
-    end
+    source_line = PutsDebuggerer::SourceFile.new(source_file).source(source_line_count, source_line_number)
   end
   source_line
 end
@@ -514,43 +641,42 @@ def __with_pd_options__(options=nil)
   PutsDebuggerer.options = permanent_options
 end
 
-def __build_pd_data__(object, print_engine_options=nil)
+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 = PutsDebuggerer::CALLER_DEPTH_ZERO
+  depth += 1 if pd_inspect
+  depth += 4 if pd_inspect && logger_formatter_decorated
+  depth += 8 if pd_inspect && logging_layouts_decorated
   pd_data = {
     announcer: PutsDebuggerer.announcer,
-    file: __caller_file__(depth).sub(PutsDebuggerer.app_path.to_s, ''),
+    file: __caller_file__(depth)&.sub(PutsDebuggerer.app_path.to_s, ''),
     line_number: __caller_line_number__(depth),
-    pd_expression: __caller_pd_expression__(depth),
+    pd_expression: __caller_pd_expression__(depth, source_line_count),
+    run_number: run_number,
     object: object,
-    object_printer: lambda do
-      if PutsDebuggerer.print_engine.is_a?(Proc)
-        PutsDebuggerer.print_engine.call(object)
-      else
-        if print_engine_options.to_h.empty?
-          send(PutsDebuggerer.print_engine, object)
-        else
-          send(PutsDebuggerer.print_engine, object, print_engine_options) rescue send(PutsDebuggerer.print_engine, object)
-        end
-      end
-    end
+    object_printer: PutsDebuggerer::OBJECT_PRINTER_DEFAULT.call(object, print_engine_options, source_line_count, run_number)
   }
-  if PutsDebuggerer.caller?
-    start_depth = depth.to_i
-    caller_depth = PutsDebuggerer.caller == -1 ? -1 : (start_depth + PutsDebuggerer.caller)
-    pd_data[:caller] = caller[start_depth..caller_depth].to_a
+  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[:header] = PutsDebuggerer.header if PutsDebuggerer.header?
-  pd_data[:footer] = PutsDebuggerer.footer if PutsDebuggerer.footer?
   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)
+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 = __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?(")")
@@ -565,5 +691,5 @@ end
 #
 # outputs `(x=1)`
 def __extract_pd_expression__(source_line)
-  source_line.strip
+  source_line.to_s.strip
 end