module PutsDebuggerer

Constants

ANNOUNCER_DEFAULT
CALLER_DEPTH_ZERO
CALLER_DEPTH_ZERO_OPAL
FORMATTER_DEFAULT
HEADER_DEFAULT
LOGGER_FORMATTER_DECORATOR
LOGGING_LAYOUT_DECORATOR
OBJECT_PRINTER_DEFAULT
OPTIONS
OPTION_ALIASES
PRINTER_DEFAULT
PRINTER_MESSAGE_INVALID
PRINTER_RAILS
RETURN_DEFAULT
SOURCE_LINE_COUNT_DEFAULT
STACK_TRACE_CALL_LINE_NUMBER_REGEX
STACK_TRACE_CALL_SOURCE_FILE_REGEX
STACK_TRACE_CALL_SOURCE_FILE_REGEX_OPAL
WRAPPER_DEFAULT

Attributes

announcer[R]

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
app_path[R]

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"
caller[R]

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'
formatter[R]

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: ********************************************************************************
header[R]

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"
logger_original_formatter[R]

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

logging_original_layouts[R]

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

printer[R]

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
run_at[R]

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
source_line_count[R]

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"
wrapper[R]

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

Public Class Methods

announcer=(text) click to toggle source
# File lib/puts_debuggerer.rb, line 304
def announcer=(text)
  @announcer = text.nil? ? ANNOUNCER_DEFAULT : text
end
app_path=(path) click to toggle source
# File lib/puts_debuggerer.rb, line 91
def app_path=(path)
  @app_path = (path || Rails.root.to_s) rescue nil
end
caller=(value) click to toggle source
# File lib/puts_debuggerer.rb, line 381
def caller=(value)
  if value.equal?(true)
    @caller = -1 #needed for upper bound in pd method
  else
    @caller = value
  end
end
caller?() click to toggle source
# File lib/puts_debuggerer.rb, line 389
def caller?
  !!caller
end
convert_options(hash) click to toggle source
# 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) click to toggle source
# File lib/puts_debuggerer.rb, line 494
def determine_object(objects)
  objects.compact.size > 1 ? objects : objects.first
end
determine_options(objects) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# File lib/puts_debuggerer.rb, line 498
def determine_run_at(options)
  ((options && options[:run_at]) || PutsDebuggerer.run_at)
end
formatter=(formatter_proc) click to toggle source
# File lib/puts_debuggerer.rb, line 354
def formatter=(formatter_proc)
  @formatter = formatter_proc.nil? ? FORMATTER_DEFAULT : formatter_proc
end
options() click to toggle source

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

# 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) click to toggle source

Sets options included in hash

# File lib/puts_debuggerer.rb, line 412
def options=(hash)
  hash.each do |option, value|
    send("#{option}=", value)
  end
end
print_engine() click to toggle source

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]]
]
print_engine=(engine) click to toggle source
print_engine_default() click to toggle source
printer=(printer) click to toggle source
# File lib/puts_debuggerer.rb, line 212
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
    @printer = method(printer).name rescue raise(PRINTER_MESSAGE_INVALID)
  end
end
printer_default() click to toggle source
# File lib/puts_debuggerer.rb, line 234
def printer_default
  Object.const_defined?(:Rails) ? PRINTER_RAILS : PRINTER_DEFAULT
end
run_at=(value) click to toggle source
# File lib/puts_debuggerer.rb, line 471
def run_at=(value)
  @run_at = value
end
run_at?() click to toggle source
# File lib/puts_debuggerer.rb, line 475
def run_at?
  !!@run_at
end
source_line_count=(value) click to toggle source
# File lib/puts_debuggerer.rb, line 113
def source_line_count=(value)
  @source_line_count = value || SOURCE_LINE_COUNT_DEFAULT
end