Module: PutsDebuggerer

Defined in:
lib/puts_debuggerer.rb,
lib/puts_debuggerer/source_file.rb,
lib/puts_debuggerer/run_determiner.rb

Defined Under Namespace

Modules: RunDeterminer Classes: SourceFile

Constant Summary collapse

SOURCE_LINE_COUNT_DEFAULT = 
1
HEADER_DEFAULT = 
'*'*80
WRAPPER_DEFAULT = 
'*'*80

'*'*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

:ap
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 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]}#{" (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 =

depth includes pd + with_options method + nested block + build_pd_data method

4
STACK_TRACE_CALL_LINE_NUMBER_REGEX = 
/\:(\d+)\:in /
STACK_TRACE_CALL_SOURCE_FILE_REGEX = 
/[ ]*([^:]+)\:\d+\:in /

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.announcer ⇒ Object

Announcer (e.g. [PD]) to announce every print out with (default: “[PD]”)

Example:

PutsDebuggerer.announcer = "*** PD ***\n  "
pd (x=1)

Prints out:

*** PD ***
   /Users/User/example.rb:2
   > pd x=1
  => 1



294
295
296
 
# File 'lib/puts_debuggerer.rb', line 294

def announcer
  @announcer
end

.app_path ⇒ Object

Application root path to exclude when printing out file path

Example:

# File Name: /Users/User/sample_app/lib/sample.rb
PutsDebuggerer.app_path = '/Users/User/sample_app'
pd (x=1)

Prints out:

[PD] lib/sample.rb:3
   > pd x=1
  => "1"



85
86
87
 
# File 'lib/puts_debuggerer.rb', line 85

def app_path
  @app_path
end

.caller ⇒ Object

Caller backtrace included at the end of every print out Passed an argument of true/false, nil, or depth as an integer.

  • true and -1 means include full caller backtrace

  • false and nil means do not include caller backtrace

  • depth (0-based) means include limited caller backtrace depth

Example:

# File Name: /Users/User/sample_app/lib/sample.rb
PutsDebuggerer.caller = 3
pd (x=1)

Prints out:

[PD] /Users/User/sample_app/lib/sample.rb:3
   > pd x=1
  => "1"
     /Users/User/sample_app/lib/master_samples.rb:368:in `block (3 levels) in <top (required)>'
     /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in `eval'
     /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in `evaluate'
     /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in `evaluate'



371
372
373
 
# File 'lib/puts_debuggerer.rb', line 371

def caller
  @caller
end

.footer ⇒ Object (readonly)

Footer to include at the bottom of every print out.

  • Default value is nil

  • Value true enables footer as ‘’*‘*80`

  • Value false, nil, or empty string disables footer

  • Any other string value gets set as a custom footer

Example:

PutsDebuggerer.footer = true
pd (x=1)

Prints out:

[PD] /Users/User/example.rb:2
   > pd x=1
  => "1"
********************************************************************************



168
169
170
 
# File 'lib/puts_debuggerer.rb', line 168

def footer
  @footer
end

.formatter ⇒ Object

Formatter used in every print out Passed a data argument with the following keys:

  • :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 of print_engine and encapsulates its details. In any case, data for :object is available should one want to avoid altogether.

Example:

PutsDebuggerer.formatter = -> (data) {
  puts "-<#{data[:announcer]}>-"
  puts "HEADER: #{data[:header]}"
  puts "FILE: #{data[:file]}"
  puts "LINE: #{data[:line_number]}"
  puts "EXPRESSION: #{data[:pd_expression]}"
  print "PRINT OUT: "
  data[:object_printer].call
  puts "CALLER: #{data[:caller].to_a.first}"
  puts "FOOTER: #{data[:footer]}"
}
pd (x=1)

Prints out:

-<[PD]>-
FILE: /Users/User/example.rb
HEADER: ********************************************************************************
LINE: 9
EXPRESSION: x=1
PRINT OUT: 1
CALLER: #/Users/User/master_examples.rb:83:in `block (3 levels) in <top (required)>'
FOOTER: ********************************************************************************



344
345
346
 
# File 'lib/puts_debuggerer.rb', line 344

def formatter
  @formatter
end

.header ⇒ Object (readonly)

