pry-rescue 0.18.1 → 1.0.0

data/README.md

@@ -1,18 +1,59 @@
+**pry-rescue** - super-fast debugging for ruby. (See [Pry to the
+rescue!](http://cirw.in/blog/pry-to-the-rescue))
 
-**pry-rescue** super-fast, painless, debugging for the (ruby) masses. (See [Pry to the rescue!](http://cirw.in/blog/pry-to-the-rescue))
+Introduction
+============
+
+pry-rescue is an implementation of "break on unhandled exception" for Ruby. Whenever an
+exception is raised, but not rescued, pry-rescue will automatically open pry for you:
+
+```ruby
+$ rescue examples/example2.rb
+From: /home/conrad/0/ruby/pry-rescue/examples/example2.rb @ line 19 Object#beta:
+
+    17: def beta
+    18:   y = 30
+ => 19:   gamma(1, 2)
+    20: end
+
+ArgumentError: wrong number of arguments (2 for 1)
+from /home/conrad/0/ruby/pry-rescue/examples/example2.rb:22:in `gamma`
+[1] pry(main)>
+```
+
+Installation
+============
+
+You can install `pry-rescue` with rubygems as normal, and I strongly recommend you also
+install `pry-stack_explorer`. See [Known bugs](#known-bugs) for places that won't work.
+
+```
+gem install pry-rescue pry-stack_explorer
+```
+
+If you're using Bundler, you can add it to your Gemfile in the development group:
+
+```ruby
+group :development do
+  gem 'pry-rescue'
+  gem 'pry-stack_explorer'
+end
+```
 
 Usage
 =====
 
-First `gem install pry-rescue pry-stack_explorer`. Then run your program with `rescue`
-instead of `ruby`:
+For simple ruby scripts, just run them with the `rescue` executable instead of the `ruby`
+executable.
 
 ```
 rescue <script.rb> [arguments..]
 ```
 
-If you're using Rails, you should add `pry-rescue` to the development section of your
-Gemspec and then run rails server using rescue:
+Rails
+-----
+
+For rails, use `rescue rails` in place of `rails`, for example:
 
 ```
 rescue rails server
@@ -24,75 +65,83 @@ If you're using `bundle exec` the rescue should go after the exec:
 bundle exec rescue rails server
 ```
 
-If you're using Rack, you should use the middleware instead (though be careful to only
-include it in development!)
-```
-use PryRescue::Rack
-```
+Then whenever an unhandled exception happens inside rails, a pry console will open on
+stdout. This is the same terminal that you see the rails logs on, so if you're
+using something like [pow](https://pow.cx) then you will run into difficulties.
 
-If you're using rspec, you should add `pry-rescue` to your Gemfile and then you can
-enable rescuing on failed tests by running:
+You might also be interested in
+[better_errors](https://github.com/charliesome/better_errors) which opens consoles in your
+browser on unhandled exceptions, and [pry-rails](https://github.com/rweng/pry-rails) which
+adds some rails specific helpers to pry, and replaces `rails console` by pry.
 
-```
-rescue rspec
-```
+Rspec
+-----
 
-If you want more fine-grained control over which parts of your code are rescued, you can
-also use the block form:
+If you're using [RSpec](https://rspec.org) or
+[respec](https://github.com/oggy/respec), you can open a pry session on
+every test failure using `rescue rspec` or `rescue respec`:
 
 ```ruby
-require 'pry-rescue'
-
-def test
-  raise "foo"
-rescue => e
-  raise "bar"
-end
-
-Pry.rescue do
-  test
-end
+$ rescue rspec
+From: /home/conrad/0/ruby/pry-rescue/examples/example_spec.rb @ line 9 :
+
+     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
+
+RSpec::Expectations::ExpectationNotMetError: expected: 0.3
+     got: 0.30000000000000004 (using ==)
+[1] pry(main)>
 ```
-This will land you in a pry-session:
 
-```
-From: examples/example.rb @ line 4 Object#test:
+Unfortunately using `edit -c` to edit `_spec.rb` files does not yet reload the
+code in a way that the `try-again` command can understand. You can still use
+`try-again` if you edit code that is not in spec files.
 
-    4: def test
-    5:   raise "foo"
-    6: rescue => e
- => 7:   raise "bar"
-    8: end
+Minitest
+--------
 
-RuntimeError: bar
-from examples/example.rb:7:in `rescue in test'
-[1] pry(main)>
+Add the following to your `test_helper.rb` or to the top of your test file.
+
+```ruby
+require 'minitest/autorun'
+require 'pry-rescue/minitest'
 ```
 
-Finally. If you're doing your own exception handling, you can ask pry to open on an exception that you've caught.
-For this to work you must be inside a Pry::rescue{ } block.
+Then, when you have a failure, you can use `edit`, `edit -c`, and `edit-method`, then
+`try-again` to re-run the tests.
 
-```ruby
-def test
-  raise "foo"
-rescue => e
-  Pry::rescued(e)
-end
+Rack
+----
 
-Pry::rescue{ test }
+If you're using Rack, you should use the middleware instead (though be careful to only
+include it in development!):
+
+```
+use PryRescue::Rack if ENV["RACK_ENV"] == 'development'
 ```
 
-cd-raise
-========
+Pry commands
+============
+
+`pry-rescue` adds two commands to pry. `cd-cause` and `try-again`. In combination with
+`edit --method` these can let you fix the problem with your code and verify that the fix
+worked without restarting your program.
+
+cd-cause
+--------
 
-If you've run some code in Pry, and an exception was raised, you can use the `cd-raise`
+If you've run some code in Pry, and an exception was raised, you can use the `cd-cause`
 command:
 
-```
+```ruby
 [1] pry(main)> foo
 RuntimeError: two
-from a.rb:4:in `rescue in foo'
-[2] pry(main)> cd-raise
+from a.rb:4:in `rescue in foo`
+[2] pry(main)> cd-cause
 From: a.rb @ line 4 Object#foo:
 
     1: def foo
@@ -101,19 +150,14 @@ From: a.rb @ line 4 Object#foo:
  => 4:   raise "two"
     5: end
 
-[1] pry(main)>
+[3] pry(main)>
 ```
 
-To get back from `cd-raise` you can either type `<ctrl+d>` or `cd ..`.
+If that exception was in turn caused by a previous exception you can use
+`cd-cause` again to move to the original problem:
 
-cd-cause
-========
-
-If you need to find the reason that the exception happened, you can use the `cd-cause`
-command:
-
-```
-[1] pry(main)> cd-cause
+```ruby
+[3] pry(main)> cd-cause
 From: examples/example.rb @ line 4 Object#test:
 
     4: def test
@@ -123,22 +167,23 @@ From: examples/example.rb @ line 4 Object#test:
     8: end
 
 RuntimeError: foo
-from examples/example.rb:5:in `test'
-[1] pry(main)>
+from examples/example.rb:5:in `test`
+[4] pry(main)>
 ```
 
 To get back from `cd-cause` you can either type `<ctrl+d>` or `cd ..`.
 
 try-again
-=========
+---------
 
-Once you've used Pry's `edit` or `edit-method` commands to fix your code, you can issue a
-`try-again` command to re-run your code. (Either from the start in the case of using the
-`rescue` script, or from the block if you're using that API).
+Once you've used Pry's `edit` or command to fix your code, you can issue a `try-again`
+command to re-run your code. For rails and rack, this re-runs the request, for minitest
+and rspec, it re-runs the current test, for more advanced users this re-runs the
+`Pry::rescue{ }` block.
 
-```
-[1] pry(main)> edit-method
-[2] pry(main)> whereami
+```ruby
+[4] pry(main)> edit --method
+[5] pry(main)> whereami
 From: examples/example.rb @ line 4 Object#test:
 
     4: def test
@@ -146,45 +191,64 @@ From: examples/example.rb @ line 4 Object#test:
     6: rescue => e
     7:   raise "bar"
     8: end
-[3] pry(main)> try-again
+[6] pry(main)> try-again
 foo
 ```
 
-Testing
-=======
+Advanced usage
+==============
 
-Pry-rescue comes with beta support for minitest and rspec: test failures will
-drop you into pry at that location.  Please feel free to try these out, and
-leave bug reports if something is not working.
+Block form
+----------
 
-Note that for either of these, you will find `exit!` very handy: there is a pry
-`exit` command that will merely drop you into the next failure.
+If you want more fine-grained control over which parts of your code are rescued, you can
+also use the block form:
 
-### minitest
+```ruby
+require 'pry-rescue'
 
-Add the following to your `test_helper.rb` or to the top of your test file.
+def test
+  raise "foo"
+rescue => e
+  raise "bar"
+end
 
-```ruby
-require 'minitest/autorun'
-require 'pry-rescue/minitest'
+Pry.rescue do
+  test
+end
 ```
+This will land you in a pry-session:
 
-Then, when you have a failure, you can use `edit`, `edit -c`, and `edit-method`, then
-`try-again` to re-run the tests, or run it by name (`test_foo`).
-
-### rspec
+```
+From: examples/example.rb @ line 4 Object#test:
 
-Add the following to your `spec_helper.rb` or to the top of your test file.
+    4: def test
+    5:   raise "foo"
+    6: rescue => e
+ => 7:   raise "bar"
+    8: end
 
-```ruby
-require 'pry-rescue/rspec'
+RuntimeError: bar
+from examples/example.rb:7:in `rescue in test`
+[1] pry(main)>
 ```
 
-Note that, unlike minitest, rspec creates odd structures instead of classes, so
-it is somewhat resistant to live-coding practices. In particular,  `edit -c` to
-edit the test then `try-again` doesn't work (so you'll have to `exit!`).
+Rescuing an exception
+---------------------
 
+Finally. If you're doing your own exception handling, you can ask pry to open on an exception that you've caught.
+For this to work you must be inside a Pry::rescue{ } block.
+
+```ruby
+def test
+  raise "foo"
+rescue => e
+  Pry::rescued(e)
+end
 
+Pry::rescue{ test }
+
+```
 Peeking
 =======
 
@@ -195,7 +259,7 @@ suprisingly long time to run.
 In this case it's useful to be able to open a pry console when you notice that your
 program is not going anywhere. To do this, send your process a `SIGQUIT` using `<ctrl+\>`.
 
-```
+```ruby
 cirwin@localhost:/tmp/pry $ ruby examples/loop.rb
 ^\
 Preparing to peek via pry!
@@ -212,9 +276,10 @@ pry (main)>
 ```
 
 Advanced peeking
-================
+----------------
 
-You can configure which signal pry-rescue listens for by default by exporting the PRY_PEEK
+You can configure which signal pry-rescue listens for by default by exporting the
+`PRY_PEEK`
 environment variable that suits your use-case best:
 
 ```
@@ -254,14 +319,6 @@ you trigger the signal.
 export RUBYOPT=-r/home/cirwin/src/pry-rescue/lib/pry-rescue/peek/usr2
 ```
 
-pry-stack explorer
-==================
-
-If you're running rubinius, or ruby-1.9, then you can use `pry-rescue` alongside
-`pry-stack\_explorer`. This gives you the ability to move `up` or `down` the stack so that
-you can get a better idea of why your function ended up in a bad state. Run
-[example2.rb](https://github.com/ConradIrwin/pry-rescue/blob/master/examples/example2.rb) to get a feel for what this is like.
-
 Known bugs
 ==========
 

data/bin/rescue

@@ -27,13 +27,10 @@ when '--'
 when /\A-/
   puts USAGE
   exit
-end
-
-case ARGV[0]
 when 'rails'
-  ENV['PRY_RESCUE'] = 'rails'
+  ENV['PRY_RESCUE_RAILS'] = 'true'
   exec(*ARGV)
-when 'rspec'
+when /^re?spec|rake$/
   ENV['SPEC_OPTS'] = "#{ENV['SPEC_OPTS']} -r pry-rescue/rspec"
   exec(*ARGV)
 end

data/examples/example_spec.rb

@@ -0,0 +1,11 @@
+require 'rspec'
+require 'rspec/autorun'
+
+$:.unshift File.expand_path '../../lib', __FILE__
+require 'pry-rescue'
+
+describe "Float" do
+  it "should be able to add" do
+    (0.1 + 0.2).should == 0.3
+  end
+end

data/lib/pry-rescue/commands.rb

@@ -1,75 +1,59 @@
 Pry::Commands.create_command "cd-cause", "Move to the exception that caused this exception to happen"  do
 
   banner <<-BANNER
-    Usage: cd-cause
+    Usage: cd-cause [_ex_]
 
-    Starts a new pry session at the previously raised exception.
+    Starts a new Pry session at the previously raised exception.
 
-    This is useful if you've caught one exception, and raised another,
-    if you need to find out why the original was raised.
+    If you have many layers of exceptions that are rescued and then re-raised,
+    you can repeat cd-cause as many times as you need.
 
-    @example
-      5.    def foo
-      6.      raise "one"
-      7.    rescue
-      8. =>   raise "two"
-      9.    end
-
-      pry> cd-cause
-
-      5.    def foo
-      6. =>   raise "one"
-      7.    rescue
-      8.      raise "two"
-      9.    end
-
-    Once you have finished with the internal exception type <ctrl+d> or cd .. to
-    return to where you were.
-
-    If you have many layers of exceptions that are rescued and then re-raised, you
-    can repeat cd-cause as many times as you need.
-  BANNER
-
-  def process
-    raised = target.eval("_raised_.dup rescue nil")
-    raise Pry::CommandError, "cd-cause only works in a pry session created by Pry::rescue{}" unless raised
-    raised.pop
-
-    if raised.any?
-      PryRescue.enter_exception_context(raised)
-    else
-      raise Pry::CommandError, "No previous exception detected"
-    end
-  end
-end
-
-Pry::Commands.create_command "cd-raise", "Move to the point at which an exception was raised" do
-  banner <<-BANNER
-    Usage: cd-raise [_ex_]
-
-    Starts a new pry session at the point that the given exception was raised.
-
-    If no exception is given, defaults to _ex_, the most recent exception that
-    was raised by code you ran from within pry.
+    The cd-cause command is useful if:
+      - You've just caused an exception within Pry, and you want to see why
+      - When an intermediate exception handler
+        - Intentionally re-raises an exception
+        - Has a bug that causes an inadvertent exception
 
     @example
-
       [2] pry(main)> foo
       RuntimeError: two
       from /home/conrad/0/ruby/pry-rescue/a.rb:4:in `rescue in foo'
-      [3] pry(main)> cd-raise
+      [3] pry(main)> cd-cause
 
           1: def foo
           2:   raise "one"
           3: rescue => e
        => 4:   raise "two"
           5: end
+
+      [4] pry(main)> cd-cause
+
+          1: def foo
+       => 2:   raise "one"
+          3: rescue => e
+          4:   raise "two"
+          5: end
+
+    Once you have finished inspecting the exception, type <ctrl+d> or cd .. to
+    return to where you were.
   BANNER
 
   def process
-    ex = target.eval(args.first || "_ex_")
-    raise Pry::CommandError, "No most recent exception" unless ex
-    Pry.rescued(ex)
+    return Pry.rescued target.eval(args.first) if args.any?
+
+    # TODO: better understand why !defined?(_ex_)
+    ex = target.eval("defined?(_ex_) && _ex_")
+    raised = target.eval("_raised_.dup rescue nil")
+
+    ex_was_raised = raised && raised.last.first == ex
+    if ex && !ex_was_raised
+      Pry.rescued(ex)
+    elsif ex_was_raised && raised.size > 1
+      raised.pop
+      PryRescue.enter_exception_context(raised)
+    else
+      raise Pry::CommandError, "No previous exception detected"
+    end
   end
 end
 

data/pry-rescue.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'pry-rescue'
-  s.version       = '0.18.1'
+  s.version       = '1.0.0'
   s.summary       = 'Open a pry session on any unhandled exceptions'
   s.description   = 'Allows you to wrap code in Pry::rescue{ } to open a pry session at any unhandled exceptions'
   s.homepage      = 'https://github.com/ConradIrwin/pry-rescue'

data/spec/commands_spec.rb

@@ -1,3 +1,5 @@
+require './spec/spec_helper'
+
 describe "pry-rescue commands" do
   describe "try-again" do
     it "should throw try_again" do
@@ -17,7 +19,7 @@ describe "pry-rescue commands" do
     end
   end
 
-  describe "cd-raise" do
+  describe "cd-cause" do
     it "should enter the context of an explicit exception" do
       begin
         b1 = binding
@@ -30,7 +32,7 @@ describe "pry-rescue commands" do
         raised.should == e1
       }
 
-      Pry.new.process_command 'cd-raise e1', '', binding
+      Pry.new.process_command 'cd-cause e1', '', binding
     end
 
     it "should enter the context of _ex_ if no exception is given" do
@@ -45,7 +47,7 @@ describe "pry-rescue commands" do
         raised.should == _ex_
       }
 
-      Pry.new.process_command 'cd-raise', '', binding
+      Pry.new.process_command 'cd-cause', '', binding
     end
   end
 
@@ -57,10 +59,12 @@ describe "pry-rescue commands" do
           raise "original"
         rescue => e1
           b2 = binding
-          raise
+          raise # similar to dubious re-raises you'll find in the wild
         end
       rescue => e2
+        # Hacks due to us not really entering a pry session here
         _raised_ = [[e1, [b1]], [e2, [b2]]]
+        _ex_ = e2
       end
 
       PryRescue.should_receive(:enter_exception_context).once.with{ |raised|
@@ -75,7 +79,9 @@ describe "pry-rescue commands" do
         b1 = binding
         raise "original"
       rescue => e1
+        # Hacks due to us not really entering a pry session here
         _raised_ = [[e1, [b1]]]
+        _ex_ = e1
       end
 
       lambda{
@@ -86,7 +92,7 @@ describe "pry-rescue commands" do
     it "should raise a CommandError if not in Pry::rescue" do
       lambda{
         Pry.new.process_command 'cd-cause', '', binding
-      }.should raise_error Pry::CommandError, /Pry::rescue/
+      }.should raise_error Pry::CommandError, /No previous exception/
     end
   end
 end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'rspec'
+require 'rspec/autorun'
+
+require 'pry/test/helper'
+
+require './lib/pry-rescue'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pry-rescue
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-14 00:00:00.000000000 Z
+date: 2013-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   type: :runtime
@@ -130,6 +130,7 @@ files:
 - bin/rescue
 - examples/example.rb
 - examples/example2.rb
+- examples/example_spec.rb
 - examples/loop.rb
 - examples/random-exit.rb
 - examples/rescue.rb
@@ -161,6 +162,7 @@ files:
 - spec/fixtures/uri.rb
 - spec/peek_spec.rb
 - spec/pry_rescue_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/ConradIrwin/pry-rescue
 licenses: []
 post_install_message: