puts_debuggerer 0.8.1 → 0.10.2

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 (13) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +81 -0
  3. data/LICENSE.txt +1 -1
  4. data/README.md +475 -55
  5. data/VERSION +1 -0
  6. data/lib/pd.rb +1 -0
  7. data/lib/puts_debuggerer.rb +151 -275
  8. data/lib/puts_debuggerer/core_ext/kernel.rb +217 -0
  9. data/lib/puts_debuggerer/core_ext/logger.rb +3 -0
  10. data/lib/puts_debuggerer/core_ext/logging/logger.rb +5 -0
  11. data/lib/puts_debuggerer/run_determiner.rb +109 -0
  12. data/lib/puts_debuggerer/source_file.rb +32 -0
  13. metadata +84 -26
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 0b6b423e48750ec42b8ba75d9d11b9bee413f968
4
- data.tar.gz: 436e88ff0bae84786ae496c93e9051c6a7e038f2
2
+ SHA256:
3
+ metadata.gz: c10b7cd1e10ee4448130b42cf869c55904445ec9038875c4da4339813ba7b6d6
4
+ data.tar.gz: 973aaad4a4eda5bb9ef7add02f0b3a3b991bb84f6fd2ab461281c03aa5cc1404
5
5
  SHA512:
6
- metadata.gz: 8d1fd6d211ef47039e03d2fcf0dd4e093bf68d28bae54fb3285a72fc7cb179889eefd2e4340eaecea7c630c8ec7b671a2d9b26ffbd01fc2acaccbed99e90fb17
7
- data.tar.gz: 627007999c72fd0c33d7ea60aa6703f68b56ea55c3698e0cca578e41f961aaac5f01dd924a0fd3e9fac9a97364b416d82534e4cedc6855fa2f4720e988cf78ae
6
+ metadata.gz: 9b029b0cfeb9b219313e80b72c8be7094db40101a51bc6b430254110c4e2b662eaed5706831372909f950fa1f7503a20544553491d29f275f004ab26be2c1419
7
+ data.tar.gz: cdd0aaa7734d5b98a1efba63fdc8aebd514ad76a694a1362b066728ffb0605005f8093d83355aa7c10d32a26eedf2e372042a62ecfdc0e04271fa2e24899ddb1
data/CHANGELOG.md ADDED
@@ -0,0 +1,81 @@
1
+ # Change Log
2
+
3
+ ## 0.10.2
4
+
5
+ - Improve Opal Ruby compatibility by displaying source file/line
6
+
7
+ ## 0.10.1
8
+
9
+ - Remove the need for specifying `require 'ap'` before `require 'pd'`
10
+
11
+ ## 0.10.0
12
+
13
+ - Support `require 'pd`' as a shorter alternative to `require 'puts_debuggerer'`
14
+ - Support `printer` as a Logger object or Logging::Logger (from "logging" gem). Basically any object that responds to :debug method.
15
+ - Support `printer: false` option to return rendered String instead of printing and returning object
16
+ - Set logger formatter to PutsDebuggerer::LOGGER_FORMATTER_DECORATOR when passing as printer (keeping format the same, but decorating msg with pd)
17
+ - Add pd_inspect (and pdi alias) Kernel core extension methods
18
+ - Made awesome_print gem require happen only if printer is set to :ap or :awesome_print
19
+ - Support logging gem logger and Decorate logger layout with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR for logging gem
20
+
21
+ ## 0.9.0
22
+
23
+ - Provide partial support for Opal Ruby (missing display of file name, line number, and source code)
24
+ - `source_line_count` option
25
+ - `wraper` option for including both `header` and `footer`
26
+ - Special handling of exceptions (prints using full_message)
27
+ - Change :ap printer default to :p when unavailable
28
+ - Support varargs printing (example: `pd arg1, arg2, arg3`)
29
+ - Display `run_at` run number in printout
30
+
31
+ ## 0.8.2
32
+
33
+ - require 'stringio' for projects that don't require automatically via other gems
34
+
35
+ ## 0.8.1
36
+
37
+ - `printer` option support for Rails test environment
38
+
39
+ ## 0.8.0
40
+
41
+ - `printer` option support
42
+
43
+ ## 0.7.1
44
+
45
+ - default print engine to :ap (AwesomePrint)
46
+
47
+ ## 0.7.0
48
+
49
+ - `run_at` option, global and piecemeal.
50
+
51
+ ## 0.6.1
52
+
53
+ - updated README and broke apart specs
54
+
55
+ ## 0.6.0
56
+
57
+ - unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
58
+
59
+ ## 0.5.1
60
+
61
+ - support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
62
+
63
+ ## 0.5.0
64
+
65
+ - custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
66
+
67
+ ## 0.4.0
68
+
69
+ - custom print engine (e.g. ap), custom announcer, and IRB support
70
+
71
+ ## 0.3.0
72
+
73
+ - header/footer support, multi-line printout, improved format
74
+
75
+ ## 0.2.0
76
+
77
+ - App path exclusion support, Rails root support, improved format
78
+
79
+ ## 0.1.0
80
+
81
+ - File/line/expression print out
data/LICENSE.txt CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2017 Andy Maleh
1
+ Copyright (c) 2017-2020 - Andy Maleh
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
data/README.md CHANGED
@@ -2,22 +2,40 @@
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)
5
6
 
