puts_debuggerer 0.9.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +30 -0
  3. data/README.md +360 -59
  4. data/VERSION +1 -1
  5. data/lib/pd.rb +1 -0
  6. data/lib/puts_debuggerer.rb +116 -305
  7. data/lib/puts_debuggerer/core_ext/kernel.rb +224 -0
  8. data/lib/puts_debuggerer/core_ext/logger.rb +3 -0
  9. data/lib/puts_debuggerer/core_ext/logging/logger.rb +5 -0
  10. data/lib/puts_debuggerer/run_determiner.rb +109 -0
  11. data/lib/puts_debuggerer/source_file.rb +32 -0
  12. metadata +32 -12
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f418876a84bf9553ec518205bad58db7b3abc120f1cd9fcff49e6edd49267247
4
- data.tar.gz: 808081fdf435cd30c4d1bb1f6a4f6211068e2ae2d52c039e3f99bbbf77071744
3
+ metadata.gz: 85cc76378a88f1e7c8019f347e69070190ca4f051619fc60dee05d2ff3e83dda
4
+ data.tar.gz: fb66e2375aa5624c8910d429032e9d99367b1ed5560aa7e364bd431167f5a291
5
5
  SHA512:
6
- metadata.gz: 4e85ad239c06a374f8e8319649cca570af59aae4b828b64e2d4e9e1102af8a41123f8896da3ce8e2ec103d5300c4968493063419a258ed672ee82de05358e3f4
7
- data.tar.gz: 2c56e41a7649d11ca7998d86b1682d2b16e59ecf70b94ef71c3672857c03693932d9ef797218fb65c9cfea7563c0df6428bf2e48a1ca4ac2366f38677b6bdfb8
6
+ metadata.gz: e61dc7234af7e6392bc61a8510a63846c65a6cf305e5ba2dd2ce807d6ec72d259675cf0f32bddb45709d0d823e2123d8e3ce4ecce14c8165bb15874354128c24
7
+ data.tar.gz: 5140b36a4d575b4f27e19929c70437d8e30a45d5085b682106868c2e915e49be6744a6aea772946b8e05b3ec2d1ed4d3be21ba163dec2db56a21eeaa6b991650
data/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Change Log
2
2
 
3
+ ## 0.12.0
4
+
5
+ - Upgrade `awesome_print` to `~> 0.9.2`
6
+ - Support passing pd options as part of a printed hash instead of requiring a separate hash (e.g. `pd(path: path, header: true)` instead of `pd({path: path}, header: true)` )
7
+ - Support empty use of pd statement + options (e.g. `pd` or `pd header: true`)
8
+
9
+ ## 0.11.0
10
+
11
+ - Pry support
12
+ - In Opal, print exceptions as errors in the web console using an alternative to full_message since it's not implemented in Opal yet
13
+ - Fix `pd_inspect` and `pdi` in IRB
14
+
15
+ ## 0.10.2
16
+
17
+ - Improve Opal Ruby compatibility by displaying source file/line
18
+
19
+ ## 0.10.1
20
+
21
+ - Remove the need for specifying `require 'ap'` before `require 'pd'`
22
+
23
+ ## 0.10.0
24
+
25
+ - Support `require 'pd`' as a shorter alternative to `require 'puts_debuggerer'`
26
+ - Support `printer` as a Logger object or Logging::Logger (from "logging" gem). Basically any object that responds to :debug method.
27
+ - Support `printer: false` option to return rendered String instead of printing and returning object
28
+ - Set logger formatter to PutsDebuggerer::LOGGER_FORMATTER_DECORATOR when passing as printer (keeping format the same, but decorating msg with pd)
29
+ - Add pd_inspect (and pdi alias) Kernel core extension methods
30
+ - Made awesome_print gem require happen only if printer is set to :ap or :awesome_print
31
+ - Support logging gem logger and Decorate logger layout with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR for logging gem
32
+
3
33
  ## 0.9.0
4
34
 
5
35
  - Provide partial support for Opal Ruby (missing display of file name, line number, and source code)
