puts_debuggerer 0.8.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b80118305f3b8201241cb75a16fab616e1db9789daf829c5b4ea68ad7a6d94d
-  data.tar.gz: dd345085a3bcbf718cdb49983b3c2d1838b1914b231e6fc033ff30ea992fac32
+  metadata.gz: 43ff23befa76e5fc66ff64e550594c4e0c4a2055d586329ee731c075c6ab54a7
+  data.tar.gz: 1224fadbcca6b036eac9ed58d9ce60d5e7f7a6cd3a6742de05e4f82cb9107b8e
 SHA512:
-  metadata.gz: 1ac9056936792d4f8c46e4ae4114b0911a6442ef5b6ee5a6a1aebd6e405c3abc37466d207f19e94c6eaf9bd58374cd30ab2f66581777b9e37b2f572953c9261a
-  data.tar.gz: 7e0bbb0fcb9c502a252227b74a68a91d39f8ecbbf5cf85a18c4f561dae0a71baa5d258680835c573d2c5f6555e142f1b911f6a3c94302022cbd3a3ac4caeda01
+  metadata.gz: 13af30103a2bfa13e3e579f9083ed366fb4fa168e53a7c685e9181c60fb194dc24430e49d14348d4ae59f7573430b1f665987182b101a4a5da28394acf9b485e
+  data.tar.gz: 3b6eb47ca8c5758f3ffe6405ca94031bc05ee2cfad09cbb1f20fec85aea0fef42c0900a9ccd43916f4f567aed1d7c8f5ec9ec779c69c586cd9f5052e8b809047

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Change Log
+
+## 0.11.0
+
+- Pry support
+- In Opal, print exceptions as errors in the web console using an alternative to full_message since it's not implemented in Opal yet
+- Fix `pd_inspect` and `pdi` in IRB
+
+## 0.10.2
+
+- Improve Opal Ruby compatibility by displaying source file/line
+
+## 0.10.1
+
+- Remove the need for specifying `require 'ap'` before `require 'pd'`
+
+## 0.10.0
+
+- Support `require 'pd`' as a shorter alternative to `require 'puts_debuggerer'`
+- Support `printer` as a Logger object or Logging::Logger (from "logging" gem). Basically any object that responds to :debug method.
+- Support `printer: false` option to return rendered String instead of printing and returning object
+- Set logger formatter to PutsDebuggerer::LOGGER_FORMATTER_DECORATOR when passing as printer (keeping format the same, but decorating msg with pd)
+- Add pd_inspect (and pdi alias) Kernel core extension methods
+- Made awesome_print gem require happen only if printer is set to :ap or :awesome_print
+- Support logging gem logger and Decorate logger layout with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR for logging gem
+
+## 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