6
- Yes, many of us avoid debuggers like the plague and clamp on to our puts
7
- statements like an umbrella in a stormy day.
8
- Why not make it official and have puts debugging become its own perfectly
9
- legitimate thing?!!
7
+ (credit to Aaron Patterson for partial inspiration: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html)
10
8
 
11
- Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW!
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.
12
10
 
13
- For background, please read this blog post by Aaron Patterson:
14
- https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
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.
16
+
17
+ Basic Example:
18
+
19
+ ```ruby
20
+ # /Users/User/trivia_app.rb # line 1
21
+ require 'pd' # line 2
22
+ bug_or_band = 'beattle' # line 3
23
+ pd bug_or_band # line 4
24
+ ```
25
+
26
+ Output:
27
+
28
+ ```bash
29
+ [PD] /Users/User/trivia_app.rb:4
30
+ > pd bug_or_band # line 4
31
+ => "beattle"
32
+ ```
15
33
 
16
34
  ## Background
17
35
 
18
- 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, leading to repetitive wasteful effort.
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.
19
37
 
20
- puts_debuggerer automates that work via the short and simple `pd` command, automatically printing meaningful headers for output.
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.
21
39
 
22
40
  Example without pd:
23
41
 
@@ -44,7 +62,29 @@ Which gets lost in a logging stream such as:
44
62
  (0.2ms) COMMIT
45
63
  ```
46
64
 
47
- Example with pd:
65
+ Problem can be mitigated by adding a few more puts statements:
66
+
67
+ ```ruby
68
+ puts "*"*40
69
+ puts "order_total"
70
+ puts order_total
71
+ ```
72
+
73
+ But those add up pretty quickly when inspecting multiple variables:
74
+
75
+ ```ruby
76
+ puts "*"*40
77
+ puts "order_total"
78
+ puts order_total
79
+ puts "*"*40
80
+ puts "order_summary"
81
+ puts order_summary
82
+ puts "*"*40
83
+ puts "order_details"
84
+ puts order_details
85
+ ```
86
+
87
+ 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:
48
88
 
49
89
  ```ruby
50
90
  pd order_total
@@ -58,7 +98,15 @@ Output:
58
98
  => 195.50
59
99
  ```
60
100
 
61
- 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.
101
+ 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):
102
+
103
+ ```ruby
104
+ pd order_total
105
+ pd order_summary
106
+ pd order_details
107
+ ```
108
+
109
+ Output:
62
110
 
63
111
  ```
64
112
  (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)
@@ -69,15 +117,183 @@ This is not only easy to locate in a logging stream such as the one below, but a
69
117
  (0.2ms) BEGIN