Header to include at the top of every print out.

  • Default value is nil

  • Value true enables header as ‘’*‘*80`

  • Value false, nil, or empty string disables header

  • Any other string value gets set as a custom header

Example:

PutsDebuggerer.header = true
pd (x=1)

Prints out:

********************************************************************************
[PD] /Users/User/example.rb:2
   > pd x=1
  => "1"



130
131
132
 
# File 'lib/puts_debuggerer.rb', line 130

def header
  @header
end

.logger_original_formatter ⇒ Object (readonly)

Logger original formatter before it was decorated with PutsDebuggerer::LOGGER_FORMATTER_DECORATOR upon setting the logger as a printer.



236
237
238
 
# File 'lib/puts_debuggerer.rb', line 236

def logger_original_formatter
  @logger_original_formatter
end

.logging_original_layouts ⇒ Object (readonly)

Logging library original layouts before being decorated with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR upon setting the Logging library logger as a printer.



240
241
242
 
# File 'lib/puts_debuggerer.rb', line 240

def logging_original_layouts
  @logging_original_layouts
end

.print_engine ⇒ Object

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](github.com/awesome-print/awesome_print).

Example:

# File Name: /Users/User/example.rb
require 'awesome_print'
PutsDebuggerer.print_engine = :p
array = [1, [2, 3]]
pd array

Prints out:

[PD] /Users/User/example.rb:5
   > pd array
  => [1, [2, 3]]
]



265
266
267
 
# File 'lib/puts_debuggerer.rb', line 265

def print_engine
  @print_engine
end

.printer ⇒ Object

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



206
207
208
 
# File 'lib/puts_debuggerer.rb', line 206

def printer
  @printer
end

.run_at ⇒ Object

When to run as specified by an index, array, or range.

  • Default value is nil meaning always

  • Value as an Integer index (1-based) specifies at which run to print once

  • Value as an Array of indices specifies at which runs to print multiple times

  • Value as a range specifies at which runs to print multiple times, indefinitely if it ends with ..-1

Example:

PutsDebuggerer.run_at = 1
pd (x=1) # prints standard PD output
pd (x=1) # prints nothing

PutsDebuggerer.run_at = 2
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output

PutsDebuggerer.run_at = [1, 3]
pd (x=1) # prints standard PD output
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output
pd (x=1) # prints nothing

PutsDebuggerer.run_at = 3..5
pd (x=1) # prints nothing
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output
pd (x=1) # prints standard PD output
pd (x=1) # prints standard PD output
pd (x=1) # prints nothing
pd (x=1) # prints nothing

PutsDebuggerer.run_at = 3...6
pd (x=1) # prints nothing
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output
pd (x=1) # prints standard PD output
pd (x=1) # prints standard PD output
pd (x=1) # prints nothing

PutsDebuggerer.run_at = 3..-1
pd (x=1) # prints nothing
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output
pd (x=1) ... continue printing indefinitely on all subsequent runs

PutsDebuggerer.run_at = 3...-1
pd (x=1) # prints nothing
pd (x=1) # prints nothing
pd (x=1) # prints standard PD output
pd (x=1) ... continue printing indefinitely on all subsequent runs



461
462
463
 
# File 'lib/puts_debuggerer.rb', line 461

def run_at
  @run_at
end

.source_line_count ⇒ Object

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"



107
108
109
 
# File 'lib/puts_debuggerer.rb', line 107

def source_line_count
  @source_line_count
end

.wrapper ⇒ Object (readonly)

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"
********************************************************************************



149
150
151
 
# File 'lib/puts_debuggerer.rb', line 149

def wrapper
  @wrapper
end

Class Method Details

.caller? ⇒ Boolean 



381
382
383
 
# File 'lib/puts_debuggerer.rb', line 381

def caller?
  !!caller
end

.determine_object(objects) ⇒ Object 



475
476
477
 
# File 'lib/puts_debuggerer.rb', line 475

def determine_object(objects)
  objects.compact.size > 1 ? objects : objects.first
end

.determine_options(objects) ⇒ Object 



471
472
473
 
# File 'lib/puts_debuggerer.rb', line 471

def determine_options(objects)    
  objects.delete_at(-1) if objects.size > 1 && objects.last.is_a?(Hash)
end

.determine_printer(options) ⇒ Object 



483
484
485
486
487
488
489
 
# File 'lib/puts_debuggerer.rb', line 483

def determine_printer(options)
  if options && options.has_key?(:printer)
    options[:printer]
  else
    PutsDebuggerer.printer
  end
end

.determine_run_at(options) ⇒ Object 



479
480
481
 
# File 'lib/puts_debuggerer.rb', line 479

def determine_run_at(options)
  ((options && options[:run_at]) || PutsDebuggerer.run_at)
end

.options ⇒ Object

Options as a hash. Useful for reading and backing up options



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/puts_debuggerer.rb', line 387

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,
    caller: caller,
    run_at: run_at
  }
end

.options=(hash) ⇒ Object

Sets options included in hash



404
405
406
407
408
 
# File 'lib/puts_debuggerer.rb', line 404

def options=(hash)
  hash.each do |option, value|
    send("#{option}=", value)
  end
end

.print_engine_default ⇒ Object 



277
278
279
 
# File 'lib/puts_debuggerer.rb', line 277

def print_engine_default
  Object.const_defined?(:AwesomePrint) ? PRINT_ENGINE_DEFAULT : :p    
end

.printer_default ⇒ Object 



230
231
232
 
# File 'lib/puts_debuggerer.rb', line 230

def printer_default
  Object.const_defined?(:Rails) ? PRINTER_RAILS : PRINTER_DEFAULT    
end

.run_at? ⇒ Boolean 



467
468
469
 
# File 'lib/puts_debuggerer.rb', line 467

def run_at?
  !!@run_at
end