puts_debuggerer 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6051847f09b1366d57fe622110440f277c85a872
-  data.tar.gz: d8ee66acfbb3daea757a5bb5599aed56f9f7d182
+SHA256:
+  metadata.gz: f418876a84bf9553ec518205bad58db7b3abc120f1cd9fcff49e6edd49267247
+  data.tar.gz: 808081fdf435cd30c4d1bb1f6a4f6211068e2ae2d52c039e3f99bbbf77071744
 SHA512:
-  metadata.gz: 7df9317401c68f2f90bc10f3bccc5410883e3c712339432299aacf6761f516576c62d58477bfa00cb8648a68c7d94a6b166f21d36e81a26fcc0f73fc1b9ad60f
-  data.tar.gz: 02f85ec1f441cfc02785b5701a4b0104203fd0e2b2bdc020301b54d66435d87d12ce634b235f1be8338289cf88d2f033c34f2b078a7020853a474ed47b4a2fec
+  metadata.gz: 4e85ad239c06a374f8e8319649cca570af59aae4b828b64e2d4e9e1102af8a41123f8896da3ce8e2ec103d5300c4968493063419a258ed672ee82de05358e3f4
+  data.tar.gz: 2c56e41a7649d11ca7998d86b1682d2b16e59ecf70b94ef71c3672857c03693932d9ef797218fb65c9cfea7563c0df6428bf2e48a1ca4ac2366f38677b6bdfb8