70
118
  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]]
71
119
  (0.3ms) COMMIT
72
- [PD] /Users/User/ordering/order.rb:72
73
- > pd order_subtotal
74
- => 181.00
120
+ [PD] /Users/User/ordering/order.rb:40
121
+ > pd order_summary
122
+ => "Pragmatic Ruby Book"
123
+ 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]]
124
+ (0.2ms) BEGIN
125
+ (0.2ms) COMMIT
126
+ [PD] /Users/User/ordering/order.rb:41
127
+ > pd order_details
128
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
129
+ ```
130
+
131
+ What if you would like to add a header for faster findability? Just use the `header` option:
132
+
133
+ ```ruby
134
+ pd order_total, header: true
135
+ pd order_summary
136
+ pd order_details
137
+ ```
138
+
139
+ Output:
140
+
141
+ ```
142
+ (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)
143
+ 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]]
144
+ ********************************************************************************
145
+ [PD] /Users/User/ordering/order.rb:39
146
+ > pd order_total, header: true
147
+ => 195.50
148
+ (0.2ms) BEGIN
149
+ 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]]
150
+ (0.3ms) COMMIT
151
+ [PD] /Users/User/ordering/order.rb:40
152
+ > pd order_summary
153
+ => "Pragmatic Ruby Book"
154
+ 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]]
155
+ (0.2ms) BEGIN
156
+ (0.2ms) COMMIT
157
+ [PD] /Users/User/ordering/order.rb:41
158
+ > pd order_details
159
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
160
+ ```
161
+
162
+ Wanna customize the header and add a footer too? No problem:
163
+
164
+ ```ruby
165
+ pd order_total, header: '>'*80
166
+ pd order_summary
167
+ pd order_details, footer: '<'*80
168
+ ```
169
+
170
+ Output:
171
+
172
+ ```
173
+ (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)
174
+ 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]]
175
+ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
176
+ [PD] /Users/User/ordering/order.rb:39
177
+ > pd order_total, header: '>'*80
178
+ => 195.50
179
+ (0.2ms) BEGIN
180
+ 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]]
181
+ (0.3ms) COMMIT
182
+ [PD] /Users/User/ordering/order.rb:40
183
+ > pd order_summary
184
+ => "Pragmatic Ruby Book"
185
+ 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]]
186
+ (0.2ms) BEGIN
187
+ (0.2ms) COMMIT
188
+ [PD] /Users/User/ordering/order.rb:41
189
+ > pd order_details, footer: '<'*80
190
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
191
+ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
192
+ ```
193
+
194
+ Need a quick stack trace? Just use the `caller` option (you may surround with header and footer too via `wrapper`).
195
+
196
+ ```ruby
197
+ pd order_total, caller: true, wrapper: true
198
+ pd order_summary
199
+ pd order_details
200
+ ```
201
+
202
+ Output:
203
+
204
+ ```
205
+ (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)
206
+ 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]]
207
+ ********************************************************************************
208
+ [PD] /Users/User/ordering/order.rb:39
209
+ > pd order_total, caller: true, wrapper: true
210
+ => 195.50
211
+ /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'
212
+ /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'
213
+ /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'
214
+ /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'
215
+ /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'
216
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
217
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
218
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
219
+ /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'
220
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `tap'
221
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands/server/server_command.rb:142:in `perform'
222
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/command.rb:27:in `run'
223
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor/invocation.rb:127:in `invoke_command'
224
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/thor-1.0.1/lib/thor.rb:392:in `dispatch'
225
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command/base.rb:69:in `perform'
226
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/command.rb:46:in `invoke'
227
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/railties-5.2.4.3/lib/rails/commands.rb:18:in `<main>'
228
+ /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'
229
+ /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'
230
+ /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'
231
+ /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'
232
+ /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'
233
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `block in require'
234
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:257:in `load_dependency'
235
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/activesupport-5.2.4.3/lib/active_support/dependencies.rb:291:in `require'
236
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/rails:9:in `<top (required)>'
237
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `load'
238
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/rails.rb:28:in `call'
239
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client/command.rb:7:in `call'
240
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/client.rb:30:in `run'
241
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/bin/spring:49:in `<top (required)>'
242
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `load'
243
+ /Users/User/.rvm/gems/ruby-2.7.1/gems/spring-2.1.0/lib/spring/binstub.rb:11:in `<top (required)>'
244
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `require'
245
+ /Users/User/code/sample-glimmer-dsl-opal-rails5-app/bin/spring:15:in `<top (required)>'
246
+ bin/rails:3:in `load'
247
+ bin/rails:3:in `<main>'
248
+ ********************************************************************************
249
+ (0.2ms) BEGIN
250
+ 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]]
251
+ (0.3ms) COMMIT
252
+ [PD] /Users/User/ordering/order.rb:40
253
+ > pd order_summary
254
+ => "Pragmatic Ruby Book"
255
+ 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]]
256
+ (0.2ms) BEGIN
257
+ (0.2ms) COMMIT
258
+ [PD] /Users/User/ordering/order.rb:41
259
+ > pd order_details
260
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
261
+ ```
262
+
263
+ Is the stack trace too long? Shorten it by passing number of lines to display to `caller` option.
264
+
265
+ ```ruby
266
+ pd order_total, caller: 3, wrapper: true
267
+ pd order_summary
268
+ pd order_details
269
+ ```
270
+
271
+ ```
272
+ (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)
273
+ 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]]
274
+ ********************************************************************************
275
+ [PD] /Users/User/ordering/order.rb:39
276
+ > pd order_total, caller: 3, wrapper: true
277
+ => 195.50
278
+ /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'
279
+ /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'
280
+ /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'
281
+ ********************************************************************************
282
+ (0.2ms) BEGIN
283
+ 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]]
284
+ (0.3ms) COMMIT
285
+ [PD] /Users/User/ordering/order.rb:40
286
+ > pd order_summary
287
+ => "Pragmatic Ruby Book"
75
288
  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]]
76
289
  (0.2ms) BEGIN
77
290
  (0.2ms) COMMIT
291
+ [PD] /Users/User/ordering/order.rb:41
292
+ > pd order_details
293
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
78
294
  ```
