puts_debuggerer 0.7.1 → 0.10.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 (11) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +73 -0
  3. data/LICENSE.txt +1 -1
  4. data/README.md +548 -63
  5. data/VERSION +1 -0
  6. data/lib/pd.rb +1 -0
  7. data/lib/puts_debuggerer.rb +272 -146
  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: 15dfcef6a6e1e5beb4239710ba4b0fa7e7577b1b
4
- data.tar.gz: cf41610d09b62afd8792dfe7665cca246b89402c
2
+ SHA256:
3
+ metadata.gz: b97ba980916a6d84faa8817ed75f1cc5d19841435e707a61090c5bfaf511872e
4
+ data.tar.gz: 05e9a62ad2893e1394e18359652f5de012536b90f61ba6a2507501daaf73b774
5
5
  SHA512:
6
- metadata.gz: e5b7a1e346bd3e8d084d367fabbacaf396b9117ead8c071c3cabaf2d6645222c2e521c63876e73a710fe740121472559a174a1e44b5f54dc067199293113ce8b
7
- data.tar.gz: eac965aa078e785bc9a99b337e981dc43820af6a8c4a7bb1de8a5567b9937359315d303c221fedfa0ebd832658aac531deea44332de07d057c8ae71d960a7888
6
+ metadata.gz: 397639f53099e9fa91b5cbc7a42b0fe7c465eb2835e6b08307c5ae0b0e01036f6d3ee428c204375f2a5c977543715955f3efbd448bceb4dde59bea21f9a09290
7
+ data.tar.gz: b53f8db42dea2a575f438357e43966a478692cb73342dbc9255ed7e23196758f2e166180e26283bd06f19974a2a570e2bc01f52f5d37f27d57b939e16e40e797
data/CHANGELOG.md ADDED
@@ -0,0 +1,73 @@
1
+ # Change Log
2
+
3
+ ## 0.10.0
4
+
5
+ - Support `require 'pd`' as a shorter alternative to `require 'puts_debuggerer'`
6
+ - Support `printer` as a Logger object or Logging::Logger (from "logging" gem). Basically any object that responds to :debug method.
7
+ - Support `printer: false` option to return rendered String instead of printing and returning object
8
+ - Set logger formatter to PutsDebuggerer::LOGGER_FORMATTER_DECORATOR when passing as printer (keeping format the same, but decorating msg with pd)
9
+ - Add pd_inspect (and pdi alias) Kernel core extension methods
10
+ - Made awesome_print gem require happen only if printer is set to :ap or :awesome_print
11
+ - Support logging gem logger and Decorate logger layout with PutsDebuggerer::LOGGING_LAYOUT_DECORATOR for logging gem
12
+
13
+ ## 0.9.0
14
+
15
+ - Provide partial support for Opal Ruby (missing display of file name, line number, and source code)
16
+ - `source_line_count` option
17
+ - `wraper` option for including both `header` and `footer`
18
+ - Special handling of exceptions (prints using full_message)
19
+ - Change :ap printer default to :p when unavailable
20
+ - Support varargs printing (example: `pd arg1, arg2, arg3`)
21
+ - Display `run_at` run number in printout
22
+
23
+ ## 0.8.2
24
+
25
+ - require 'stringio' for projects that don't require automatically via other gems
26
+
27
+ ## 0.8.1
28
+
29
+ - `printer` option support for Rails test environment
30
+
31
+ ## 0.8.0
32
+
33
+ - `printer` option support
34
+
35
+ ## 0.7.1
36
+
37
+ - default print engine to :ap (AwesomePrint)
38
+
39
+ ## 0.7.0
40
+
41
+ - `run_at` option, global and piecemeal.
42
+
43
+ ## 0.6.1
44
+
45
+ - updated README and broke apart specs
46
+
47
+ ## 0.6.0
48
+
49
+ - unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
50
+
51
+ ## 0.5.1
52
+
53
+ - support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
54
+
55
+ ## 0.5.0
56
+
57
+ - custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
58
+
59
+ ## 0.4.0
60
+
61
+ - custom print engine (e.g. ap), custom announcer, and IRB support
62
+
63
+ ## 0.3.0
64
+
65
+ - header/footer support, multi-line printout, improved format
66
+
67
+ ## 0.2.0
68
+
69
+ - App path exclusion support, Rails root support, improved format
70
+
71
+ ## 0.1.0
72
+
73
+ - 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,22 +1,299 @@
1
- # puts_debuggerer v0.7.1
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 debugger 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
- In other words, puts_debuggerer is a Ruby library that provides improved puts debugging, automatically displaying bonus useful information such as source line numbers and source code, among many other goodies (mentioned in the README.)
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.
14
12
 
15
- Partially inspired (only partially ;) by this blog post:
16
- https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
17
- (Credit to Tenderlove.)
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).
18
14
 
19
- Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+gifts)?
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 'puts_debuggerer' # 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
+ ```
33
+
34
+ ## Background
35
+
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.
37
+
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.
39
+
40
+ Example without pd:
41
+
42
+ ```ruby
43
+ puts order_total
44
+ ```
45
+
46
+ Output:
47
+ ```
48
+ 195.50
49
+ ```
50
+
51
+ Which gets lost in a logging stream such as:
52
+
53
+ ```
54
+ (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)
55
+ 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]]
56
+ (0.2ms) BEGIN
57
+ 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]]
58
+ (0.3ms) COMMIT
59
+ 195.50
60
+ 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]]
61
+ (0.2ms) BEGIN
62
+ (0.2ms) COMMIT
63
+ ```
64
+
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:
88
+
89
+ ```ruby
90
+ pd order_total
91
+ ```
92
+
93
+ Output:
94
+
95
+ ```
96
+ [PD] /Users/User/ordering/order.rb:39
97
+ > pd order_total
98
+ => 195.50
99
+ ```
100
+
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:
110
+
111
+ ```
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)
113
+ 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]]
114
+ [PD] /Users/User/ordering/order.rb:39
115
+ > pd order_total
116
+ => 195.50
117
+ (0.2ms) BEGIN
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]]
119
+ (0.3ms) COMMIT
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"
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.
20
297
 
21
298
  ## Instructions
22
299
 
@@ -25,7 +302,7 @@ Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+g
25
302
  Add the following to bundler's `Gemfile`.
26
303
 
27
304
  ```ruby
28
- gem 'puts_debuggerer', '~> 0.7.1'
305
+ gem 'puts_debuggerer', '~> 0.10.0'
29
306
  ```
30
307
 
31
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.
@@ -35,20 +312,29 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
35
312
  Or manually install and require library.
36
313
 
37
314
  ```bash
38
- gem install puts_debuggerer -v0.7.1
315
+ gem install puts_debuggerer -v0.10.0
39
316
  ```
40
317
 
41
318
  ```ruby
42
319
  require 'puts_debuggerer'
43
320
  ```
44
321
 
45
- ### Usage
322
+ ### Awesome Print
46
323
 
47
- Simply invoke global `pd` method anywhere in your code passing an object or an expression argument.
324
+ puts_debuggerer comes with [awesome_print](https://github.com/awesome-print/awesome_print).
48
325
 
49
- It will then provide helpful debugging information by printing the source file, line number, and source code in addition to output (works even in IRB).
326
+ You may disable when needed by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
50
327
 
51
- Example Code:
328
+ ```ruby
329
+ gem "awesome_print", require: false
330
+ gem "puts_debuggerer"
331
+ ```
332
+
333
+ ### Usage
334
+
335
+ 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).
336
+
337
+ Example:
52
338
 
53
339
  ```ruby
54
340
  # /Users/User/finance_calculator_app/pd_test.rb # line 1
@@ -57,7 +343,7 @@ pd "Show me the source of the bug: #{bug}" # line 3
57
343
  pd "Show me the result of the calculation: #{(12.0/3.0)}" # line 4
58
344
  ```
59
345
 
60
- Example Printout:
346
+ Output:
61
347
 
62
348
  ```bash
63
349
  [PD] /Users/User/finance_calculator_app/pd_test.rb:3
@@ -68,17 +354,18 @@ Example Printout:
68
354
  => "Show me the result of the calculation: 4.0"
69
355
  ```
70
356
 
71
- Quickly locate printed lines using Find feature (e.g. CTRL+F) by looking for:
357
+ 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).
358
+
359
+ Second, quickly locate printed lines using the Find feature (e.g. CTRL+F) by looking for:
72
360
  * [PD]
73
361
  * file:line_number
74
362
  * known ruby expression.
75
363
 
76
- This gives you the added benefit of easily removing your `pd` statements later
77
- on once done debugging.
364
+ Third, easily remove your ` pd ` statements via the source code Find feature once done debugging.
78
365
 
79
366
  Note that `pd` returns the passed in object or expression argument unchanged, permitting debugging with shorter syntax than tap, and supporting chaining of extra method invocations afterward.