data/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Change Log
+
+## 0.9.0
+
+- Provide partial support for Opal Ruby (missing display of file name, line number, and source code)
+- `source_line_count` option
+- `wraper` option for including both `header` and `footer`
+- Special handling of exceptions (prints using full_message)
+- Change :ap printer default to :p when unavailable
+- Support varargs printing (example: `pd arg1, arg2, arg3`)
+- Display `run_at` run number in printout
+
+## 0.8.2
+
+- require 'stringio' for projects that don't require automatically via other gems
+
+## 0.8.1
+
+- `printer` option support for Rails test environment
+
+## 0.8.0
+
+- `printer` option support
+
+## 0.7.1
+
+- default print engine to :ap (AwesomePrint)
+
+## 0.7.0
+
+- `run_at` option, global and piecemeal.
+
+## 0.6.1
+
+- updated README and broke apart specs
+
+## 0.6.0
+
+- unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
+
+## 0.5.1
+
+- support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
+
+## 0.5.0
+
+- custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
+
+## 0.4.0
+
+- custom print engine (e.g. ap), custom announcer, and IRB support
+
+## 0.3.0
+
+- header/footer support, multi-line printout, improved format
+
+## 0.2.0
+
+- App path exclusion support, Rails root support, improved format
+
+## 0.1.0
+
+- File/line/expression print out

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017 Andy Maleh
+Copyright (c) 2017-2020 - Andy Maleh
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,22 +1,127 @@
-# puts_debuggerer v0.7.0
+# Puts Debuggerer (debugger-less debugging FTW)
 [![Gem Version](https://badge.fury.io/rb/puts_debuggerer.svg)](http://badge.fury.io/rb/puts_debuggerer)
 [![Build Status](https://travis-ci.org/AndyObtiva/puts_debuggerer.svg?branch=master)](https://travis-ci.org/AndyObtiva/puts_debuggerer)
 [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/puts_debuggerer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/puts_debuggerer?branch=master)
 
-Yes, many of us avoid debuggers like the plague and clamp on to our puts
-statements like an umbrella in a stormy day.
-Why not make it official and have puts debugging become its own perfectly
-legitimate thing?!!
+Debuggers are great! They help us troubleshoot complicated programming problems by inspecting values produced by code, line by line. They are invaluable when trying to understand what is going on in a large application composed of thousands or millions of lines of code.
 
-Enter puts_debuggerer. A guilt-free puts debugger Ruby gem FTW!
+In day-to-day test-driven development and simple debugging though, a puts statement can be a lot quicker in revealing what is going on than halting execution completely just to inspect a single value or a few. This is certainly true when writing the simplest possible code that could possibly work, and running a test every few seconds or minutes. Problem is you need to locate puts statements in large output logs, know which methods were invoked, find out what variable names are being printed, and see nicely formatted output. Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, and formats output nicely courtesy of awesome_print.
 
-In other words, puts_debuggerer is a Ruby library that provides improved puts debugging, automatically displaying bonus useful information such as source line numbers and source code, among many other goodies (mentioned in the README.)
+Basic Example:
 
-Partially inspired (only partially ;) by this blog post:
+```ruby
+# /Users/User/trivia_app.rb      # line 1
+require 'puts_debuggerer'        # line 2
+bug_or_band = 'beattle'          # line 3
+pd bug_or_band                   # line 4
+```
+
+Output:
+
+```bash
+[PD] trivia_app.rb:4
+   > pd bug_or_band                   # line 4
+  => "beattle"
+```
+
+## Background
+
+For initial background, please read this blog post by Aaron Patterson (part of the inspiration for this gem):
 https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
-(Credit to Tenderlove.)
 
-Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+gifts)?
+It can be quite frustrating to lose puts statements in a large output or log file. One way to help find them is add a header (e.g. `puts "The Order Total"`) or an announcer (e.g. `puts '*'*80`) before every puts statement. Unfortunately, that leads to repetitive wasteful effort that adds up quickly over many work sessions and interrupts thinking flow while solving problems.
+
+puts_debuggerer automates that work via the short and simple `pd` command, automatically printing meaningful headers for output and accelerating problem solving work due to ease of typing.
+
+Example without pd:
+
+```ruby
+puts order_total
+```
+
+Output:
+```
+195.50
+```
+
+Which gets lost in a logging stream such as:
+
+```
+   (2.7ms)  CREATE TABLE "ar_internal_metadata" ("key" character varying PRIMARY KEY, "value" character varying, "created_at" timestamp NOT NULL, "updated_at" timestamp NOT NULL)
+  ActiveRecord::InternalMetadata Load (0.4ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+  SQL (0.3ms)  INSERT INTO "ar_internal_metadata" ("key", "value", "created_at", "updated_at") VALUES ($1, $2, $3, $4) RETURNING "key"  [["key", "environment"], ["value", "development"], ["created_at", 2017-08-24 22:56:52 UTC], ["updated_at", 2017-08-24 22:56:52 UTC]]
+   (0.3ms)  COMMIT
+   195.50
+  ActiveRecord::InternalMetadata Load (0.3ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+   (0.2ms)  COMMIT
+```
+
+Problem can be mitigated by adding a few more puts statements:
+
+```ruby
+puts "*"*40
+puts "order_total"
+puts order_total
+```
+
+But those add up pretty quickly when inspecting multiple variables:
+
+```ruby
+puts "*"*40
+puts "order_total"
+puts order_total
+puts "*"*40
+puts "order_summary"
+puts order_summary
+puts "*"*40
+puts "order_details"
+puts order_details
+```
+
+Here is a simple example using `pd` instead:
+
+```ruby
+pd order_total
+```
+
+Output:
+
+```
+[PD] /Users/User/ordering/order.rb:39
+  > pd order_total  
+ => 195.50
+```
+
+This is not only easy to locate in a logging stream such as the one below, but also includes the `order_total` variable for easy findability among other pd statements.
+
+```
+   (2.7ms)  CREATE TABLE "ar_internal_metadata" ("key" character varying PRIMARY KEY, "value" character varying, "created_at" timestamp NOT NULL, "updated_at" timestamp NOT NULL)
+  ActiveRecord::InternalMetadata Load (0.4ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+[PD] /Users/User/ordering/order.rb:39
+  > pd order_total  
+ => 195.50
+   (0.2ms)  BEGIN
+  SQL (0.3ms)  INSERT INTO "ar_internal_metadata" ("key", "value", "created_at", "updated_at") VALUES ($1, $2, $3, $4) RETURNING "key"  [["key", "environment"], ["value", "development"], ["created_at", 2017-08-24 22:56:52 UTC], ["updated_at", 2017-08-24 22:56:52 UTC]]
+   (0.3ms)  COMMIT
+[PD] /Users/User/ordering/order.rb:72
+  > pd order_subtotal  
+ => 181.00
+  ActiveRecord::InternalMetadata Load (0.3ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+   (0.2ms)  COMMIT
+```
+
+And it is easy to search for using the `[PD]` announcer (customizable).
+
+When inspecting multiple variables, debugging code is still a snap:
+
+```ruby
+pd order_total
+pd order_summary
+pd order_details
+```
 
 ## Instructions
 
@@ -25,7 +130,7 @@ Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+g
 Add the following to bundler's `Gemfile`.
 
 ```ruby
-gem 'puts_debuggerer', '~> 0.7.0'
+gem 'puts_debuggerer', '~> 0.9.0'
 ```
 
 This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you may create an initializer under `config/initializers` named `puts_debuggerer_options.rb` to enable further customizations as per the [Options](#options) section below.
@@ -35,20 +140,29 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
 Or manually install and require library.
 
 ```bash
-gem install puts_debuggerer -v0.7.0
+gem install puts_debuggerer -v0.9.0
 ```
 
 ```ruby
 require 'puts_debuggerer'
 ```
 
-### Usage
+### Awesome Print
+
+puts_debuggerer comes with [awesome_print](https://github.com/awesome-print/awesome_print).
+
+You may disable when needed by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
+
+```ruby
+gem "awesome_print", require: false
+gem "puts_debugger"
+```
 
-Simply invoke global `pd` method anywhere in your code passing an object or an expression argument.
+### Usage
 
-It will then provide helpful debugging information by printing the source file, line number, and source code in addition to output (works even in IRB).
+First, add `pd` method anywhere in your code to display details about an object or expression (if you're used to awesome_print, you're in luck! puts_debuggerer includes awesome_print as the default print engine for output).
 
-Example Code:
+Example:
 
 ```ruby
 # /Users/User/finance_calculator_app/pd_test.rb           # line 1
@@ -57,7 +171,7 @@ pd "Show me the source of the bug: #{bug}"                # line 3
 pd "Show me the result of the calculation: #{(12.0/3.0)}" # line 4
 ```
 
-Example Printout:
+Output:
 
 ```bash
 [PD] /Users/User/finance_calculator_app/pd_test.rb:3
@@ -68,17 +182,18 @@ Example Printout:
   => "Show me the result of the calculation: 4.0"
 ```
 
-Quickly locate printed lines using Find feature (e.g. CTRL+F) by looking for:
+In addition to the main object/expression output, you get to see the source file name, line number, and source code to help you debug and troubleshoot problems quicker (it even works in IRB).
+
+Second, quickly locate printed lines using the Find feature (e.g. CTRL+F) by looking for:
 * [PD]
 * file:line_number
 * known ruby expression.
 
-This gives you the added benefit of easily removing your `pd` statements later
-on once done debugging.
+Third, easily remove your ` pd ` statements via the source code Find feature once done debugging.
 
 Note that `pd` returns the passed in object or expression argument unchanged, permitting debugging with shorter syntax than tap, and supporting chaining of extra method invocations afterward.
 
-Example Code:
+Example:
 
 ```ruby
 # /Users/User/greeting_app/pd_test.rb                     # line 1
@@ -86,7 +201,7 @@ name = 'Robert'                                           # line 2
 greeting = "Hello #{pd(name)}"                            # line 3
 ```
 
-Example Printout:
+Output:
 
 ```bash
 [PD] /Users/User/greeting_app/pd_test.rb:3
@@ -216,20 +331,118 @@ Prints out:
 ********************************************************************************
 ```
 
+#### `PutsDebuggerer.wrapper`
+(default = `'*'*80`)
+
+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:
+
+```ruby
+PutsDebuggerer.wrapper = true
+pd (x=1)
+```
+
+Prints out:
+
+```bash
+********************************************************************************
+[PD] /Users/User/example.rb:2
+   > pd x=1
+  => "1"
+********************************************************************************
+```
+
+#### `PutsDebuggerer.source_line_count`
+(default = `1`)
+
+Example:
+
+```ruby
+pd (true ||
+  false), source_line_count: 2
+```
+
+Prints out:
+
+```
+[PD] /Users/User/example.rb:2
+   > pd (true ||
+       false), source_line_count: 2
+  => "true"
+```
+
+Example:
+
+```ruby
+PutsDebuggerer.source_line_count = 2 # setting via global option
+pd (true ||
+  false)
+```
+
+Prints out:
+
+```
+[PD] /Users/User/example.rb:2
+   > pd (true ||
+       false), source_line_count: 2
+  => "true"
+```
+
+#### `PutsDebuggerer.printer`
+(default = `:puts`)
+
+Printer is a global method symbol or lambda expression to use in printing to the user.
+Examples of global methods are `:puts` and `:print`.
+An example of a lambda expression is `lambda {|output| Rails.logger.info(output)}`
+
+Defaults to `:puts`
+In Rails, it defaults to:
+```ruby
+lambda do |output|
+  puts output if Rails.env.test?
+  Rails.logger.debug(output)
+end
+```
+
+Example:
+
+```ruby
+# 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:
+
+```bash
+[PD] /Users/User/example.rb:5
+   > pd str
+  => Hello
+```
+
 #### `PutsDebuggerer.print_engine`
-(default = `:p`)
+(default = `:ap`)
 
-Print engine is a global method symbol or lambda expression to use in object printout. Examples of global methods are `:p`, `:ap`, and `:pp`. An example of a lambda expression is `lambda {|o| Rails.logger.info(o)}`
+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 Ruby's built-in `p` method identified by the symbol `:p`.
-If it finds [awesome_print](https://github.com/awesome-print/awesome_print) loaded, it defaults to `ap` as `:ap` instead. Also, if it finds Rails loaded without ap, it relies on `lambda {|o| Rails.logger.debug(o)}` as the print engine. Otherwise if both Rails and [awesome_print](https://github.com/awesome-print/awesome_print) are loaded, then it relies on `lambda {|o| Rails.logger.ap(o)}` instead
+Defaults to [awesome_print](https://github.com/awesome-print/awesome_print).
 
 Example:
 
 ```ruby
 # File Name: /Users/User/example.rb
-require 'awesome_print'
-PutsDebuggerer.print_engine = :ap
+PutsDebuggerer.print_engine = :p
 array = [1, [2, 3]]
 pd array
 ```
@@ -239,13 +452,7 @@ Prints out:
 ```bash
 [PD] /Users/User/example.rb:5
    > pd array
-  => [
-    [0] 1,
-    [1] [
-        [0] 2,
-        [1] 3
-    ]
-]
+  => [1, [2, 3]]
 ```
 
 #### `PutsDebuggerer.announcer`
@@ -366,6 +573,7 @@ the same exact `object` passed to `pd` for counting.
 
 Examples (global):
 
+```ruby
   PutsDebuggerer.run_at = 1
   pd (x=1) # prints standard PD output
   pd (x=1) # prints nothing
@@ -401,13 +609,14 @@ Examples (global):
   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
+  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
+  pd (x=1) # ... continue printing indefinitely on all subsequent runs
+```
 
 You may reset the run_at number counter via:
 `PutsDebuggerer.reset_run_at_global_number` for global usage.
@@ -417,20 +626,9 @@ And:
 `PutsDebuggerer.reset_run_at_numbers`
 for piecemeal usage.
 
-### Bonus
-
-puts_debuggerer comes with a number of bonus goodies.
-
-It comes with [awesome_print](https://github.com/awesome-print/awesome_print).
-
-You may disable by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
-
-```ruby
-gem "awesome_print", require: false
-gem "puts_debugger"
-```
+### Bonus API
 
-Additionally, puts_debuggerer comes with the following bonus utility methods:
+puts_debuggerer comes with the following bonus API methods:
 
 #### `__caller_line_number__(caller_depth=0)`
 
@@ -472,17 +670,26 @@ puts __caller_source_line__
 
 Prints out `puts __caller_source_line__`
 
-## Release Notes
+## Compatibility
+
+[puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) is fully compatible with: 
+- [Ruby](https://www.ruby-lang.org/en/)
+- [JRuby](https://www.jruby.org/)
+- IRB
+- Rails Console.
+
+It has partial-compatibility with [Opal Ruby](https://opalrb.com/) with everything working except these features:
+- File name display
+- Line number display
+- Source code call display
 
-* v0.7.0: `run_at` option, global and piecemeal.
-* v0.6.1: updated README and broke apart specs
-* v0.6.0: unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
-* v0.5.1: support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
-* v0.5.0: custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
-* v0.4.0: custom print engine (e.g. ap), custom announcer, and IRB support
-* v0.3.0: header/footer support, multi-line printout, improved format
-* v0.2.0: App path exclusion support, Rails root support, improved format
-* v0.1.0: File/line/expression print out
+## Change Log
+
+[CHANGELOG.md](CHANGELOG.md)
+
+## TODO
+
+[TODO.md](TODO)
 
 ## Contributing
 
@@ -498,5 +705,6 @@ Prints out `puts __caller_source_line__`
 
 ## Copyright
 
-Copyright (c) 2017 Andy Maleh. See LICENSE.txt for
-further details.
+[MIT](LICENSE.txt)
+
+Copyright (c) 2017-2020 - Andy Maleh.

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/lib/puts_debuggerer.rb

@@ -1,17 +1,28 @@
-require 'ripper'
+require 'awesome_print' unless RUBY_PLATFORM == 'opal'
+require 'stringio'
 
 module PutsDebuggerer
+  SOURCE_LINE_COUNT_DEFAULT = 1
   HEADER_DEFAULT = '*'*80
+  WRAPPER_DEFAULT = '*'*80
   FOOTER_DEFAULT = '*'*80
-  PRINT_ENGINE_DEFAULT = :p
-  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p or :puts) or lambda/proc'
+  PRINTER_DEFAULT = :puts
+  PRINTER_RAILS = lambda do |output|
+    puts output if Rails.env.test?
+    Rails.logger.debug(output)
+  end
+  PRINT_ENGINE_DEFAULT = :ap
+  PRINTER_MESSAGE_INVALID = 'printer must be a valid global method symbol (e.g. :puts) or 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 = {}
@@ -38,6 +49,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`
@@ -71,6 +104,39 @@ module PutsDebuggerer
       !!@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
+
+    def wrapper=(value)
+      if value.equal?(true)
+        @wrapper = WRAPPER_DEFAULT
+      elsif value == ''
+        @wrapper = nil
+      else
+        @wrapper = value
+      end
+    end
+
+    def wrapper?
+      !!@wrapper
+    end
+    
     # Footer to include at the bottom of every print out.
     # * Default value is `nil`
     # * Value `true` enables footer as `'*'*80`
@@ -104,17 +170,55 @@ module PutsDebuggerer
       !!@footer
     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 Ruby's built-in `p` method identified by the symbol `:p`.
-    # If it finds awesome_print loaded, it defaults to `ap` as `:ap` instead.
+    # Printer is a global method symbol or lambda expression to use in printing to the user.
+    # Examples of global methods are `:puts` and `:print`.
+    # An example of a lambda expression is `lambda {|output| Rails.logger.ap(output)}`
+    #
+    # 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?
+        if Object.const_defined?(:Rails)
+          @printer = PRINTER_RAILS
+        else
+          @printer = PRINTER_DEFAULT
+        end
+      elsif printer.is_a?(Proc)
+        @printer = printer
+      else
+        @printer = method(printer).name rescue raise(PRINTER_MESSAGE_INVALID)
+      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](https://github.com/awesome-print/awesome_print).
     #
     # Example:
     #
     #   # File Name: /Users/User/example.rb
     #   require 'awesome_print'
-    #   PutsDebuggerer.print_engine = :ap
+    #   PutsDebuggerer.print_engine = :p
     #   array = [1, [2, 3]]
     #   pd array
     #
@@ -122,28 +226,15 @@ module PutsDebuggerer
     #
     #   [PD] /Users/User/example.rb:5
     #      > pd array
-    #     => [
-    #       [0] 1,
-    #       [1] [
-    #           [0] 2,
-    #           [1] 3
-    #       ]
+    #     => [1, [2, 3]]
     #   ]
     attr_reader :print_engine
 
     def print_engine=(engine)
       if engine.nil?
-        if Object.const_defined?(:Rails)
-          if Object.respond_to?(:ap, 'Hello')
-            @print_engine = lambda {|object| Rails.logger.ap(object)}
-          else
-            @print_engine = lambda {|object| Rails.logger.debug(object)}
-          end
-        else
-          @print_engine = method(:ap).name rescue PRINT_ENGINE_DEFAULT
-        end
+        @print_engine = Object.const_defined?(:AwesomePrint) ? PRINT_ENGINE_DEFAULT : :p
       elsif engine.is_a?(Proc)
-        @print_engine = engine #TODO check that it takes one parameter or else fail fast
+        @print_engine = engine
       else
         @print_engine = method(engine).name rescue raise(PRINT_ENGINE_MESSAGE_INVALID)
       end
@@ -173,12 +264,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
@@ -256,8 +349,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,
@@ -340,15 +436,15 @@ module PutsDebuggerer
       @run_at_global_number = value
     end
 
-    def init_run_at_global_number(object, run_at)
+    def init_run_at_global_number
       @run_at_global_number = 1
     end
 
-    def increment_run_at_global_number(object, run_at)
+    def increment_run_at_global_number
       @run_at_global_number += 1
     end
 
-    def reset_run_at_global_number(object, run_at)
+    def reset_run_at_global_number
       @run_at_global_number = nil
     end
 
@@ -375,12 +471,15 @@ module PutsDebuggerer
   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.
@@ -411,13 +510,24 @@ 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)
+def pd(*objects)
+  options = objects.delete_at(-1) if objects.size > 1 && objects.last.is_a?(Hash)
+  object = objects.compact.size > 1 ? objects : objects.first
   run_at = ((options && options[:run_at]) || PutsDebuggerer.run_at)
 
   if __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.run_at_global_number || PutsDebuggerer.run_at_number(object, run_at)
+      formatter_pd_data = __build_pd_data__(object, print_engine_options, PutsDebuggerer.source_line_count, run_number) #depth adds build method
+      stdout = $stdout
+      $stdout = sio = StringIO.new
       PutsDebuggerer.formatter.call(formatter_pd_data)
+      $stdout = stdout
+      if PutsDebuggerer.printer.is_a?(Proc)
+        PutsDebuggerer.printer.call(sio.string)
+      else
+        send(PutsDebuggerer.send(:printer), sio.string)
+      end
     end
   end
 
@@ -429,20 +539,20 @@ def __run_pd__(object, run_at)
   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?
       if PutsDebuggerer.run_at_global_number.nil?
         PutsDebuggerer.init_run_at_global_number
       else
         PutsDebuggerer.increment_run_at_global_number
       end
       run_number = PutsDebuggerer.run_at_global_number
+    else
+      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)
     end
     if run_at.is_a?(Integer)
       run_pd = true if run_at == run_number
@@ -466,7 +576,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
@@ -479,7 +589,7 @@ end
 #
 # prints out `lib/example.rb`
 def __caller_file__(caller_depth=0)
-  caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]
+  caller[caller_depth] && caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]
 end
 
 
@@ -491,22 +601,28 @@ 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)
   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