79
295
 
80
- And it is easy to search for using the `[PD]` announcer.
296
+ There are many more options and powerful features in [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) as detailed below.
81
297
 
82
298
  ## Instructions
83
299
 
@@ -86,7 +302,7 @@ And it is easy to search for using the `[PD]` announcer.
86
302
  Add the following to bundler's `Gemfile`.
87
303
 
88
304
  ```ruby
89
- gem 'puts_debuggerer', '~> 0.8.1'
305
+ gem 'puts_debuggerer', '~> 0.10.2'
90
306
  ```
91
307
 
92
308
  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.
@@ -96,13 +312,41 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
96
312
  Or manually install and require library.
97
313
 
98
314
  ```bash
99
- gem install puts_debuggerer -v0.8.1
315
+ gem install puts_debuggerer -v0.10.2
100
316
  ```
101
317
 
102
318
  ```ruby
103
319
  require 'puts_debuggerer'
104
320
  ```
105
321
 
322
+ Or the shorter form (often helpful to quickly troubleshoot an app):
323
+
324
+ ```ruby
325
+ require 'pd'
326
+ ```
327
+
328
+
329
+ ### Awesome Print
330
+
331
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) comes with [awesome_print](https://github.com/awesome-print/awesome_print).
332
+
333
+ It is the default `PutsDebuggerer.print_engine`
334
+
335
+ Still, if you do not need it, you may disable by setting `PutsDebuggerer.print_engine` to another value. Example:
336
+
337
+ ```ruby
338
+ PutsDebuggerer.print_engine = :puts
339
+ ```
340
+
341
+ If you also avoid requiring 'awesome_print', PutsDebuggerer won't require it either if it sees that you have a different `print_engine`
342
+
343
+ You may also avoid requiring in Bundler `Gemfile` with `require: false`:
344
+
345
+ ```ruby
346
+ gem "awesome_print", require: false
347
+ gem "puts_debuggerer"
348
+ ```
349
+
106
350
  ### Usage
107
351
 
108
352
  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).
