pry-rescue 0.18.1 → 1.0.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.
data/README.md CHANGED
@@ -1,18 +1,59 @@
1
+ **pry-rescue** - super-fast debugging for ruby. (See [Pry to the
2
+ rescue!](http://cirw.in/blog/pry-to-the-rescue))
1
3
 
2
- **pry-rescue** super-fast, painless, debugging for the (ruby) masses. (See [Pry to the rescue!](http://cirw.in/blog/pry-to-the-rescue))
4
+ Introduction
5
+ ============
6
+
7
+ pry-rescue is an implementation of "break on unhandled exception" for Ruby. Whenever an
8
+ exception is raised, but not rescued, pry-rescue will automatically open pry for you:
9
+
10
+ ```ruby
11
+ $ rescue examples/example2.rb
12
+ From: /home/conrad/0/ruby/pry-rescue/examples/example2.rb @ line 19 Object#beta:
13
+
14
+ 17: def beta
15
+ 18: y = 30
16
+ => 19: gamma(1, 2)
17
+ 20: end
18
+
19
+ ArgumentError: wrong number of arguments (2 for 1)
20
+ from /home/conrad/0/ruby/pry-rescue/examples/example2.rb:22:in `gamma`
21
+ [1] pry(main)>
22
+ ```
23
+
24
+ Installation
25
+ ============
26
+
27
+ You can install `pry-rescue` with rubygems as normal, and I strongly recommend you also
28
+ install `pry-stack_explorer`. See [Known bugs](#known-bugs) for places that won't work.
29
+
30
+ ```
31
+ gem install pry-rescue pry-stack_explorer
32
+ ```
33
+
34
+ If you're using Bundler, you can add it to your Gemfile in the development group:
35
+
36
+ ```ruby
37
+ group :development do
38
+ gem 'pry-rescue'
39
+ gem 'pry-stack_explorer'
40
+ end
41
+ ```
3
42
 
4
43
  Usage
5
44
  =====
6
45
 
7
- First `gem install pry-rescue pry-stack_explorer`. Then run your program with `rescue`
8
- instead of `ruby`:
46
+ For simple ruby scripts, just run them with the `rescue` executable instead of the `ruby`
47
+ executable.
9
48
 
10
49
  ```
11
50
  rescue <script.rb> [arguments..]
12
51
  ```
13
52
 
14
- If you're using Rails, you should add `pry-rescue` to the development section of your
15
- Gemspec and then run rails server using rescue:
53
+ Rails
54
+ -----
55
+
56
+ For rails, use `rescue rails` in place of `rails`, for example:
16
57
 
17
58
  ```
18
59
  rescue rails server
@@ -24,75 +65,83 @@ If you're using `bundle exec` the rescue should go after the exec:
24
65
  bundle exec rescue rails server
25
66
  ```
26
67
 
27
- If you're using Rack, you should use the middleware instead (though be careful to only
28
- include it in development!)
29
- ```
30
- use PryRescue::Rack
31
- ```
68
+ Then whenever an unhandled exception happens inside rails, a pry console will open on
69
+ stdout. This is the same terminal that you see the rails logs on, so if you're
70
+ using something like [pow](https://pow.cx) then you will run into difficulties.
32
71
 
33
- If you're using rspec, you should add `pry-rescue` to your Gemfile and then you can
34
- enable rescuing on failed tests by running:
72
+ You might also be interested in
73
+ [better_errors](https://github.com/charliesome/better_errors) which opens consoles in your
74
+ browser on unhandled exceptions, and [pry-rails](https://github.com/rweng/pry-rails) which
75
+ adds some rails specific helpers to pry, and replaces `rails console` by pry.
35
76
 
36
- ```
37
- rescue rspec
38
- ```
77
+ Rspec
78
+ -----
39
79
 
40
- If you want more fine-grained control over which parts of your code are rescued, you can
41
- also use the block form:
80
+ If you're using [RSpec](https://rspec.org) or
81
+ [respec](https://github.com/oggy/respec), you can open a pry session on
82
+ every test failure using `rescue rspec` or `rescue respec`:
42
83
 
43
84
  ```ruby
44
- require 'pry-rescue'
45
-
46
- def test
47
- raise "foo"
48
- rescue => e
49
- raise "bar"
50
- end
51
-
52
- Pry.rescue do
53
- test
54
- end
85
+ $ rescue rspec
86
+ From: /home/conrad/0/ruby/pry-rescue/examples/example_spec.rb @ line 9 :
87
+
88
+ 6:
89
+ 7: describe "Float" do
90
+ 8: it "should be able to add" do
91
+ => 9: (0.1 + 0.2).should == 0.3
92
+ 10: end
93
+ 11: end
94
+
95
+ RSpec::Expectations::ExpectationNotMetError: expected: 0.3
96
+ got: 0.30000000000000004 (using ==)
97
+ [1] pry(main)>
55
98
  ```
56
- This will land you in a pry-session:
57
99
 
58
- ```
59
- From: examples/example.rb @ line 4 Object#test:
100
+ Unfortunately using `edit -c` to edit `_spec.rb` files does not yet reload the
101
+ code in a way that the `try-again` command can understand. You can still use
102
+ `try-again` if you edit code that is not in spec files.
60
103
 
61
- 4: def test
62
- 5: raise "foo"
63
- 6: rescue => e
64
- => 7: raise "bar"
65
- 8: end
104
+ Minitest
105
+ --------
66
106
 
67
- RuntimeError: bar
68
- from examples/example.rb:7:in `rescue in test'
69
- [1] pry(main)>
107
+ Add the following to your `test_helper.rb` or to the top of your test file.
108
+
109
+ ```ruby
110
+ require 'minitest/autorun'
111
+ require 'pry-rescue/minitest'
70
112
  ```
71
113
 
72
- Finally. If you're doing your own exception handling, you can ask pry to open on an exception that you've caught.
73
- For this to work you must be inside a Pry::rescue{ } block.
114
+ Then, when you have a failure, you can use `edit`, `edit -c`, and `edit-method`, then
115
+ `try-again` to re-run the tests.
74
116
 
75
- ```ruby
76
- def test
77
- raise "foo"
78
- rescue => e
79
- Pry::rescued(e)
80
- end
117
+ Rack
118
+ ----
81
119
 
82
- Pry::rescue{ test }
120
+ If you're using Rack, you should use the middleware instead (though be careful to only
121
+ include it in development!):
122
+
123
+ ```
124
+ use PryRescue::Rack if ENV["RACK_ENV"] == 'development'
83
125
  ```
84
126
 
85
- cd-raise
86
- ========
127
+ Pry commands
128
+ ============
129
+
130
+ `pry-rescue` adds two commands to pry. `cd-cause` and `try-again`. In combination with
131
+ `edit --method` these can let you fix the problem with your code and verify that the fix
132
+ worked without restarting your program.
133
+
134
+ cd-cause
135
+ --------
87
136
 
88
- If you've run some code in Pry, and an exception was raised, you can use the `cd-raise`
137
+ If you've run some code in Pry, and an exception was raised, you can use the `cd-cause`
89
138
  command:
90
139
 
91
- ```
140
+ ```ruby
92
141
  [1] pry(main)> foo
93
142
  RuntimeError: two
94
- from a.rb:4:in `rescue in foo'
95
- [2] pry(main)> cd-raise
143
+ from a.rb:4:in `rescue in foo`
144
+ [2] pry(main)> cd-cause
96
145
  From: a.rb @ line 4 Object#foo:
97
146
 
98
147
  1: def foo
@@ -101,19 +150,14 @@ From: a.rb @ line 4 Object#foo:
101
150
  => 4: raise "two"
102
151
  5: end
103
152
 
104
- [1] pry(main)>
153
+ [3] pry(main)>
105
154
  ```
106
155
 
107
- To get back from `cd-raise` you can either type `<ctrl+d>` or `cd ..`.
156
+ If that exception was in turn caused by a previous exception you can use
157
+ `cd-cause` again to move to the original problem:
108
158
 
109
- cd-cause
110
- ========
111
-
112
- If you need to find the reason that the exception happened, you can use the `cd-cause`
113
- command:
114
-
115
- ```
116
- [1] pry(main)> cd-cause
159
+ ```ruby
160
+ [3] pry(main)> cd-cause
117
161
  From: examples/example.rb @ line 4 Object#test:
118
162
 
119
163
  4: def test
@@ -123,22 +167,23 @@ From: examples/example.rb @ line 4 Object#test:
123
167
  8: end
124
168
 
125
169
  RuntimeError: foo
126
- from examples/example.rb:5:in `test'
127
- [1] pry(main)>
170
+ from examples/example.rb:5:in `test`
171
+ [4] pry(main)>
128
172
  ```
129
173
 
130
174
  To get back from `cd-cause` you can either type `<ctrl+d>` or `cd ..`.
131
175
 
132
176
  try-again
133
- =========
177
+ ---------
134
178
 
135
- Once you've used Pry's `edit` or `edit-method` commands to fix your code, you can issue a
136
- `try-again` command to re-run your code. (Either from the start in the case of using the
137
- `rescue` script, or from the block if you're using that API).
179
+ Once you've used Pry's `edit` or command to fix your code, you can issue a `try-again`
180
+ command to re-run your code. For rails and rack, this re-runs the request, for minitest
181
+ and rspec, it re-runs the current test, for more advanced users this re-runs the
182
+ `Pry::rescue{ }` block.
138
183
 
139
- ```
140
- [1] pry(main)> edit-method
141
- [2] pry(main)> whereami
184
+ ```ruby
185
+ [4] pry(main)> edit --method
186
+ [5] pry(main)> whereami
142
187
  From: examples/example.rb @ line 4 Object#test:
143
188
 
144
189
  4: def test
@@ -146,45 +191,64 @@ From: examples/example.rb @ line 4 Object#test:
146
191
  6: rescue => e
147
192
  7: raise "bar"
148
193
  8: end
149
- [3] pry(main)> try-again
194
+ [6] pry(main)> try-again
150
195
  foo
151
196
  ```
152
197
 
153
- Testing
154
- =======
198
+ Advanced usage
199
+ ==============
155
200
 
156
- Pry-rescue comes with beta support for minitest and rspec: test failures will
157
- drop you into pry at that location. Please feel free to try these out, and
158
- leave bug reports if something is not working.
201
+ Block form
202
+ ----------
159
203
 
160
- Note that for either of these, you will find `exit!` very handy: there is a pry
161
- `exit` command that will merely drop you into the next failure.
204
+ If you want more fine-grained control over which parts of your code are rescued, you can
205
+ also use the block form:
162
206
 
163
- ### minitest
207
+ ```ruby
208
+ require 'pry-rescue'
164
209
 
165
- Add the following to your `test_helper.rb` or to the top of your test file.
210
+ def test
211
+ raise "foo"
212
+ rescue => e
213
+ raise "bar"
214
+ end
166
215
 
167
- ```ruby
168
- require 'minitest/autorun'
169
- require 'pry-rescue/minitest'
216
+ Pry.rescue do
217
+ test
218
+ end
170
219
  ```
220
+ This will land you in a pry-session:
171
221
 
172
- Then, when you have a failure, you can use `edit`, `edit -c`, and `edit-method`, then
173
- `try-again` to re-run the tests, or run it by name (`test_foo`).
174
-
175
- ### rspec
222
+ ```
223
+ From: examples/example.rb @ line 4 Object#test:
176
224
 
177
- Add the following to your `spec_helper.rb` or to the top of your test file.
225
+ 4: def test
226
+ 5: raise "foo"
227
+ 6: rescue => e
228
+ => 7: raise "bar"
229
+ 8: end
178
230
 
179
- ```ruby
180
- require 'pry-rescue/rspec'
231
+ RuntimeError: bar
232
+ from examples/example.rb:7:in `rescue in test`
233
+ [1] pry(main)>
181
234
  ```
182
235
 
183
- Note that, unlike minitest, rspec creates odd structures instead of classes, so
184
- it is somewhat resistant to live-coding practices. In particular, `edit -c` to
185
- edit the test then `try-again` doesn't work (so you'll have to `exit!`).
236
+ Rescuing an exception
237
+ ---------------------
186
238
 
239
+ Finally. If you're doing your own exception handling, you can ask pry to open on an exception that you've caught.
240
+ For this to work you must be inside a Pry::rescue{ } block.
241
+
242
+ ```ruby
243
+ def test
244
+ raise "foo"
245
+ rescue => e
246
+ Pry::rescued(e)
247
+ end
187
248
 
249
+ Pry::rescue{ test }
250
+
251
+ ```
188
252
  Peeking
189
253
  =======
190
254
 
@@ -195,7 +259,7 @@ suprisingly long time to run.
195
259
  In this case it's useful to be able to open a pry console when you notice that your
196
260
  program is not going anywhere. To do this, send your process a `SIGQUIT` using `<ctrl+\>`.
197
261
 
198
- ```
262
+ ```ruby
199
263
  cirwin@localhost:/tmp/pry $ ruby examples/loop.rb
200
264
  ^\
201
265
  Preparing to peek via pry!
@@ -212,9 +276,10 @@ pry (main)>
212
276
  ```
213
277
 
214
278
  Advanced peeking
215
- ================
279
+ ----------------
216
280
 
217
- You can configure which signal pry-rescue listens for by default by exporting the PRY_PEEK
281
+ You can configure which signal pry-rescue listens for by default by exporting the
282
+ `PRY_PEEK`
218
283
  environment variable that suits your use-case best:
219
284
 
220
285
  ```
@@ -254,14 +319,6 @@ you trigger the signal.
254
319
  export RUBYOPT=-r/home/cirwin/src/pry-rescue/lib/pry-rescue/peek/usr2
255
320
  ```
256
321
 
257
- pry-stack explorer
258
- ==================
259
-
260
- If you're running rubinius, or ruby-1.9, then you can use `pry-rescue` alongside
261
- `pry-stack\_explorer`. This gives you the ability to move `up` or `down` the stack so that
262
- you can get a better idea of why your function ended up in a bad state. Run
263
- [example2.rb](https://github.com/ConradIrwin/pry-rescue/blob/master/examples/example2.rb) to get a feel for what this is like.
264
-
265
322
  Known bugs
266
323
  ==========
267
324
 
data/bin/rescue CHANGED
@@ -27,13 +27,10 @@ when '--'
27
27
  when /\A-/
28
28
  puts USAGE
29
29
  exit
30
- end
31
-
32
- case ARGV[0]
33
30
  when 'rails'
34
- ENV['PRY_RESCUE'] = 'rails'
31
+ ENV['PRY_RESCUE_RAILS'] = 'true'
35
32
  exec(*ARGV)
36
- when 'rspec'
33
+ when /^re?spec|rake$/
37
34
  ENV['SPEC_OPTS'] = "#{ENV['SPEC_OPTS']} -r pry-rescue/rspec"
38
35
  exec(*ARGV)
39
36
  end
@@ -0,0 +1,11 @@
1
+ require 'rspec'
2
+ require 'rspec/autorun'
3
+
4
+ $:.unshift File.expand_path '../../lib', __FILE__
5
+ require 'pry-rescue'
6
+
7
+ describe "Float" do
8
+ it "should be able to add" do
9
+ (0.1 + 0.2).should == 0.3
10
+ end
11
+ end
@@ -1,75 +1,59 @@
1
1
  Pry::Commands.create_command "cd-cause", "Move to the exception that caused this exception to happen" do
2
2
 
3
3
  banner <<-BANNER
4
- Usage: cd-cause
4
+ Usage: cd-cause [_ex_]
5
5
 
6
- Starts a new pry session at the previously raised exception.
6
+ Starts a new Pry session at the previously raised exception.
7
7
 
8
- This is useful if you've caught one exception, and raised another,
9
- if you need to find out why the original was raised.
8
+ If you have many layers of exceptions that are rescued and then re-raised,
9
+ you can repeat cd-cause as many times as you need.
10
10
 
11
- @example
12
- 5. def foo
13
- 6. raise "one"
14
- 7. rescue
15
- 8. => raise "two"
16
- 9. end
17
-
18
- pry> cd-cause
19
-
20
- 5. def foo
21
- 6. => raise "one"
22
- 7. rescue
23
- 8. raise "two"
24
- 9. end
25
-
26
- Once you have finished with the internal exception type <ctrl+d> or cd .. to
27
- return to where you were.
28
-
29
- If you have many layers of exceptions that are rescued and then re-raised, you
30
- can repeat cd-cause as many times as you need.
31
- BANNER
32
-
33
- def process
34
- raised = target.eval("_raised_.dup rescue nil")
35
- raise Pry::CommandError, "cd-cause only works in a pry session created by Pry::rescue{}" unless raised
36
- raised.pop
37
-
38
- if raised.any?
39
- PryRescue.enter_exception_context(raised)
40
- else
41
- raise Pry::CommandError, "No previous exception detected"
42
- end
43
- end
44
- end
45
-
46
- Pry::Commands.create_command "cd-raise", "Move to the point at which an exception was raised" do
47
- banner <<-BANNER
48
- Usage: cd-raise [_ex_]
49
-
50
- Starts a new pry session at the point that the given exception was raised.
51
-
52
- If no exception is given, defaults to _ex_, the most recent exception that
53
- was raised by code you ran from within pry.
11
+ The cd-cause command is useful if:
12
+ - You've just caused an exception within Pry, and you want to see why
13
+ - When an intermediate exception handler
14
+ - Intentionally re-raises an exception
15
+ - Has a bug that causes an inadvertent exception
54
16
 
55
17
  @example
56
-
57
18
  [2] pry(main)> foo
58
19
  RuntimeError: two
59
20
  from /home/conrad/0/ruby/pry-rescue/a.rb:4:in `rescue in foo'
60
- [3] pry(main)> cd-raise
21
+ [3] pry(main)> cd-cause
61
22
 
62
23
  1: def foo
63
24
  2: raise "one"
64
25
  3: rescue => e
65
26
  => 4: raise "two"
66
27
  5: end
28
+
29
+ [4] pry(main)> cd-cause
30
+
31
+ 1: def foo
32
+ => 2: raise "one"
33
+ 3: rescue => e
34
+ 4: raise "two"
35
+ 5: end
36
+
37
+ Once you have finished inspecting the exception, type <ctrl+d> or cd .. to
38
+ return to where you were.
67
39
  BANNER
68
40
 
69
41
  def process
70
- ex = target.eval(args.first || "_ex_")
71
- raise Pry::CommandError, "No most recent exception" unless ex
72
- Pry.rescued(ex)
42
+ return Pry.rescued target.eval(args.first) if args.any?
43
+
44
+ # TODO: better understand why !defined?(_ex_)
45
+ ex = target.eval("defined?(_ex_) && _ex_")
46
+ raised = target.eval("_raised_.dup rescue nil")
47
+
48
+ ex_was_raised = raised && raised.last.first == ex
49
+ if ex && !ex_was_raised
50
+ Pry.rescued(ex)
51
+ elsif ex_was_raised && raised.size > 1
52
+ raised.pop
53
+ PryRescue.enter_exception_context(raised)
54
+ else
55
+ raise Pry::CommandError, "No previous exception detected"
56
+ end
73
57
  end
74
58
  end
75
59
 
data/pry-rescue.gemspec CHANGED
@@ -1,6 +1,6 @@
1
1
  Gem::Specification.new do |s|
2
2
  s.name = 'pry-rescue'
3
- s.version = '0.18.1'
3
+ s.version = '1.0.0'
4
4
  s.summary = 'Open a pry session on any unhandled exceptions'
5
5
  s.description = 'Allows you to wrap code in Pry::rescue{ } to open a pry session at any unhandled exceptions'
6
6
  s.homepage = 'https://github.com/ConradIrwin/pry-rescue'
@@ -1,3 +1,5 @@
1
+ require './spec/spec_helper'
2
+
1
3
  describe "pry-rescue commands" do
2
4
  describe "try-again" do
3
5
  it "should throw try_again" do
@@ -17,7 +19,7 @@ describe "pry-rescue commands" do
17
19
  end
18
20
  end
19
21
 
20
- describe "cd-raise" do
22
+ describe "cd-cause" do
21
23
  it "should enter the context of an explicit exception" do
22
24
  begin
23
25
  b1 = binding
@@ -30,7 +32,7 @@ describe "pry-rescue commands" do
30
32
  raised.should == e1
31
33
  }
32
34
 
33
- Pry.new.process_command 'cd-raise e1', '', binding
35
+ Pry.new.process_command 'cd-cause e1', '', binding
34
36
  end
35
37
 
36
38
  it "should enter the context of _ex_ if no exception is given" do
@@ -45,7 +47,7 @@ describe "pry-rescue commands" do
45
47
  raised.should == _ex_
46
48
  }
47
49
 
48
- Pry.new.process_command 'cd-raise', '', binding
50
+ Pry.new.process_command 'cd-cause', '', binding
49
51
  end
50
52
  end
51
53
 
@@ -57,10 +59,12 @@ describe "pry-rescue commands" do
57
59
  raise "original"
58
60
  rescue => e1
59
61
  b2 = binding
60
- raise
62
+ raise # similar to dubious re-raises you'll find in the wild
61
63
  end
62
64
  rescue => e2
65
+ # Hacks due to us not really entering a pry session here
63
66
  _raised_ = [[e1, [b1]], [e2, [b2]]]
67
+ _ex_ = e2
64
68
  end
65
69
 
66
70
  PryRescue.should_receive(:enter_exception_context).once.with{ |raised|
@@ -75,7 +79,9 @@ describe "pry-rescue commands" do
75
79
  b1 = binding
76
80
  raise "original"
77
81
  rescue => e1
82
+ # Hacks due to us not really entering a pry session here
78
83
  _raised_ = [[e1, [b1]]]
84
+ _ex_ = e1
79
85
  end
80
86
 
81
87
  lambda{
@@ -86,7 +92,7 @@ describe "pry-rescue commands" do
86
92
  it "should raise a CommandError if not in Pry::rescue" do
87
93
  lambda{
88
94
  Pry.new.process_command 'cd-cause', '', binding
89
- }.should raise_error Pry::CommandError, /Pry::rescue/
95
+ }.should raise_error Pry::CommandError, /No previous exception/
90
96
  end
91
97
  end
92
98
  end
@@ -0,0 +1,6 @@
1
+ require 'rspec'
2
+ require 'rspec/autorun'
3
+
4
+ require 'pry/test/helper'
5
+
6
+ require './lib/pry-rescue'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pry-rescue
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.18.1
4
+ version: 1.0.0
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -11,7 +11,7 @@ authors:
11
11
  autorequire:
12
12
  bindir: bin
13
13
  cert_chain: []
14
- date: 2013-02-14 00:00:00.000000000 Z
14
+ date: 2013-02-17 00:00:00.000000000 Z
15
15
  dependencies:
16
16
  - !ruby/object:Gem::Dependency
17
17
  type: :runtime
@@ -130,6 +130,7 @@ files:
130
130
  - bin/rescue
131
131
  - examples/example.rb
132
132
  - examples/example2.rb
133
+ - examples/example_spec.rb
133
134
  - examples/loop.rb
134
135
  - examples/random-exit.rb
135
136
  - examples/rescue.rb
@@ -161,6 +162,7 @@ files:
161
162
  - spec/fixtures/uri.rb
162
163
  - spec/peek_spec.rb
163
164
  - spec/pry_rescue_spec.rb
165
+ - spec/spec_helper.rb
164
166
  homepage: https://github.com/ConradIrwin/pry-rescue
165
167
  licenses: []
166
168
  post_install_message: