pry-rescue 0.18.1 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
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: