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)
      if RUBY_ENGINE == 'opal'
        object.backtrace.each { |line| puts line }
      else
        puts object.full_message
      end
    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]}#{':' if data[:line_number]}#{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
CALLER_DEPTH_ZERO_OPAL =

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

-1 #depth includes pd + with_options method + nested block + build_pd_data method
STACK_TRACE_CALL_LINE_NUMBER_REGEX = 
/\:(\d+)\:in /
STACK_TRACE_CALL_SOURCE_FILE_REGEX = 
/[ ]*([^:]+)\:\d+\:in /
STACK_TRACE_CALL_SOURCE_FILE_REGEX_OPAL = 
/(http[^\)]+)/
OPTIONS = 
[:app_path, :source_line_count, :header, :h, :wrapper, :w, :footer, :f, :printer, :print_engine, :announcer, :formatter, :caller, :run_at]
OPTION_ALIASES = 
{
  a: :announcer,
  c: :caller,
  h: :header,
  f: :footer,
  w: :wrapper,
}

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



302
303
304
 
# File 'lib/puts_debuggerer.rb', line 302

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"



89
90
91
 
# File 'lib/puts_debuggerer.rb', line 89

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'



379
380
381
 
# File 'lib/puts_debuggerer.rb', line 379

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



172
173
174
 
# File 'lib/puts_debuggerer.rb', line 172

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



352
353
354
 
# File 'lib/puts_debuggerer.rb', line 352

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"



134
135
136
 
# File 'lib/puts_debuggerer.rb', line 134

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.



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

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.



244
245
246
 
# File 'lib/puts_debuggerer.rb', line 244

def logging_original_layouts
  @logging_original_layouts
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



210
211
212
 
# File 'lib/puts_debuggerer.rb', line 210

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



469
470
471
 
# File 'lib/puts_debuggerer.rb', line 469

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"



111
112
113
 
# File 'lib/puts_debuggerer.rb', line 111

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



153
154
155
 
# File 'lib/puts_debuggerer.rb', line 153

def wrapper
  @wrapper
end

Class Method Details

.caller? ⇒ Boolean

Returns:

  • (Boolean) 


389
390
391
 
# File 'lib/puts_debuggerer.rb', line 389

def caller?
  !!caller
end

.convert_options(hash) ⇒ Object 



490
491
492
 
# File 'lib/puts_debuggerer.rb', line 490

def convert_options(hash)
  Hash[hash.map { |key, value| OPTION_ALIASES[key] ? ( value == :t ?  [OPTION_ALIASES[key], true] : [OPTION_ALIASES[key], value] ) : [key, value]}]
end

.determine_object(objects) ⇒ Object 



494
495
496
 
# File 'lib/puts_debuggerer.rb', line 494

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

.determine_options(objects) ⇒ Object 



479
480
481
482
483
484
485
486
487
488
 
# File 'lib/puts_debuggerer.rb', line 479

def determine_options(objects)
  if objects.size > 1 && objects.last.is_a?(Hash)
    convert_options(objects.delete_at(-1))
  elsif objects.size == 1 && objects.first.is_a?(Hash)
    hash = objects.first
    convert_options(hash.slice(*OPTIONS).tap do
      hash.delete_if {|option| OPTIONS.include?(option)}
    end)
  end
end

.determine_printer(options) ⇒ Object 



502
503
504
505
506
507
508
 
# File 'lib/puts_debuggerer.rb', line 502

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

.determine_run_at(options) ⇒ Object 



498
499
500
 
# File 'lib/puts_debuggerer.rb', line 498

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



395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/puts_debuggerer.rb', line 395

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



412
413
414
415
416
 
# File 'lib/puts_debuggerer.rb', line 412

def options=(hash)
  hash.each do |option, value|
    send("#{option}=", value)
  end
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]]
]



269
270
271
272
273
274
275
 
# File 'lib/puts_debuggerer.rb', line 269

def print_engine
  if @print_engine.nil?
    require 'awesome_print' if RUBY_ENGINE != 'opal'
    @print_engine = print_engine_default
  end
  @print_engine
end

.print_engine=(engine) ⇒ Object 



277
278
279
280
281
282
283
 
# File 'lib/puts_debuggerer.rb', line 277

def print_engine=(engine)
  if engine.is_a?(Proc) || engine.nil?
    @print_engine = engine
  else
    @print_engine = method(engine).name rescue raise(PRINT_ENGINE_MESSAGE_INVALID)
  end
end

.print_engine_default ⇒ Object 



285
286
287
 
# File 'lib/puts_debuggerer.rb', line 285

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

.printer_default ⇒ Object 



234
235
236
 
# File 'lib/puts_debuggerer.rb', line 234

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

.run_at? ⇒ Boolean

Returns:

  • (Boolean) 


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

def run_at?
  !!@run_at
end