Browse files

+Readme, license

  • Loading branch information...
1 parent 09d5b2c commit 6c7dcd86164c98880c57a76aad6819e5361cd41a @ConradIrwin committed Aug 11, 2012
Showing with 113 additions and 0 deletions.
  1. +19 −0 LICENSE.MIT
  2. +94 −0 README.md
View
19 LICENSE.MIT
@@ -0,0 +1,19 @@
+Copyright (c) 2012 Conrad Irwin <conrad.irwin@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
View
94 README.md
@@ -0,0 +1,94 @@
+pry-capture allows you to start a Pry session on any unhandled exceptions in your code.
+
+
+Installation
+============
+Either `gem install pry-capture`, or add it to the development section of your Gemfile:
+
+```ruby
+source :rubygems
+group :development do
+ gem 'pry-capture'
+ gem 'pry-stack_explorer' # if you're using MRI 1.9 and you want it to be awesome.
+end
+```
+
+Usage
+=====
+
+In development, wrap your code in `Pry::capture{ }`; then any exceptions that are raised
+but not rescued will open a pry session.
+
+```ruby
+require 'pry-capture'
+
+def test
+ raise "foo"
+rescue => e
+ raise "bar"
+end
+
+Pry.capture do
+ test
+end
+```
+
+This will land you in a pry-session:
+
+```
+From: examples/example.rb @ line 4 Object#test:
+
+ 4: def test
+ 5: raise "foo"
+ 6: rescue => e
+ => 7: raise "bar"
+ 8: end
+
+RuntimeError: bar
+from examples/example.rb:7:in `rescue in test'
+[1] pry(main)>
+```
+
+If you need to find the reason that the exception happened, you can use the `cd-cause`
+command:
+
+```
+[1] pry(main)> cd-cause
+From: examples/example.rb @ line 4 Object#test:
+
+ 4: def test
+ => 5: raise "foo"
+ 6: rescue => e
+ 7: raise "bar"
+ 8: end
+
+RuntimeError: foo
+from examples/example.rb:5:in `test'
+[1] pry(main)>
+```
+
+To get back from `cd-cause` you can either type `<ctrl+d>` or `cd ..`.
+
+pry-stack explorer
+==================
+
+If you're running rubinius, or ruby-1.9, then you can use `pry-capture` 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. See
+example2.rb](https://github.com/ConradIrwin/pry-capture/blob/master/examples/example2.rb) to get a feel for what this is like.
+
+Known bugs
+==========
+
+Occasionally, when using ruby-1.8 or jruby, the value for `self` will be incorrect. You
+will still be able to access local variables, but calling methods will not work as you
+expect.
+
+On rbx we are unable to intercept some exceptions thrown from inside the C++ VM, for
+example the ZeroDivisionError in `1 / 0`.
+
+Meta-fu
+=======
+
+Released under the MIT license, see LICENSE.MIT for details. Contributions and bug-reports
+are welcome.

0 comments on commit 6c7dcd8

Please sign in to comment.