puts_debuggerer 0.8.0 → 0.10.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (11) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +77 -0
  3. data/LICENSE.txt +1 -1
  4. data/README.md +470 -54
  5. data/VERSION +1 -0
  6. data/lib/pd.rb +1 -0
  7. data/lib/puts_debuggerer.rb +231 -150
  8. data/lib/puts_debuggerer/core_ext/kernel.rb +6 -0
  9. data/lib/puts_debuggerer/run_determiner.rb +109 -0
  10. data/lib/puts_debuggerer/source_file.rb +31 -0
  11. metadata +68 -26
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 0f63870f52c5a1fcfde9556bca624180ad098c43
4
- data.tar.gz: 5e4b9f5af1b8f2d3daabb519ecc5bb490779e7c8
2
+ SHA256:
3
+ metadata.gz: 2fd0277b6264431cf1d1e83db01166e95107cbbc6dc45b0eff9adac444650372
4
+ data.tar.gz: 31276c4cb27085ccd264897fa7305e7fe1740d8f6a4a0901c73e1e2ec179c458
5
5
  SHA512:
6
- metadata.gz: 29c620c7faec7a524ee775cf3108aaad57a21ec3891763733a5222b552b7dc6507881b0b8dd173b42dacd668783d3d0fd95d4b63123943b02509b0cfb432ad62
7
- data.tar.gz: f53bdfb0185323d065bca4dc15f8bbbf319d28c545b03441102f91d05ad5db3bb336997598334e0a5682d0aec972f91ffffa7df4c17828b15861ba6ef4b87a85
6
+ metadata.gz: 96cb360a70d4118c0fc63a17b0d5d1b883f40177a8765efe2a9e135afe872686ee4090ba5e8bb5c456077545225b6a92737d2de1c315e0b3ce6184ee53ef9ac1
7
+ data.tar.gz: 751582b302545b1f4bea4fb7704125e0eb3e95057c4d0a3435042b3b2cddf2d13026f60318ef0da777c72f6b004479e8f64d0fc78f374b19ad9a8db9a78ed494
data/CHANGELOG.md ADDED
@@ -0,0 +1,77 @@
1
+ # Change Log
2
+
3
+ ## 0.10.1
4
+
5
+ - Remove the need for specifying `require 'ap'` before `require 'pd'`
6
+
7
+ ## 0.10.0
8
+
9
+ - Support `require 'pd`' as a shorter alternative to `require 'puts_debuggerer'`
10
+ - Support `printer` as a Logger object or Logging::Logger (from "logging" gem). Basically any object that responds to :debug method.
11
+ - Support `printer: false` option to return rendered String instead of printing and returning object
12
+ - Set logger formatter to PutsDebuggerer::LOGGER_FORMATTER_DECORATOR when passing as printer (keeping format the same, but decorating msg with pd)
13
+ - Add pd_inspect (and pdi alias) Kernel core extension methods
14
+ - Made awesome_print gem require happen only if printer is set to :ap or :awesome_print
15
+ - Support logging gem logger and Decorate logger layout with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR for logging gem
16
+
17
+ ## 0.9.0
18
+
19
+ - Provide partial support for Opal Ruby (missing display of file name, line number, and source code)
20
+ - `source_line_count` option
21
+ - `wraper` option for including both `header` and `footer`
22
+ - Special handling of exceptions (prints using full_message)
23
+ - Change :ap printer default to :p when unavailable
24
+ - Support varargs printing (example: `pd arg1, arg2, arg3`)
25
+ - Display `run_at` run number in printout
26
+
27
+ ## 0.8.2
28
+
29
+ - require 'stringio' for projects that don't require automatically via other gems
30
+
31
+ ## 0.8.1
32
+
33
+ - `printer` option support for Rails test environment
34
+
35
+ ## 0.8.0
36
+
37
+ - `printer` option support
38
+
39
+ ## 0.7.1
40
+
41
+ - default print engine to :ap (AwesomePrint)
42
+
43
+ ## 0.7.0
44
+
45
+ - `run_at` option, global and piecemeal.
46
+
47
+ ## 0.6.1
48
+
49
+ - updated README and broke apart specs
50
+
51
+ ## 0.6.0
52
+
53
+ - unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
54
+
55
+ ## 0.5.1
56
+
57
+ - support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
58
+
59
+ ## 0.5.0
60
+
61
+ - custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
62
+
63
+ ## 0.4.0
64
+
65
+ - custom print engine (e.g. ap), custom announcer, and IRB support
66
+
67
+ ## 0.3.0
68
+
69
+ - header/footer support, multi-line printout, improved format
70
+
71
+ ## 0.2.0
72
+
73
+ - App path exclusion support, Rails root support, improved format
74
+
75
+ ## 0.1.0
76
+
77
+ - 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
@@ -1,26 +1,41 @@
1
- # puts_debuggerer v0.8.0
1
+ # Puts Debuggerer (debugger-less debugging FTW)
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
- Partially inspired (only partially ;) by this blog post:
14
- https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
15
- (Credit to Tenderlove.)
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.
16
12
 
17
- Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+gifts)? Maybe I'll buy everyone wearing the merchandise a beer at software conferences.
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
+ ```
18
33
 
19
34
  ## Background
20
35
 
21
- 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.
22
37
 
23
- 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.
24
39
 
25
40
  Example without pd:
26
41
 
@@ -47,7 +62,29 @@ Which gets lost in a logging stream such as:
47
62
  (0.2ms) COMMIT
48
63
  ```
49
64
 
50
- 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:
51
88
 
52
89
  ```ruby
53
90
  pd order_total
@@ -61,7 +98,15 @@ Output:
61
98
  => 195.50
62
99
  ```
63
100
 
64
- 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:
65
110
 
66
111
  ```
67
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)
@@ -72,15 +117,183 @@ This is not only easy to locate in a logging stream such as the one below, but a
72
117
  (0.2ms) BEGIN
73
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]]
74
119
  (0.3ms) COMMIT
75
- [PD] /Users/User/ordering/order.rb:72
76
- > pd order_subtotal
77
- => 181.00
120
+ [PD] /Users/User/ordering/order.rb:40
121
+ > pd order_summary
122
+ => "Pragmatic Ruby Book"
78
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]]
79
124
  (0.2ms) BEGIN
80
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
81
137
  ```
82
138
 
83
- And it is easy to search for using the `[PD]` announcer.
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"
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]]
289
+ (0.2ms) BEGIN
290
+ (0.2ms) COMMIT
291
+ [PD] /Users/User/ordering/order.rb:41
292
+ > pd order_details
293
+ => "[Hard Cover] Pragmatic Ruby Book - English Version"
294
+ ```
295
+
296
+ There are many more options and powerful features in [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) as detailed below.
84
297
 
85
298
  ## Instructions
86
299
 
@@ -89,7 +302,7 @@ And it is easy to search for using the `[PD]` announcer.
89
302
  Add the following to bundler's `Gemfile`.
90
303
 
91
304
  ```ruby
92
- gem 'puts_debuggerer', '~> 0.8.0'
305
+ gem 'puts_debuggerer', '~> 0.10.1'
93
306
  ```
94
307
 
95
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.
@@ -99,13 +312,41 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
99
312
  Or manually install and require library.
100
313
 
101
314
  ```bash
102
- gem install puts_debuggerer -v0.8.0
315
+ gem install puts_debuggerer -v0.10.1
103
316
  ```
104
317
 
105
318
  ```ruby
106
319
  require 'puts_debuggerer'
107
320
  ```
108
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
+
109
350
  ### Usage
110
351
 
111
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).
@@ -159,6 +400,20 @@ Output:
159
400
 
160
401
  Happy puts_debuggerering!
161
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
+
162
417
  ### Options
163
418
 
164
419
  Options enable more data to be displayed with puts_debuggerer, such as the caller
@@ -240,9 +495,25 @@ Header to include at the top of every print out.
240
495
 
241
496
  Example:
242
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
+
243
513
  ```ruby
244
514
  PutsDebuggerer.header = true
245
515
  pd (x=1)
516
+ pd (x=2)
246
517
  ```
247
518
 
248
519
  Prints out:
@@ -250,8 +521,12 @@ Prints out:
250
521
  ```bash
251
522
  ********************************************************************************
252
523
  [PD] /Users/User/example.rb:2
253
- > pd x=1
524
+ > pd (x=1)
254
525
  => "1"
526
+ ********************************************************************************
527
+ [PD] /Users/User/example.rb:3
528
+ > pd (x=2)
529
+ => "2"
255
530
  ```
256
531
 
257
532
  #### `PutsDebuggerer.footer`
@@ -265,29 +540,149 @@ Footer to include at the bottom of every print out.
265
540
 
266
541
  Example:
267
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
+
268
558
  ```ruby