data/README.md CHANGED
@@ -2,16 +2,23 @@
2
2
  [![Gem Version](https://badge.fury.io/rb/puts_debuggerer.svg)](http://badge.fury.io/rb/puts_debuggerer)
3
3
  [![Build Status](https://travis-ci.org/AndyObtiva/puts_debuggerer.svg?branch=master)](https://travis-ci.org/AndyObtiva/puts_debuggerer)
4
4
  [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/puts_debuggerer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/puts_debuggerer?branch=master)
5
+ [![Maintainability](https://api.codeclimate.com/v1/badges/81d8f6e046eb1b4a36f4/maintainability)](https://codeclimate.com/github/AndyObtiva/puts_debuggerer/maintainability)
6
+
7
+ (credit to Aaron Patterson for partial inspiration: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html)
5
8
 
6
9
  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.
7
10
 
8
- 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.
11
+ 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.
12
+
13
+ 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).
14
+
15
+ [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).
9
16
 
10
17
  Basic Example:
11
18
 
12
19
  ```ruby
13
20
  # /Users/User/trivia_app.rb # line 1
14
- require 'puts_debuggerer' # line 2
21
+ require 'pd' # line 2
15
22
  bug_or_band = 'beattle' # line 3
16
23
  pd bug_or_band # line 4
17
24
  ```
@@ -19,17 +26,14 @@ pd bug_or_band # line 4
19
26
  Output:
20
27
 
21
28
  ```bash
22
- [PD] trivia_app.rb:4
29
+ [PD] /Users/User/trivia_app.rb:4
23
30
  > pd bug_or_band # line 4
24
31
  => "beattle"
25
32
  ```
26
33
 
27
34
  ## Background
28
35
 
29
- For initial background, please read this blog post by Aaron Patterson (part of the inspiration for this gem):
30
- https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
31
-
32
- 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.
36
+ 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.
33
37
 
34
38
  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.
35
39
 
@@ -58,71 +62,225 @@ Which gets lost in a logging stream such as:
58
62
  (0.2ms) COMMIT
59
63
  ```
60
64
 
61
- Problem can be mitigated by adding a few more puts statements:
65
+ 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:
62
66
 
63
67
  ```ruby
64
- puts "*"*40
65
- puts "order_total"
66
- puts order_total
68
+ pd order_total
67
69
  ```
68
70
 
69
- But those add up pretty quickly when inspecting multiple variables:
71
+ Output:
70
72
 
71
- ```ruby
72
- puts "*"*40
73
- puts "order_total"
74
- puts order_total
75
- puts "*"*40
76
- puts "order_summary"
77
- puts order_summary
78
- puts "*"*40
79
- puts "order_details"
80
- puts order_details
73
+ ```
74
+ (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)
75
+ 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]]
76
+ (0.2ms) BEGIN
77
+ 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]]
78
+ (0.3ms) COMMIT
79
+ [PD] /Users/User/ordering/order.rb:39
80
+ > pd order_total
81
+ => 195.50
82
+ 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]]
83
+ (0.2ms) BEGIN
84
+ (0.2ms) COMMIT
81
85
  ```
82
86
 
83
- Here is a simple example using `pd` instead:
87
+ 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):
84
88
 
85
89
  ```ruby
86
90
  pd order_total
91
+ pd order_summary
92
+ pd order_details
87
93
  ```
88
94
 
89
95
  Output:
90
96
 
91
97
  ```
98
+ (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)
99
+ 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]]
92
100
  [PD] /Users/User/ordering/order.rb:39
93
- > pd order_total
101
+ > pd order_total
94
102
  => 195.50
103
+ (0.2ms) BEGIN
104
+ 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]]
105
+ (0.3ms) COMMIT
106
+ [PD] /Users/User/ordering/order.rb:40
107
+ > pd order_summary
108
+ => "Pragmatic Ruby Book"
109
+ 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]]
110
+ (0.2ms) BEGIN
111
+ (0.2ms) COMMIT
112
+ [PD] /Users/User/ordering/order.rb:41
113
+ > pd order_details
114
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
115
+ ```
116
+
117
+ What if you would like to add a header for faster findability of groups of related pd statements? Just use the `header` option:
118
+
119
+ ```ruby
120
+ pd order_total, header: true
121
+ pd order_summary
122
+ pd order_details
123
+ ```
124
+
125
+ Output:
126
+
127
+ ```
128
+ (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)
129
+ 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]]
130
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
131
+ [PD] /Users/User/ordering/order.rb:39
132
+ > pd order_total, header: true
133
+ => 195.50
134
+ (0.2ms) BEGIN
135
+ 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]]
136
+ (0.3ms) COMMIT
137
+ [PD] /Users/User/ordering/order.rb:40
138
+ > pd order_summary
139
+ => "Pragmatic Ruby Book"
140
+ 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]]
141
+ (0.2ms) BEGIN
142
+ (0.2ms) COMMIT
143
+ [PD] /Users/User/ordering/order.rb:41
144
+ > pd order_details
145
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
95
146
  ```
96
147
 
97
- 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.
148
+ Wanna customize the header and add a footer too? No problem:
149
+
150
+ ```ruby
151
+ pd order_total, header: '>'*80
152
+ pd order_summary
153
+ pd order_details, footer: '<'*80
154
+ ```
155
+
156
+ Output:
98
157
 
99
158
  ```
100
159
  (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)
101
160
  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]]
161
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
102
162
  [PD] /Users/User/ordering/order.rb:39
103
- > pd order_total
163
+ > pd order_total, header: '>'*80
104
164
  => 195.50
105
165
  (0.2ms) BEGIN
106
166
  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]]
107
167
  (0.3ms) COMMIT
108
- [PD] /Users/User/ordering/order.rb:72
109
- > pd order_subtotal
110
- => 181.00
168
+ [PD] /Users/User/ordering/order.rb:40
169
+ > pd order_summary
170
+ => "Pragmatic Ruby Book"
111
171
  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]]
112
172
  (0.2ms) BEGIN
113
173
  (0.2ms) COMMIT
174
+ [PD] /Users/User/ordering/order.rb:41
175
+ > pd order_details, footer: '<'*80
176
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
177
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
114
178
  ```
115
179
 
116
- And it is easy to search for using the `[PD]` announcer (customizable).
180
+ Need a quick stack trace? Just use the `caller` option (you may surround with header and footer too via `wrapper`).
117
181
 
118
- When inspecting multiple variables, debugging code is still a snap:
182
+ ```ruby
183
+ pd order_total, caller: true, wrapper: true
184
+ pd order_summary
185
+ pd order_details
186
+ ```
187
+
188
+ Output:
189
+
190
+ ```
191
+ (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)
192
+ 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]]
193
+ ********************************************************************************
194
+ [PD] /Users/User/ordering/order.rb:39
195
+ > pd order_total, caller: true, wrapper: true
196
+ => 195.50
197
+ /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'
198
+ /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'
199
+ /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'
200
+ /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'
201
+ /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'
202
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
203
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
204
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
205
+ /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'
206
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `tap'
207
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `perform'
208
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/command.rb:27:in `run'
209
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/invocation.rb:127:in `invoke_command'
210
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor.rb:392:in `dispatch'
211
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command/base.rb:69:in `perform'
212
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command.rb:46:in `invoke'
213
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands.rb:18:in `<main>'
214
+ /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'
215
+ /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'
216
+ /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'
217
+ /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'
218
+ /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'
219
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
220
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
221
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
222
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/rails:9:in `<top (required)>'
223
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `load'
224
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `call'
225
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/command.rb:7:in `call'
226
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client.rb:30:in `run'
227
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/bin/spring:49:in `<top (required)>'
228
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `load'
229
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `<top (required)>'
230
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `require'
231
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `<top (required)>'
232
+ bin/rails:3:in `load'
233
+ bin/rails:3:in `<main>'
234
+ ********************************************************************************
235
+ (0.2ms) BEGIN
236
+ 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]]
237
+ (0.3ms) COMMIT
238
+ [PD] /Users/User/ordering/order.rb:40
239
+ > pd order_summary
240
+ => "Pragmatic Ruby Book"
241
+ 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]]
242
+ (0.2ms) BEGIN
243
+ (0.2ms) COMMIT
244
+ [PD] /Users/User/ordering/order.rb:41
245
+ > pd order_details
246
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
247
+ ```
248
+
249
+ Is the stack trace too long? Shorten it by passing number of lines to display to `caller` option.
119
250
 
120
251
  ```ruby
121
- pd order_total
252
+ pd order_total, caller: 3, wrapper: true
122
253
  pd order_summary
123
254
  pd order_details
124
255
  ```
125
256
 
257
+ ```
258
+ (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)
259
+ 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]]
260
+ ********************************************************************************
261
+ [PD] /Users/User/ordering/order.rb:39
262
+ > pd order_total, caller: 3, wrapper: true
263
+ => 195.50
264
+ /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'
265
+ /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'
266
+ /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'
267
+ ********************************************************************************
268
+ (0.2ms) BEGIN
269
+ 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]]
270
+ (0.3ms) COMMIT
271
+ [PD] /Users/User/ordering/order.rb:40
272
+ > pd order_summary
273
+ => "Pragmatic Ruby Book"
274
+ 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]]
275
+ (0.2ms) BEGIN
276
+ (0.2ms) COMMIT
277
+ [PD] /Users/User/ordering/order.rb:41
278
+ > pd order_details
279
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
280
+ ```
281
+
282
+ There are many more options and powerful features in [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) as detailed below.
283
+
126
284
  ## Instructions
127
285
 
128
286
  ### Option 1: Bundler
@@ -130,7 +288,7 @@ pd order_details
130
288
  Add the following to bundler's `Gemfile`.
131
289
 
132
290
  ```ruby
133
- gem 'puts_debuggerer', '~> 0.9.0'
291
+ gem 'puts_debuggerer', '~> 0.12.0'
134
292
  ```
135
293
 
136
294
  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,38 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
140
298
  Or manually install and require library.
141
299
 
142
300
  ```bash
143
- gem install puts_debuggerer -v0.9.0
301
+ gem install puts_debuggerer -v0.12.0
144
302
  ```
145
303
 
146
304
  ```ruby
147
305
  require 'puts_debuggerer'
148
306
  ```
149
307
 
308
+ Or the shorter form (often helpful to quickly troubleshoot an app):
309
+
310
+ ```ruby
311
+ require 'pd'
312
+ ```
313
+
150
314
  ### Awesome Print
151
315
 
152
- puts_debuggerer comes with [awesome_print](https://github.com/awesome-print/awesome_print).
316
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) comes with [awesome_print](https://github.com/awesome-print/awesome_print).
317
+
318
+ It is the default `PutsDebuggerer.print_engine`
153
319
 
154
- You may disable when needed by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
320
+ Still, if you do not need it, you may disable by setting `PutsDebuggerer.print_engine` to another value. Example:
321
+
322
+ ```ruby
323
+ PutsDebuggerer.print_engine = :puts
324
+ ```
325
+
326
+ If you also avoid requiring 'awesome_print', PutsDebuggerer won't require it either if it sees that you have a different `print_engine`
327
+
328
+ You may also avoid requiring in Bundler `Gemfile` with `require: false`:
155
329
 
156
330
  ```ruby
157
331
  gem "awesome_print", require: false
158
- gem "puts_debugger"
332
+ gem "puts_debuggerer"
159
333
  ```
160
334
 
161
335
  ### Usage
@@ -182,7 +356,7 @@ Output:
182
356
  => "Show me the result of the calculation: 4.0"
183
357
  ```
184
358
 
185
- 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).
359
+ 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).
186
360
 
187
361
  Second, quickly locate printed lines using the Find feature (e.g. CTRL+F) by looking for:
188
362
  * [PD]
@@ -211,6 +385,20 @@ Output:
211
385
 
212
386
  Happy puts_debuggerering!
213
387
 
388
+ #### `pd_inspect` kernel method
389
+
390
+ You may want to just return the string produced by the `pd` method without printing it.
391
+
392
+ In that case, you may use the `pd` alternative to `object.inspect`:
393
+ - `object.pd_inspect`
394
+ - `obj.pdi` (shorter alias)
395
+
396
+ This returns the `pd` formatted string without printing to the terminal or log files.
397
+
398
+ #### Ruby Logger and Logging::Logger
399
+
400
+ Ruby Logger and Logging::Logger (from [logging gem](https://github.com/TwP/logging)) are supported as [printers](#putsdebuggererprinter) (learn more under [PutsDebuggerer#printer](#putsdebuggererprinter)).
401
+
214
402
  ### Options
215
403
 
216
404
  Options enable more data to be displayed with puts_debuggerer, such as the caller
@@ -233,7 +421,7 @@ pd data, header: true
233
421
  Prints out:
234
422
 
235
423
  ```bash
236
- ********************************************************************************
424
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
237
425
  [PD] /Users/User/project/piecemeal.rb:3
238
426
  > pd data, header: true
239
427
  => [1, [2, 3]]
@@ -282,53 +470,93 @@ Example Printout:
282
470
  ```
283
471
 
284
472
  #### `PutsDebuggerer.header`
285
- (default = `'*'*80`)
473
+ (default = `'>'*80`)
286
474
 
287
475
  Header to include at the top of every print out.
288
476
  * Default value is `nil`
289
- * Value `true` enables header as `'*'*80`
477
+ * Value `true` enables header as `'>'*80`
290
478
  * Value `false`, `nil`, or empty string disables header
291
479
  * Any other string value gets set as a custom header
292
480
 
293
481
  Example:
294
482
 
483
+ ```ruby
484
+ pd (x=1), header: true
485
+ ```
486
+
487
+ Prints out:
488
+
489
+ ```bash
490
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
491
+ [PD] /Users/User/example.rb:1
492
+ > pd (x=1), header: true
493
+ => "1"
494
+ ```
495
+
496
+ Global Option Example:
497
+
295
498
  ```ruby
296
499
  PutsDebuggerer.header = true
297
500
  pd (x=1)
501
+ pd (x=2)
298
502
  ```
299
503
 
300
504
  Prints out:
301
505
 
302
506
  ```bash
303
- ********************************************************************************
507
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
304
508
  [PD] /Users/User/example.rb:2
305
- > pd x=1
509
+ > pd (x=1)
306
510
  => "1"
511
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
512
+ [PD] /Users/User/example.rb:3
513
+ > pd (x=2)
514
+ => "2"
307
515
  ```
308
516
 
309
517
  #### `PutsDebuggerer.footer`
310
- (default = `'*'*80`)
518
+ (default = `'<'*80`)
311
519
 
312
520
  Footer to include at the bottom of every print out.
313
521
  * Default value is `nil`
314
- * Value `true` enables footer as `'*'*80`
522
+ * Value `true` enables footer as `'<'*80`
315
523
  * Value `false`, `nil`, or empty string disables footer
316
524
  * Any other string value gets set as a custom footer
317
525
 
318
526
  Example:
319
527
 
528
+ ```ruby
529
+ pd (x=1), footer: true
530
+ ```
531
+
532
+ Prints out:
533
+
534
+ ```bash
535
+ [PD] /Users/User/example.rb:1
536
+ > pd (x=1), footer: true
537
+ => "1"
538
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
539
+ ```
540
+
541
+ Global Option Example:
542
+
320
543
  ```ruby
321
544
  PutsDebuggerer.footer = true
322
545
  pd (x=1)
546
+ pd (x=2)
323
547
  ```
324
548
 
325
549
  Prints out:
326
550
 
327
551
  ```bash
328
552
  [PD] /Users/User/example.rb:2
329
- > pd x=1
553
+ > pd (x=1)
330
554
  => "1"
331
- ********************************************************************************
555
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
556
+ [PD] /Users/User/example.rb:3
557
+ > pd (x=2)
558
+ => "2"
559
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
332
560
  ```
333
561
 
334
562
  #### `PutsDebuggerer.wrapper`
@@ -342,9 +570,26 @@ Wrapper to include at the top and bottom of every print out (both header and foo
342
570
 
343
571
  Example:
344
572
 
573
+ ```ruby
574
+ pd (x=1), wrapper: true
575
+ ```
576
+
577
+ Prints out:
578
+
579
+ ```bash
580
+ ********************************************************************************
581
+ [PD] /Users/User/example.rb:1
582
+ > pd x=1, wrapper: true
583
+ => "1"
584
+ ********************************************************************************
585
+ ```
586
+
587
+ Global Option Example:
588
+
345
589
  ```ruby
346
590
  PutsDebuggerer.wrapper = true
347
591
  pd (x=1)
592
+ pd (x=2)
348
593
  ```
349
594
 
350
595
  Prints out:
@@ -352,14 +597,21 @@ Prints out:
352
597
  ```bash
353
598
  ********************************************************************************
354
599
  [PD] /Users/User/example.rb:2
355
- > pd x=1
600
+ > pd (x=1)
356
601
  => "1"
357
602
  ********************************************************************************
603
+ ********************************************************************************
604
+ [PD] /Users/User/example.rb:3
605
+ > pd (x=2)
606
+ => "2"
607
+ ********************************************************************************
358
608
  ```
359
609
 
360
610
  #### `PutsDebuggerer.source_line_count`
361
611
  (default = `1`)
362
612
 
613
+ 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.
614
+
363
615
  Example:
364
616
 
365
617
  ```ruby
@@ -370,7 +622,7 @@ pd (true ||
370
622
  Prints out:
371
623
 
372
624
  ```
373
- [PD] /Users/User/example.rb:2
625
+ [PD] /Users/User/example.rb:1
374
626
  > pd (true ||
375
627
  false), source_line_count: 2
376
628
  => "true"
@@ -396,9 +648,17 @@ Prints out:
396
648
  #### `PutsDebuggerer.printer`
397
649
  (default = `:puts`)
398
650
 
399
- Printer is a global method symbol or lambda expression to use in printing to the user.
400
- Examples of global methods are `:puts` and `:print`.
651
+ Printer is a global method symbol, lambda expression, or logger to use in printing to the user.
652
+
653
+ Examples of a global method are `:puts` and `:print`.
401
654
  An example of a lambda expression is `lambda {|output| Rails.logger.info(output)}`
655
+ Examples of a logger are a Ruby `Logger` instance or `Logging::Logger` instance
656
+
657
+ When a logger is supplied, it is automatically enhanced with a PutsDebuggerer formatter to use
658
+ when calling logger methods outside of PutsDebuggerer (e.g. `logger.error('msg')` will use `pd`)
659
+
660
+ Printer may be set to `false` to avoid printing and only return the formatted string.
661
+ It is equivalent of just calling `.pd_inspect` (or alias `.pdi`) on the object
402
662
 
403
663
  Defaults to `:puts`
404
664
  In Rails, it defaults to:
@@ -450,7 +710,7 @@ pd array
450
710
  Prints out:
451
711
 
452
712
  ```bash
453
- [PD] /Users/User/example.rb:5
713
+ [PD] /Users/User/example.rb:4
454
714
  > pd array
455
715
  => [1, [2, 3]]
456
716
  ```
@@ -555,6 +815,34 @@ Prints out:
555
815
  /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
556
816
  ```
557
817
 
818
+ Global Option Example:
819
+
820
+ ```ruby
821
+ # File Name: /Users/User/sample_app/lib/sample.rb
822
+ PutsDebuggerer.caller = 3 # always print 3 lines only of the stack trace
823
+ pd (x=1)
824
+ pd (x=2)
825
+ ```
826
+
827
+ Prints out:
828
+
829
+ ```bash
830
+ [PD] /Users/User/sample_app/lib/sample.rb:2
831
+ > pd (x=1)
832
+ => "1"
833
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
834
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
835
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
836
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
837
+ [PD] /Users/User/sample_app/lib/sample.rb:3
838
+ > pd (x=2)
839
+ => "2"
840
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
841
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
842
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
843
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
844
+ ```
845
+
558
846
  #### `PutsDebuggerer.run_at`
559
847
  (default = nil)
560
848
 
@@ -672,16 +960,29 @@ Prints out `puts __caller_source_line__`
672
960
 
673
961
  ## Compatibility
674
962
 
675
- [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) is fully compatible with:
963
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) is fully compatible with:
676
964
  - [Ruby](https://www.ruby-lang.org/en/)
677
965
  - [JRuby](https://www.jruby.org/)
678
- - IRB
679
- - Rails Console.
966
+ - IRB (including Rails Console)
967
+ - Pry
968
+
969
+ ### Opal Ruby
970
+
971
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) provides partial-compatibility in [Opal Ruby](https://opalrb.com/) with everything working except:
972
+ - AwesomePrint (using the `:p` printer instead)
973
+ - Source code display
974
+
975
+ [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.
976
+
977
+ Here is an example of `pd` output in Opal:
978
+
979
+ ```
980
+ [PD] http://localhost:3000/assets/views/garderie_rainbow_daily_agenda/app_view.self-72626d75e0f68a619b1c8ad139535d799d45ab6c730d083820b790d71338e983.js?body=1:72:12
981
+ >
982
+ => "body"
983
+ ```
680
984
 
681
- It has partial-compatibility with [Opal Ruby](https://opalrb.com/) with everything working except these features:
682
- - File name display
683
- - Line number display
684
- - Source code call display
985
+ 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.
685
986
 
686
987
  ## Change Log
687
988