module PutsDebuggerer
Constants
- ANNOUNCER_DEFAULT
- CALLER_DEPTH_ZERO
- CALLER_DEPTH_ZERO_OPAL
- FOOTER_DEFAULT
- FORMATTER_DEFAULT
- HEADER_DEFAULT
- LOGGER_FORMATTER_DECORATOR
- LOGGING_LAYOUT_DECORATOR
- OBJECT_PRINTER_DEFAULT
- OPTIONS
- OPTION_ALIASES
- PRINTER_DEFAULT
- PRINTER_MESSAGE_INVALID
- PRINTER_RAILS
- PRINT_ENGINE_DEFAULT
- PRINT_ENGINE_MESSAGE_INVALID
- 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 (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
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 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 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 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 before it was decorated with PutsDebuggerer::LOGGER_FORMATTER_DECORATOR
upon setting the logger as a printer.
Logging
library original layouts before being decorated with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR
upon setting the Logging
library logger as a printer.
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
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.
-
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 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
# File lib/puts_debuggerer.rb, line 304 def announcer=(text) @announcer = text.nil? ? ANNOUNCER_DEFAULT : text end
# File lib/puts_debuggerer.rb, line 91 def app_path=(path) @app_path = (path || Rails.root.to_s) rescue nil end
# 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
# File lib/puts_debuggerer.rb, line 389 def caller? !!caller end
# 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
# File lib/puts_debuggerer.rb, line 494 def determine_object(objects) objects.compact.size > 1 ? objects : objects.first end
# 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
# File lib/puts_debuggerer.rb, line 502 def determine_printer(options) if options && options.has_key?(:printer) options[:printer] else PutsDebuggerer.printer end end
# File lib/puts_debuggerer.rb, line 498 def determine_run_at(options) ((options && options[:run_at]) || PutsDebuggerer.run_at) end
# File lib/puts_debuggerer.rb, line 354 def formatter=(formatter_proc) @formatter = formatter_proc.nil? ? FORMATTER_DEFAULT : formatter_proc end
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
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 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]] ]
# 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
# 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
# File lib/puts_debuggerer.rb, line 285 def print_engine_default Object.const_defined?(:AwesomePrint) ? PRINT_ENGINE_DEFAULT : :p end
# 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
# File lib/puts_debuggerer.rb, line 234 def printer_default Object.const_defined?(:Rails) ? PRINTER_RAILS : PRINTER_DEFAULT end
# File lib/puts_debuggerer.rb, line 471 def run_at=(value) @run_at = value end
# File lib/puts_debuggerer.rb, line 475 def run_at? !!@run_at end
# File lib/puts_debuggerer.rb, line 113 def source_line_count=(value) @source_line_count = value || SOURCE_LINE_COUNT_DEFAULT end