+    if f.respond_to?(:readline) # Opal Ruby Compatibility
+      source_lines = []
+      begin
+        while f.lineno < source_line_number + source_line_count
+          file_line_number = f.lineno + 1
+          file_line = f.readline
+          if file_line_number >= source_line_number && file_line_number < source_line_number + source_line_count
+            source_lines << file_line
+          end
+        end
+      rescue EOFError
+        # Done
       end
+      source_line = source_lines.join(' '*5)
     end
   end
   source_line
@@ -523,16 +639,19 @@ 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)
   depth = PutsDebuggerer::CALLER_DEPTH_ZERO
   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)
+      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
         if print_engine_options.to_h.empty?
@@ -549,6 +668,7 @@ def __build_pd_data__(object, print_engine_options=nil)
     pd_data[:caller] = caller[start_depth..caller_depth].to_a
   end
   pd_data[:header] = PutsDebuggerer.header if PutsDebuggerer.header?
+  pd_data[:wrapper] = PutsDebuggerer.wrapper if PutsDebuggerer.wrapper?
   pd_data[:footer] = PutsDebuggerer.footer if PutsDebuggerer.footer?
   pd_data
 end
@@ -557,9 +677,9 @@ 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?(")")
@@ -574,5 +694,5 @@ end
 #
 # outputs `(x=1)`
 def __extract_pd_expression__(source_line)