@@ -156,6 +400,20 @@ Output:
156
400
 
157
401
  Happy puts_debuggerering!
158
402
 
403
+ #### `pd_inspect` kernel method
404
+
405
+ You may want to just return the string produced by the `pd` method without printing it.
406
+
407
+ In that case, you may use the `pd` alternative to `object.inspect`:
408
+ - `object.pd_inspect`
409
+ - `obj.pdi` (shorter alias)
410
+
411
+ This returns the `pd` formatted string without printing to the terminal or log files.
412
+
413
+ #### Ruby Logger and Logging::Logger
414
+
415
+ Ruby Logger and Logging::Logger (from [logging gem](https://github.com/TwP/logging)) are supported as [printers](#putsdebuggererprinter) (learn more under [PutsDebuggerer#printer](#putsdebuggererprinter)).
416
+
159
417
  ### Options
160
418
 
161
419
  Options enable more data to be displayed with puts_debuggerer, such as the caller
@@ -237,9 +495,25 @@ Header to include at the top of every print out.
237
495
 
238
496
  Example:
239
497
 
498
+ ```ruby
499
+ pd (x=1), header: true
500
+ ```
501
+
502
+ Prints out:
503
+
504
+ ```bash
505
+ ********************************************************************************
506
+ [PD] /Users/User/example.rb:1
507
+ > pd (x=1), header: true
508
+ => "1"
509
+ ```
510
+
511
+ Global Option Example:
512
+
240
513
  ```ruby
241
514
  PutsDebuggerer.header = true
242
515
  pd (x=1)
516
+ pd (x=2)
243
517
  ```
244
518
 
245
519
  Prints out:
@@ -247,8 +521,12 @@ Prints out:
247
521
  ```bash
248
522
  ********************************************************************************
249
523
  [PD] /Users/User/example.rb:2
250
- > pd x=1
524
+ > pd (x=1)
251
525
  => "1"
526
+ ********************************************************************************
527
+ [PD] /Users/User/example.rb:3
528
+ > pd (x=2)
529
+ => "2"
252
530
  ```
253
531
 
254
532
  #### `PutsDebuggerer.footer`
@@ -262,26 +540,140 @@ Footer to include at the bottom of every print out.
262
540
 
263
541
  Example:
264
542
 
543
+ ```ruby
544
+ pd (x=1), footer: true
545
+ ```
546
+
547
+ Prints out:
548
+
549
+ ```bash
550
+ [PD] /Users/User/example.rb:1
551
+ > pd (x=1), footer: true
552
+ => "1"
553
+ ********************************************************************************
554
+ ```
555
+
556
+ Global Option Example:
557
+
265
558
  ```ruby
266
559
  PutsDebuggerer.footer = true
267
560
  pd (x=1)
561
+ pd (x=2)
268
562
  ```
269
563
 
270
564
  Prints out:
271
565
 
272
566
  ```bash
273
567
  [PD] /Users/User/example.rb:2
274
- > pd x=1
568
+ > pd (x=1)
569
+ => "1"
570
+ ********************************************************************************
571
+ [PD] /Users/User/example.rb:3
572
+ > pd (x=2)
573
+ => "2"
574
+ ********************************************************************************
575
+ ```
576
+
577
+ #### `PutsDebuggerer.wrapper`
578
+ (default = `'*'*80`)
579
+
580
+ Wrapper to include at the top and bottom of every print out (both header and footer).
581
+ * Default value is `nil`
582
+ * Value `true` enables wrapper as `'*'*80`
583
+ * Value `false`, `nil`, or empty string disables wrapper
584
+ * Any other string value gets set as a custom wrapper
585
+
586
+ Example:
587
+
588
+ ```ruby
589
+ pd (x=1), wrapper: true
590
+ ```
591
+
592
+ Prints out:
593
+
594
+ ```bash
595
+ ********************************************************************************
596
+ [PD] /Users/User/example.rb:1
597
+ > pd x=1, wrapper: true
598
+ => "1"
599
+ ********************************************************************************
600
+ ```
601
+
602
+ Global Option Example:
603
+
604
+ ```ruby
605
+ PutsDebuggerer.wrapper = true
606
+ pd (x=1)
607
+ pd (x=2)
608
+ ```
609
+
610
+ Prints out:
611
+
612
+ ```bash
613
+ ********************************************************************************
614
+ [PD] /Users/User/example.rb:2
615
+ > pd (x=1)
275
616
  => "1"
276
617
  ********************************************************************************
618
+ ********************************************************************************
619
+ [PD] /Users/User/example.rb:3
620
+ > pd (x=2)
621
+ => "2"
622
+ ********************************************************************************
623
+ ```
624
+
625
+ #### `PutsDebuggerer.source_line_count`
626
+ (default = `1`)
627
+
628
+ 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.
629
+
630
+ Example:
631
+
632
+ ```ruby
633
+ pd (true ||
634
+ false), source_line_count: 2
635
+ ```
636
+
637
+ Prints out:
638
+
639
+ ```
640
+ [PD] /Users/User/example.rb:1
641
+ > pd (true ||
642
+ false), source_line_count: 2
643
+ => "true"
644
+ ```
645
+
646
+ Example:
647
+
648
+ ```ruby
649
+ PutsDebuggerer.source_line_count = 2 # setting via global option
650
+ pd (true ||
651
+ false)
652
+ ```
653
+
654
+ Prints out:
655
+
656
+ ```
657
+ [PD] /Users/User/example.rb:2
658
+ > pd (true ||
659
+ false), source_line_count: 2
660
+ => "true"
277
661
  ```
278
662
 
279
663
  #### `PutsDebuggerer.printer`
280
664
  (default = `:puts`)
281
665
 
282
- Printer is a global method symbol or lambda expression to use in printing to the user.
283
- Examples of global methods are `:puts` and `:print`.
666
+ Printer is a global method symbol, lambda expression, or logger to use in printing to the user.
667
+
668
+ Examples of a global method are `:puts` and `:print`.
284
669
  An example of a lambda expression is `lambda {|output| Rails.logger.info(output)}`
670
+ Examples of a logger are a Ruby `Logger` instance or `Logging::Logger` instance
671
+
672
+ When a logger is supplied, it is automatically enhanced with a PutsDebuggerer formatter to use
673
+ when calling logger methods outside of PutsDebuggerer (e.g. `logger.error('msg')` will use `pd`)
674
+
675
+ Printer may be set to `false` to avoid printing and only return the formatted string.
676
+ It is equivalent of just calling `.pd_inspect` (or alias `.pdi`) on the object
285
677
 
286
678
  Defaults to `:puts`
287
679
  In Rails, it defaults to:
@@ -333,7 +725,7 @@ pd array
333
725
  Prints out:
334
726
 
335
727
  ```bash
336
- [PD] /Users/User/example.rb:5
728
+ [PD] /Users/User/example.rb:4
337
729
  > pd array
338
730
  => [1, [2, 3]]
339
731
  ```
@@ -438,6 +830,34 @@ Prints out:
438
830
  /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
439
831
  ```
440
832
 
833
+ Global Option Example:
834
+
835
+ ```ruby
836
+ # File Name: /Users/User/sample_app/lib/sample.rb
837
+ PutsDebuggerer.caller = 3 # always print 3 lines only of the stack trace
838
+ pd (x=1)
839
+ pd (x=2)
840
+ ```
841
+
842
+ Prints out:
843
+
844
+ ```bash
845
+ [PD] /Users/User/sample_app/lib/sample.rb:2
846
+ > pd (x=1)
847
+ => "1"
848
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
849
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
850
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
851
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
852
+ [PD] /Users/User/sample_app/lib/sample.rb:3
853
+ > pd (x=2)
854
+ => "2"
855
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
856
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
857
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
858
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
859
+ ```
860
+
441
861
  #### `PutsDebuggerer.run_at`
442
862
  (default = nil)
443
863
 
@@ -509,20 +929,9 @@ And:
509
929
  `PutsDebuggerer.reset_run_at_numbers`
510
930
  for piecemeal usage.
511
931
 
512
- ### Bonus
513
-
514
- puts_debuggerer comes with a number of bonus goodies.
515
-
516
- It comes with [awesome_print](https://github.com/awesome-print/awesome_print).
932
+ ### Bonus API
517
933
 
518
- You may disable by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
519
-
520
- ```ruby
521
- gem "awesome_print", require: false
522
- gem "puts_debugger"
523
- ```
524
-
525
- Additionally, puts_debuggerer comes with the following bonus utility methods:
934
+ puts_debuggerer comes with the following bonus API methods:
526
935
 
527
936
  #### `__caller_line_number__(caller_depth=0)`
528
937
 
@@ -564,27 +973,37 @@ puts __caller_source_line__
564
973
 
565
974
  Prints out `puts __caller_source_line__`
566
975
 
567
- ## Release Notes
568
-
569
- * v0.8.1: `printer` option support for Rails test environment
570
- * v0.8.0: `printer` option support
571
- * v0.7.1: default print engine to :ap (AwesomePrint)
572
- * v0.7.0: `run_at` option, global and piecemeal.
573
- * v0.6.1: updated README and broke apart specs
574
- * v0.6.0: unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
575
- * v0.5.1: support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
576
- * v0.5.0: custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
577
- * v0.4.0: custom print engine (e.g. ap), custom announcer, and IRB support
578
- * v0.3.0: header/footer support, multi-line printout, improved format
579
- * v0.2.0: App path exclusion support, Rails root support, improved format
580
- * v0.1.0: File/line/expression print out
976
+ ## Compatibility
977
+
978
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) is fully compatible with:
979
+ - [Ruby](https://www.ruby-lang.org/en/)
980
+ - [JRuby](https://www.jruby.org/)
981
+ - IRB
982
+ - Rails Console.
983
+
984
+ ### Opal Ruby
985
+
986
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) provides partial-compatibility in [Opal Ruby](https://opalrb.com/) with everything working except:
987
+ - AwesomePrint (using the `:p` printer instead)
988
+ - Source code display
989
+
990
+ [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.
991
+
992
+ Here is an example of `pd` output in Opal:
993
+
994
+ ```
995
+ [PD] http://localhost:3000/assets/views/garderie_rainbow_daily_agenda/app_view.self-72626d75e0f68a619b1c8ad139535d799d45ab6c730d083820b790d71338e983.js?body=1:72:12
996
+ >
997
+ => "body"
998
+ ```
999
+
1000
+ ## Change Log
1001
+
1002
+ [CHANGELOG.md](CHANGELOG.md)
581
1003
 
582
1004
  ## TODO
583
1005
 
584
- * fix issue with printing in rspec inside a Rails project without having to do extra configuration
585
- * fix issue with erb support
586
- * display run_at run number in printout
587
- * implement fallback in irb for when line number cannot be discovered (issue happens in pry, perhaps this just means support pry)
1006
+ [TODO.md](TODO)
588
1007
 
589
1008
  ## Contributing
590
1009
 
@@ -600,5 +1019,6 @@ Prints out `puts __caller_source_line__`
600
1019
 
601
1020
  ## Copyright
602
1021
 
603
- Copyright (c) 2017 Andy Maleh. See LICENSE.txt for
604
- further details.
1022
+ [MIT](LICENSE.txt)
1023
+
1024
+ Copyright (c) 2017-2020 - Andy Maleh.