80
367
 
81
- Example Code:
368
+ Example:
82
369
 
83
370
  ```ruby
84
371
  # /Users/User/greeting_app/pd_test.rb # line 1
@@ -86,7 +373,7 @@ name = 'Robert' # line 2
86
373
  greeting = "Hello #{pd(name)}" # line 3
87
374
  ```
88
375
 
89
- Example Printout:
376
+ Output:
90
377
 
91
378
  ```bash
92
379
  [PD] /Users/User/greeting_app/pd_test.rb:3
@@ -94,8 +381,15 @@ Example Printout:
94
381
  => "Hello Robert"
95
382
  ```
96
383
 
384
+ Alternatively, you may want to use `object.pd_inspect` (or alias `obj.pdi`) to
385
+ return formatted string without printing.
386
+
97
387
  Happy puts_debuggerering!
98
388
 
389
+ #### Ruby Logger and Logging::Logger
390
+
391
+ Ruby Logger and Logging::Logger (from [logging gem](https://github.com/TwP/logging)) are supported as [printers](#putsdebuggererprinter) (learn more under [PutsDebuggerer#printer](#putsdebuggererprinter)).
392
+
99
393
  ### Options
100
394
 
101
395
  Options enable more data to be displayed with puts_debuggerer, such as the caller
@@ -177,9 +471,25 @@ Header to include at the top of every print out.
177
471
 
178
472
  Example:
179
473
 
474
+ ```ruby
475
+ pd (x=1), header: true
476
+ ```
477
+
478
+ Prints out:
479
+
480
+ ```bash
481
+ ********************************************************************************
482
+ [PD] /Users/User/example.rb:1
483
+ > pd (x=1), header: true
484
+ => "1"
485
+ ```
486
+
487
+ Global Option Example:
488
+
180
489
  ```ruby
181
490
  PutsDebuggerer.header = true
182
491
  pd (x=1)
492
+ pd (x=2)
183
493
  ```
184
494
 
185
495
  Prints out:
@@ -187,8 +497,12 @@ Prints out:
187
497
  ```bash
188
498
  ********************************************************************************
189
499
  [PD] /Users/User/example.rb:2
190
- > pd x=1
500
+ > pd (x=1)
191
501
  => "1"
502
+ ********************************************************************************
503
+ [PD] /Users/User/example.rb:3
504
+ > pd (x=2)
505
+ => "2"
192
506
  ```
193
507
 
194
508
  #### `PutsDebuggerer.footer`
@@ -202,33 +516,184 @@ Footer to include at the bottom of every print out.
202
516
 
203
517
  Example:
204
518
 
519
+ ```ruby
520
+ pd (x=1), footer: true
521
+ ```
522
+
523
+ Prints out:
524
+
525
+ ```bash
526
+ [PD] /Users/User/example.rb:1
527
+ > pd (x=1), footer: true
528
+ => "1"
529
+ ********************************************************************************
530
+ ```
531
+
532
+ Global Option Example:
533
+
205
534
  ```ruby
206
535
  PutsDebuggerer.footer = true
207
536
  pd (x=1)
537
+ pd (x=2)
208
538
  ```
209
539
 
210
540
  Prints out:
211
541
 
212
542
  ```bash
213
543
  [PD] /Users/User/example.rb:2
214
- > pd x=1
544
+ > pd (x=1)
545
+ => "1"
546
+ ********************************************************************************
547
+ [PD] /Users/User/example.rb:3
548
+ > pd (x=2)
549
+ => "2"
550
+ ********************************************************************************
551
+ ```
552
+
553
+ #### `PutsDebuggerer.wrapper`
554
+ (default = `'*'*80`)
555
+
556
+ Wrapper to include at the top and bottom of every print out (both header and footer).
557
+ * Default value is `nil`
558
+ * Value `true` enables wrapper as `'*'*80`
559
+ * Value `false`, `nil`, or empty string disables wrapper
560
+ * Any other string value gets set as a custom wrapper
561
+
562
+ Example:
563
+
564
+ ```ruby
565
+ pd (x=1), wrapper: true
566
+ ```
567
+
568
+ Prints out:
569
+
570
+ ```bash
571
+ ********************************************************************************
572
+ [PD] /Users/User/example.rb:1
573
+ > pd x=1, wrapper: true
215
574
  => "1"
216
575
  ********************************************************************************
217
576
  ```
218
577
 
578
+ Global Option Example:
579
+
580
+ ```ruby
581
+ PutsDebuggerer.wrapper = true
582
+ pd (x=1)
583
+ pd (x=2)
584
+ ```
585
+
586
+ Prints out:
587
+
588
+ ```bash
589
+ ********************************************************************************
590
+ [PD] /Users/User/example.rb:2
591
+ > pd (x=1)
592
+ => "1"
593
+ ********************************************************************************
594
+ ********************************************************************************
595
+ [PD] /Users/User/example.rb:3
596
+ > pd (x=2)
597
+ => "2"
598
+ ********************************************************************************
599
+ ```
600
+
601
+ #### `PutsDebuggerer.source_line_count`
602
+ (default = `1`)
603
+
604
+ 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.
605
+
606
+ Example:
607
+
608
+ ```ruby
609
+ pd (true ||
610
+ false), source_line_count: 2
611
+ ```
612
+
613
+ Prints out:
614
+
615
+ ```
616
+ [PD] /Users/User/example.rb:1
617
+ > pd (true ||
618
+ false), source_line_count: 2
619
+ => "true"
620
+ ```
621
+
622
+ Example:
623
+
624
+ ```ruby
625
+ PutsDebuggerer.source_line_count = 2 # setting via global option
626
+ pd (true ||
627
+ false)
628
+ ```
629
+
630
+ Prints out:
631
+
632
+ ```
633
+ [PD] /Users/User/example.rb:2
634
+ > pd (true ||
635
+ false), source_line_count: 2
636
+ => "true"
637
+ ```
638
+
639
+ #### `PutsDebuggerer.printer`
640
+ (default = `:puts`)
641
+
642
+ Printer is a global method symbol, lambda expression, or logger to use in printing to the user.
643
+
644
+ Examples of a global method are `:puts` and `:print`.
645
+ An example of a lambda expression is `lambda {|output| Rails.logger.info(output)}`
646
+ Examples of a logger are a Ruby `Logger` instance or `Logging::Logger` instance
647
+
648
+ When a logger is supplied, it is automatically enhanced with a PutsDebuggerer formatter to use
649
+ when calling logger methods outside of PutsDebuggerer (e.g. `logger.error('msg')` will use `pd`)
650
+
651
+ Printer may be set to `false` to avoid printing and only return the formatted string.
652
+ It is equivalent of just calling `.pd_inspect` (or alias `.pdi`) on the object
653
+
654
+ Defaults to `:puts`
655
+ In Rails, it defaults to:
656
+ ```ruby
657
+ lambda do |output|
658
+ puts output if Rails.env.test?
659
+ Rails.logger.debug(output)
660
+ end
661
+ ```
662
+
663
+ Example:
664
+
665
+ ```ruby
666
+ # File Name: /Users/User/example.rb
667
+ PutsDebuggerer.printer = lambda {|output| Rails.logger.error(output)}
668
+ str = "Hello"
669
+ pd str
670
+ ```
671
+
672
+ Prints out in the Rails app log as error lines:
673
+
674
+ ```bash
675
+ [PD] /Users/User/example.rb:5
676
+ > pd str
677
+ => Hello
678
+ ```
679
+
219
680
  #### `PutsDebuggerer.print_engine`
220
681
  (default = `:ap`)
221
682
 
222
- Print engine is a global method symbol or lambda expression to use in object printout. Examples of global methods are `:p`, `:ap`, and `:pp`. An example of a lambda expression is `lambda {|o| Rails.logger.info(o)}`
683
+ Print engine is similar to `printer`, except it is focused on the scope of formatting
684
+ the data object being printed (excluding metadata such as file name, line number,
685
+ and expression, which are handled by the `printer`).
686
+ As such, it is also a global method symbol or lambda expression.
687
+ Examples of global methods are `:p`, `:ap`, and `:pp`.
688
+ An example of a lambda expression is `lambda {|object| puts object.to_a.join(" | ")}`
223
689
 
224
- Defaults to [awesome_print](https://github.com/awesome-print/awesome_print). If it finds Rails loaded it defaults to `lambda {|o| Rails.logger.ap(o)}` instead
690
+ Defaults to [awesome_print](https://github.com/awesome-print/awesome_print).
225
691
 
226
692
  Example:
227
693
 
228
694
  ```ruby
229
695
  # File Name: /Users/User/example.rb
230
- require 'awesome_print'
231
- PutsDebuggerer.print_engine = :ap
696
+ PutsDebuggerer.print_engine = :p
232
697
  array = [1, [2, 3]]
233
698
  pd array
234
699
  ```
@@ -236,15 +701,9 @@ pd array
236
701
  Prints out:
237
702
 
238
703
  ```bash
239
- [PD] /Users/User/example.rb:5
704
+ [PD] /Users/User/example.rb:4
240
705
  > pd array
241
- => [
242
- [0] 1,
243
- [1] [
244
- [0] 2,
245
- [1] 3
246
- ]
247
- ]
706
+ => [1, [2, 3]]
248
707
  ```
249
708
 
250
709
  #### `PutsDebuggerer.announcer`
@@ -347,6 +806,34 @@ Prints out:
347
806
  /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
348
807
  ```
349
808
 
809
+ Global Option Example:
810
+
811
+ ```ruby
812
+ # File Name: /Users/User/sample_app/lib/sample.rb
813
+ PutsDebuggerer.caller = 3 # always print 3 lines only of the stack trace
814
+ pd (x=1)
815
+ pd (x=2)
816
+ ```
817
+
818
+ Prints out:
819
+
820
+ ```bash
821
+ [PD] /Users/User/sample_app/lib/sample.rb:2
822
+ > pd (x=1)
823
+ => "1"
824
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
825
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
826
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
827
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
828
+ [PD] /Users/User/sample_app/lib/sample.rb:3
829
+ > pd (x=2)
830
+ => "2"
831
+ /Users/User/sample_app/lib/master_samples.rb:368:in \`block (3 levels) in <top (required)>\'
832
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`eval\'
833
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/workspace.rb:87:in \`evaluate\'
834
+ /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
835
+ ```
836
+
350
837
  #### `PutsDebuggerer.run_at`
351
838
  (default = nil)
352
839
 
@@ -418,20 +905,9 @@ And:
418
905
  `PutsDebuggerer.reset_run_at_numbers`
419
906
  for piecemeal usage.
420
907
 
421
- ### Bonus
422
-
423
- puts_debuggerer comes with a number of bonus goodies.
424
-
425
- It comes with [awesome_print](https://github.com/awesome-print/awesome_print).
426
-
427
- You may disable by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
428
-
429
- ```ruby
430
- gem "awesome_print", require: false
431
- gem "puts_debugger"
432
- ```
908
+ ### Bonus API
433
909
 
434
- Additionally, puts_debuggerer comes with the following bonus utility methods:
910
+ puts_debuggerer comes with the following bonus API methods:
435
911
 
436
912
  #### `__caller_line_number__(caller_depth=0)`
437
913
 
@@ -473,18 +949,26 @@ puts __caller_source_line__
473
949
 
474
950
  Prints out `puts __caller_source_line__`
475
951
 
476
- ## Release Notes
952
+ ## Compatibility
953
+
954
+ [puts_debuggerer](https://rubygems.org/gems/puts_debuggerer) is fully compatible with:
955
+ - [Ruby](https://www.ruby-lang.org/en/)
956
+ - [JRuby](https://www.jruby.org/)
957
+ - IRB
958
+ - Rails Console.
959
+
960
+ It provides partial-compatibility for [Opal Ruby](https://opalrb.com/), with everything working except these features:
961
+ - File name display
962
+ - Line number display
963
+ - Source code call display
964
+
965
+ ## Change Log
477
966
 
478
- * v0.7.1: default print engine to :ap (AwesomePrint)
479
- * v0.7.0: `run_at` option, global and piecemeal.
480
- * v0.6.1: updated README and broke apart specs
481
- * v0.6.0: unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
482
- * v0.5.1: support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
483
- * v0.5.0: custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
484
- * v0.4.0: custom print engine (e.g. ap), custom announcer, and IRB support
485
- * v0.3.0: header/footer support, multi-line printout, improved format
486
- * v0.2.0: App path exclusion support, Rails root support, improved format
487
- * v0.1.0: File/line/expression print out
967
+ [CHANGELOG.md](CHANGELOG.md)
968
+
969
+ ## TODO
970
+
971
+ [TODO.md](TODO)
488
972
 
489
973
  ## Contributing
490
974
 
@@ -500,5 +984,6 @@ Prints out `puts __caller_source_line__`
500
984
 
501
985
  ## Copyright
502
986
 
503
- Copyright (c) 2017 Andy Maleh. See LICENSE.txt for
504
- further details.
987
+ [MIT](LICENSE.txt)
988
+
989
+ Copyright (c) 2017-2020 - Andy Maleh.