-  source_line.strip
+  source_line.to_s.strip
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puts_debuggerer
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Andy Maleh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-07-25 00:00:00.000000000 Z
+date: 2020-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 1.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 1.8.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -67,86 +67,111 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
 - !ruby/object:Gem::Dependency
-  name: jeweler
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.16.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: undercover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.3.4
 description: |
-  Yes, many of us avoid debuggers like the plague and clamp on to our puts statements like an umbrella in a stormy day. Why not make it official and have puts debugging become its own perfectly legitimate thing?!!
-
-  Enter puts_debuggerer. A guilt-free puts debugger Ruby gem FTW!
-
-  In other words, puts_debuggerer is a Ruby library for improved puts debugging, automatically displaying bonus useful information such as source line number and source code.
-
-  Partially inspired (only partially ;) by this blog post:
-  https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
-  (Credit to Tenderlove.)
+  Debuggers are great! They help us troubleshoot complicated programming problems by inspecting values produced by code, line by line. They are invaluable when trying to understand what is going on in a large application composed of thousands or millions of lines of code.
+  In day-to-day test-driven development and simple debugging though, a puts statement can be a lot quicker in revealing what is going on than halting execution completely just to inspect a single value or a few. This is certainly true when writing the simplest possible code that could possibly work, and running a test every few seconds or minutes. Problem is you need to locate puts statements in large output logs, know which methods were invoked, find out what variable names are being printed, and see nicely formatted output. Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, and formats output nicely courtesy of awesome_print.
+  Partially inspired by this blog post: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html (Credit to Tenderlove.)
 email: andy.am@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
+- VERSION
 - lib/puts_debuggerer.rb
 homepage: http://github.com/AndyObtiva/puts_debuggerer
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,9 +186,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.10
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: Ruby library for improved puts debugging, automatically displaying bonus
   useful information such as source line number and source code.