@@ -2,16 +2,23 @@
 [![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)
+[![Maintainability](https://api.codeclimate.com/v1/badges/81d8f6e046eb1b4a36f4/maintainability)](https://codeclimate.com/github/AndyObtiva/puts_debuggerer/maintainability)
+
+(credit to Aaron Patterson for partial inspiration: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html)
 
 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.
+In day-to-day test-driven development and simple app 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. Still, there are a number of problems with puts debugging, like difficulty in locating puts statements in a large output log, knowing which methods and line numbers were invoked, identifying which variables were printed, and seeing the content of structured hashes and arrays in an understandable format.
+
+Enter [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer)! A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, headers, footers, stack traces, and formats output nicely courtesy of [awesome_print](https://rubygems.org/gems/awesome_print).
+
+[puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) automates tips mentioned in [this blog post](https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html) by Aaron Patterson using the `pd` method available everywhere after requiring the [gem](https://rubygems.org/gems/puts_debuggerer).
 
 Basic Example:
 
 ```ruby
 # /Users/User/trivia_app.rb      # line 1
-require 'puts_debuggerer'        # line 2
+require 'pd'                     # line 2
 bug_or_band = 'beattle'          # line 3
 pd bug_or_band                   # line 4
 ```
@@ -19,17 +26,14 @@ pd bug_or_band                   # line 4
 Output:
 
 ```bash
-[PD] trivia_app.rb:4
+[PD] /Users/User/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
-
-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.
+It can be quite frustrating to lose puts statements in a large output or log file. One way to help find them is add an announcer (e.g. `puts "The Order Total"`) or a header (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.
 
@@ -58,71 +62,225 @@ Which gets lost in a logging stream such as:
    (0.2ms)  COMMIT
 ```
 
-Problem can be mitigated by adding a few more puts statements:
+Here is a simple example using `pd` instead, which provides everything the puts statements above provide in addition to deducing the file name and line number automatically for dead easy debugging:
 
 ```ruby
-puts "*"*40
-puts "order_total"
-puts order_total
+pd order_total
 ```
 
-But those add up pretty quickly when inspecting multiple variables:
+Output:
 
-```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
+```
+    (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
+[PD] /Users/User/ordering/order.rb:39
+  > pd order_total
+ => 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
 ```
 
-Here is a simple example using `pd` instead:
+This is not only easy to locate in a logging stream such as the one below, but also announces the `order_total` variable with `[PD]` for easy findability among other pd statements (you may always enter `[PD]` or variable name `order_total` using the CMD+F Quick Find to instantly jump to that line in the log):
 
 ```ruby
 pd order_total
+pd order_summary
+pd order_details
 ```
 
 Output:
 
 ```
+   (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  
+  > 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:40
+  > pd order_summary
+ => "Pragmatic Ruby Book"
+  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
+[PD] /Users/User/ordering/order.rb:41
+  > pd order_details
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
+```
+
+What if you would like to add a header for faster findability of groups of related pd statements? Just use the `header` option:
+
+```ruby
+pd order_total, header: true
+pd order_summary
+pd order_details
 ```
 
-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.
+Output:
 
 ```
    (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  
+  > pd order_total, header: true
  => 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
+[PD] /Users/User/ordering/order.rb:40
+  > pd order_summary
+ => "Pragmatic Ruby Book"
   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
+[PD] /Users/User/ordering/order.rb:41
+  > pd order_details
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
 ```
 
-And it is easy to search for using the `[PD]` announcer (customizable).
+Wanna customize the header and add a footer too? No problem:
+
+```ruby
+pd order_total, header: '>'*80
+pd order_summary
+pd order_details, footer: '<'*80
+```
+
+Output:
+
+```
+   (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, header: '>'*80
+ => 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:40
+  > pd order_summary
+ => "Pragmatic Ruby Book"
+  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
+[PD] /Users/User/ordering/order.rb:41
+  > pd order_details, footer: '<'*80
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+```
 
-When inspecting multiple variables, debugging code is still a snap:
+Need a quick stack trace? Just use the `caller` option (you may surround with header and footer too via `wrapper`).
 
 ```ruby
-pd order_total
+pd order_total, caller: true, wrapper: true
 pd order_summary
 pd order_details
 ```
 
+Output:
+
+```
+   (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, caller: true, wrapper: true
+ => 195.50
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `block in require_with_bootsnap_lfi'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/loaded_features_index.rb:92:in `register'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:22:in `require_with_bootsnap_lfi'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:31:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:145:in `block in perform'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `tap'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `perform'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/command.rb:27:in `run'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/invocation.rb:127:in `invoke_command'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor.rb:392:in `dispatch'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command/base.rb:69:in `perform'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command.rb:46:in `invoke'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands.rb:18:in `<main>'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `block in require_with_bootsnap_lfi'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/loaded_features_index.rb:92:in `register'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:22:in `require_with_bootsnap_lfi'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:31:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
+     /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/rails:9:in `<top (required)>'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `load'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `call'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/command.rb:7:in `call'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client.rb:30:in `run'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/bin/spring:49:in `<top (required)>'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `load'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `<top (required)>'
+     /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `require'
+     /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `<top (required)>'
+     bin/rails:3:in `load'
+     bin/rails:3:in `<main>'
+********************************************************************************
+   (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:40
+  > pd order_summary
+ => "Pragmatic Ruby Book"
+  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
+[PD] /Users/User/ordering/order.rb:41
+  > pd order_details
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
+```
+
+Is the stack trace too long? Shorten it by passing number of lines to display to `caller` option.
+
+```ruby
+pd order_total, caller: 3, wrapper: true
+pd order_summary
+pd order_details
+```
+
+```
+   (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, caller: 3, wrapper: true
+ => 195.50
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `require'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:23:in `block in require_with_bootsnap_lfi'
+     /Users/User/.rvm/gems/ruby-2.7.1/gems/bootsnap-1.4.6/lib/bootsnap/load_path_cache/loaded_features_index.rb:92:in `register'
+********************************************************************************
+   (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:40
+  > pd order_summary
+ => "Pragmatic Ruby Book"
+  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
+[PD] /Users/User/ordering/order.rb:41
+  > pd order_details
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
+```
+
+There are many more options and powerful features in [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) as detailed below.
+
 ## Instructions
 
 ### Option 1: Bundler
@@ -130,7 +288,7 @@ pd order_details
 Add the following to bundler's `Gemfile`.
 
 ```ruby
-gem 'puts_debuggerer', '~> 0.8.2'
+gem 'puts_debuggerer', '~> 0.10.3'
 ```
 
 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.
@@ -140,22 +298,39 @@ 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.8.2
+gem install puts_debuggerer -v0.10.3
 ```
 
 ```ruby
 require 'puts_debuggerer'
 ```
 
+Or the shorter form (often helpful to quickly troubleshoot an app):
+
+```ruby
+require 'pd'
+```
+
+
 ### Awesome Print
 
-puts_debuggerer comes with [awesome_print](https://github.com/awesome-print/awesome_print).
+[puts_debuggerer](https://rubygems.org/gems/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:
+It is the default `PutsDebuggerer.print_engine`
+
+Still, if you do not need it, you may disable by setting `PutsDebuggerer.print_engine` to another value. Example:
+
+```ruby
+PutsDebuggerer.print_engine = :puts
+```
+
+If you also avoid requiring 'awesome_print', PutsDebuggerer won't require it either if it sees that you have a different `print_engine`
+
+You may also avoid requiring in Bundler `Gemfile` with `require: false`:
 
 ```ruby
 gem "awesome_print", require: false
-gem "puts_debugger"
+gem "puts_debuggerer"
 ```
 
 ### Usage
@@ -182,7 +357,7 @@ Output:
   => "Show me the result of the calculation: 4.0"
 ```
 
-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).
+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 and Pry).
 
 Second, quickly locate printed lines using the Find feature (e.g. CTRL+F) by looking for:
 * [PD]
@@ -211,6 +386,20 @@ Output:
 
 Happy puts_debuggerering!
 
+#### `pd_inspect` kernel method
+
+You may want to just return the string produced by the `pd` method without printing it.
+
+In that case, you may use the `pd` alternative to `object.inspect`:
+- `object.pd_inspect`
+- `obj.pdi` (shorter alias)
+
+This returns the `pd` formatted string without printing to the terminal or log files.
+
+#### Ruby Logger and Logging::Logger
+
+Ruby Logger and Logging::Logger (from [logging gem](https://github.com/TwP/logging)) are supported as [printers](#putsdebuggererprinter) (learn more under [PutsDebuggerer#printer](#putsdebuggererprinter)).
+
 ### Options
 
 Options enable more data to be displayed with puts_debuggerer, such as the caller
@@ -233,7 +422,7 @@ pd data, header: true
 Prints out:
 
 ```bash
-********************************************************************************
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 [PD] /Users/User/project/piecemeal.rb:3
    > pd data, header: true
   => [1, [2, 3]]
@@ -292,18 +481,38 @@ Header to include at the top of every print out.
 
 Example:
 
+```ruby
+pd (x=1), header: true
+```
+
+Prints out:
+
+```bash
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+[PD] /Users/User/example.rb:1
+   > pd (x=1), header: true
+  => "1"
+```
+
+Global Option Example:
+
 ```ruby
 PutsDebuggerer.header = true
 pd (x=1)
+pd (x=2)
 ```
 
 Prints out:
 
 ```bash
-********************************************************************************
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 [PD] /Users/User/example.rb:2
-   > pd x=1
+   > pd (x=1)
   => "1"
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+[PD] /Users/User/example.rb:3
+   > pd (x=2)
+  => "2"
 ```
 
 #### `PutsDebuggerer.footer`
@@ -317,26 +526,140 @@ Footer to include at the bottom of every print out.
 
 Example:
 
+```ruby
+pd (x=1), footer: true
+```
+
+Prints out:
+
+```bash
+[PD] /Users/User/example.rb:1
+   > pd (x=1), footer: true
+  => "1"
+<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+```
+
+Global Option Example:
+
 ```ruby
 PutsDebuggerer.footer = true
 pd (x=1)
+pd (x=2)
 ```
 
 Prints out:
 
 ```bash
 [PD] /Users/User/example.rb:2
-   > pd x=1
+   > pd (x=1)
+  => "1"
+<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+[PD] /Users/User/example.rb:3
+   > pd (x=2)
+  => "2"
+<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+```
+
+#### `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
+pd (x=1), wrapper: true
+```
+
+Prints out:
+
+```bash
+********************************************************************************
+[PD] /Users/User/example.rb:1
+   > pd x=1, wrapper: true
   => "1"
 ********************************************************************************
 ```
 
+Global Option Example:
+
+```ruby
+PutsDebuggerer.wrapper = true
+pd (x=1)
+pd (x=2)
+```
+
+Prints out:
+
+```bash
+********************************************************************************
+[PD] /Users/User/example.rb:2
+   > pd (x=1)
+  => "1"
+********************************************************************************
+********************************************************************************
+[PD] /Users/User/example.rb:3
+   > pd (x=2)
+  => "2"
+********************************************************************************
+```
+
+#### `PutsDebuggerer.source_line_count`
+(default = `1`)
+
+Prints multiple source code lines as per count specified. Useful when a statement is broken down on multiple lines or when there is a need to get more context around the line printed.
+
+Example:
+
+```ruby
+pd (true ||
+  false), source_line_count: 2
+```
+
+Prints out:
+
+```
+[PD] /Users/User/example.rb:1
+   > 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`.
+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.info(output)}`
+Examples of a logger are a Ruby `Logger` instance or `Logging::Logger` instance
+
+When a logger is supplied, it is automatically enhanced with a PutsDebuggerer formatter to use
+when calling logger methods outside of PutsDebuggerer (e.g. `logger.error('msg')` will use `pd`)
+
+Printer may be set to `false` to avoid printing and only return the formatted string.
+It is equivalent of just calling `.pd_inspect` (or alias `.pdi`) on the object
 
 Defaults to `:puts`
 In Rails, it defaults to:
@@ -388,7 +711,7 @@ pd array
 Prints out:
 
 ```bash
-[PD] /Users/User/example.rb:5
+[PD] /Users/User/example.rb:4
    > pd array
   => [1, [2, 3]]
 ```
@@ -493,6 +816,34 @@ Prints out:
      /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
 ```
 
+Global Option Example:
+
+```ruby
+# File Name: /Users/User/sample_app/lib/sample.rb
+PutsDebuggerer.caller = 3 # always print 3 lines only of the stack trace
+pd (x=1)
+pd (x=2)
+```
+
+Prints out:
+
+```bash
+[PD] /Users/User/sample_app/lib/sample.rb:2
+    > 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\'
+[PD] /Users/User/sample_app/lib/sample.rb:3
+    > pd (x=2)
+   => "2"
+     /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\'
+```
+
 #### `PutsDebuggerer.run_at`
 (default = nil)
 
@@ -608,28 +959,39 @@ puts __caller_source_line__
 
 Prints out `puts __caller_source_line__`
 
-## Release Notes
-
-* v0.8.2: require 'stringio' for projects that don't require automatically via other gems
-* v0.8.1: `printer` option support for Rails test environment
-* v0.8.0: `printer` option support
-* v0.7.1: default print engine to :ap (AwesomePrint)
-* 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
+## 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 (including Rails Console)
+- Pry
+
+### Opal Ruby
+
+[puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) provides partial-compatibility in [Opal Ruby](https://opalrb.com/) with everything working except:
+- AwesomePrint (using the `:p` printer instead)
+- Source code display
+
+[puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) renders clickable source file/line links in Opal Ruby that take you to the source code in the web browser.
+
+Here is an example of `pd` output in Opal:
+
+```
+[PD] http://localhost:3000/assets/views/garderie_rainbow_daily_agenda/app_view.self-72626d75e0f68a619b1c8ad139535d799d45ab6c730d083820b790d71338e983.js?body=1:72:12
+   >
+  => "body"
+```
+
+Note that it ignores the configured printer when printing exceptions as it relies on Opal's `$stderr.puts` instead to show the stack trace in the web console.
+
+## Change Log
+
+[CHANGELOG.md](CHANGELOG.md)
 
 ## TODO
 
-* fix issue with printing in rspec inside a Rails project without having to do extra configuration
-* fix issue with erb support
-* display run_at run number in printout
-* implement fallback in irb for when line number cannot be discovered (issue happens in pry, perhaps this just means support pry)
+[TODO.md](TODO)
 
 ## Contributing
 
@@ -645,5 +1007,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.