269
559
  PutsDebuggerer.footer = true
270
560
  pd (x=1)
561
+ pd (x=2)
271
562
  ```
272
563
 
273
564
  Prints out:
274
565
 
275
566
  ```bash
276
567
  [PD] /Users/User/example.rb:2
277
- > pd x=1
568
+ > pd (x=1)
278
569
  => "1"
279
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)
616
+ => "1"
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"
280
661
  ```
281
662
 
282
663
  #### `PutsDebuggerer.printer`
283
664
  (default = `:puts`)
284
665
 
285
- Printer is a global method symbol or lambda expression to use in printing to the user.
286
- 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`.
287
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
288
677
 
289
678
  Defaults to `:puts`
290
- In Rails, it defaults to: `lambda {|output| Rails.logger.debug(output)}`
679
+ In Rails, it defaults to:
680
+ ```ruby
681
+ lambda do |output|
682
+ puts output if Rails.env.test?
683
+ Rails.logger.debug(output)
684
+ end
685
+ ```
291
686
 
292
687
  Example:
293
688
 
@@ -330,7 +725,7 @@ pd array
330
725
  Prints out:
331
726
 
332
727
  ```bash
333
- [PD] /Users/User/example.rb:5
728
+ [PD] /Users/User/example.rb:4
334
729
  > pd array
335
730
  => [1, [2, 3]]
336
731
  ```
@@ -435,6 +830,34 @@ Prints out:
435
830
  /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
436
831
  ```
437
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
+
438
861
  #### `PutsDebuggerer.run_at`
439
862
  (default = nil)
440
863
 
@@ -506,20 +929,9 @@ And:
506
929
  `PutsDebuggerer.reset_run_at_numbers`
507
930
  for piecemeal usage.
508
931
 
509
- ### Bonus
932
+ ### Bonus API
510
933
 
511
- puts_debuggerer comes with a number of bonus goodies.
512
-
513
- It comes with [awesome_print](https://github.com/awesome-print/awesome_print).
514
-
515
- You may disable by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
516
-
517
- ```ruby
518
- gem "awesome_print", require: false
519
- gem "puts_debugger"
520
- ```
521
-
522
- Additionally, puts_debuggerer comes with the following bonus utility methods:
934
+ puts_debuggerer comes with the following bonus API methods:
523
935
 
524
936
  #### `__caller_line_number__(caller_depth=0)`
525
937
 
@@ -561,23 +973,26 @@ puts __caller_source_line__
561
973
 
562
974
  Prints out `puts __caller_source_line__`
563
975
 
564
- ## Release Notes
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.
565
983
 
566
- * v0.8.0: `printer` option support
567
- * v0.7.1: default print engine to :ap (AwesomePrint)
568
- * v0.7.0: `run_at` option, global and piecemeal.
569
- * v0.6.1: updated README and broke apart specs
570
- * v0.6.0: unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
571
- * v0.5.1: support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
572
- * v0.5.0: custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
573
- * v0.4.0: custom print engine (e.g. ap), custom announcer, and IRB support
574
- * v0.3.0: header/footer support, multi-line printout, improved format
575
- * v0.2.0: App path exclusion support, Rails root support, improved format
576
- * v0.1.0: File/line/expression print out
984
+ It provides partial-compatibility for [Opal Ruby](https://opalrb.com/) by excluding AwesomePrint (opting for `:p` printer instead), with everything working except these features:
985
+ - File name display
986
+ - Line number display
987
+ - Source code call display
988
+
989
+ ## Change Log
990
+
991
+ [CHANGELOG.md](CHANGELOG.md)
577
992
 
578
993
  ## TODO
579
994
 
580
- * display run_at run number in printout
995
+ [TODO.md](TODO)
581
996
 
582
997
  ## Contributing
583
998
 
@@ -593,5 +1008,6 @@ Prints out `puts __caller_source_line__`
593
1008
 
594
1009
  ## Copyright
595
1010
 
596
- Copyright (c) 2017 Andy Maleh. See LICENSE.txt for
597
- further details.
1011
+ [MIT](LICENSE.txt)
1012
+
1013
+ Copyright (c) 2017-2020 - Andy Maleh.