pry-rescue 0.9.1 → 0.10.pre.1

data/README.md

@@ -119,6 +119,104 @@ From: examples/example.rb @ line 4 Object#test:
 foo
 ```
 
+<a name="peeking"/>
+Peeking
+=======
+
+Someones bugs in your program don't cause exceptions. Instead your program just gets
+stuck. Examples include infinite loops, slow network calls, or badly backtracking
+parsers.
+
+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 enable this feature you need to run:
+
+```
+rescue --peek <script.rb>
+```
+
+Then hit `<ctrl+c>` at any time to stop your program and have a peek at what it's actually
+doing. Hitting `<ctrl-c>` a second time will quit your program, if that's what you were
+trying to do.
+
+Automatic peeking
+=================
+
+Remembering to run your program with `rescue --peek` manually is a bit frustrating (as you
+don't know you need to peek, until you need to peek) and so pry-rescue also allows you to
+peek into any program at any time by sending it a `SIGUSR2` signal.
+
+The easiest way to do this is to hit `<ctrl-z>` to interrupt your program, then type
+`kill -SIGUSR2 %1 && fg` into bash. For example:
+
+<!-- TODO syntax highlighting! -->
+```
+cirwin@localhost:/tmp/pry $ ruby examples/loop.rb
+^Z
+cirwin@localhost:/tmp/pry $ kill -SIGUSR2 %1 && fg
+[1]  + continued  ./examples/loop.rb
+Preparing to peek via pry!
+Frame number: 0/4
+
+From: ./examples/loop.rb @ line 10 Object#r
+    10: def r
+    11:   some_var = 13
+    12:   loop do
+ => 13:     x = File.readlines('lib/pry-rescue.rb')
+    14:   end
+    15: end
+pry (main)>
+```
+
+If you find that that's a bit hard to remember (I know I do), then you can make it easier
+by adding the following alias to your `~/.bashrc` or similar:
+
+```
+alias peek='kill -SIGUSR2 %1 && fg'
+```
+
+Then you can just type `peek` instead of `kill -SIGUSR2 %1 && fg`
+
+Advanced peeking
+================
+
+You can configure which signal pry-rescue listens for by default by exporting the PRY_PEEK
+environment variable that suits your use-case best:
+
+```
+export PRY_PEEK=""    # don't autopeek at all
+export PRY_PEEK=INT   # peek on SIGINT (<ctrl+c>)
+export PRY_PEEK=USR1  # peek on SIGUSR1
+export PRY_PEEK=USR2  # peek on SIGUSR2
+export PRY_PEEK=EXIT  # peek on program exit
+```
+
+If it's only important for one program, then you can also set the environment variable in
+ruby before requiring pry-rescue
+
+```ruby
+ENV['PRY_PEEK'] = '' # disable SIGUSR2 handler
+require "pry-rescue"
+```
+
+Finally, you can enable peeking into programs that do not include pry-rescue by
+configuring ruby to always load one (or several) of these files:
+
+```
+export RUBYOPT=-rpry-rescue/peek/int   # peek on SIGINT (<ctrl-c>)
+export RUBYOPT=-rpry-rescue/peek/usr1  # peek on SIGUSR1
+export RUBYOPT=-rpry-rescue/peek/usr2  # peek on SIGUSR2
+export RUBYOPT=-rpry-rescue/peek/exit  # peek on program exit
+```
+
+These last examples relies on having pry-rescue in the load path (i.e. at least in the
+gemset, or Gemfile of the program). If that is not true, you can use absolute paths. The
+hook files do not require the whole of pry-rescue, nor is any of pry itself loaded until
+you trigger the signal.
+
+```
+export RUBYOPT=-r/home/cirwin/src/pry-rescue/lib/pry-rescue/peek/usr2
+```
+
 pry-stack explorer
 ==================
 

data/bin/rescue

@@ -4,7 +4,7 @@ USAGE = %{
 rescue (pry-rescue wrapper)
 
 Usage:
-  rescue <script.rb> [arguments...]
+  rescue [--peek] <script.rb> [arguments...]
 
 What it does:
   Runs <script.rb>, and if an uncaught exception is raised,
@@ -13,9 +13,25 @@ What it does:
 
   You can then poke around to figure out why your code broke!
 
-  (Not yet available: fixing the problem and continuing your program.)
+  If --peek is specified, then you can hit <Ctrl+C> to interrupt
+  your program and open a pry session at any time you need.
 
+  See the README (http://bitly.com/pry-rescue) for more.
 }
+case ARGV[0]
+when '-h', '--help'
+  puts USAGE
+  exit
+when /\A--peek\z/
+  ARGV.shift
+  ENV['PRY_PEEK'] = 'INT'
+  require "pry-rescue/peek/int"
+when '--'
+  ARGV.shift
+when /\A-/
+  puts USAGE
+  exit
+end
 
 if ARGV[0] == 'rails'
   ENV['PRY_RESCUE_RAILS'] = 'true'

data/examples/example.rb

@@ -1,3 +1,11 @@
+#!/usr/bin/env ruby
+#
+# cd-cause example
+#
+# Try running with: ./examples/example.rb
+#
+# When pry opens you can `cd-cause` a few times to see which exception
+# triggered all these buggy rescue blocks!
 $:.unshift File.expand_path '../../lib', __FILE__
 require 'pry-rescue'
 

data/examples/example2.rb

@@ -1,3 +1,11 @@
+#!/usr/bin/env ruby
+# pry-stack_explorer example
+#
+# Run with ./examples/example2.rb
+#
+# When pry opens you'll be able to move "up" and "down" the stack and see
+# what's happening at all levels.
+
 $:.unshift File.expand_path '../../lib', __FILE__
 require 'pry-rescue'
 

data/examples/loop.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+require 'pry-rescue'
+
+# Peeking example! Try running this example with:
+#
+# rescue --peek example/loop.rb
+#
+# Then hit <ctrl-c>, and be able to see what's going on.
+
+def r
+  some_var = 13
+  loop do
+    x = File.readlines('lib/pry-rescue.rb')
+  end
+end
+r

data/examples/random-exit.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# Advanced peeking example, showing how to catch the EXIT signal
+#
+# Try running with:
+#
+# RUBYOPT=-rpry-rescue/peek/exit examples/random-exit.rb
+#
+def haywire arg
+  # TODO: Figure out how to pry at the "arg" value
+  if 3 == arg
+    exit 1
+  end
+end
+
+def dangerous
+  choice = rand 55
+  haywire choice
+end
+
+loop do
+  dangerous
+end

data/examples/rescue.rb

@@ -1,5 +1,12 @@
+#!/usr/bin/env ruby
 # Slightly silly example written for http://cirw.in/blog/pry-to-the-rescue
 # (NOTE: the solution in the blog post only works on ruby-1.9)
+#
+# try running this with: rescue ./examples/rescue.rb
+#
+# When pry opens, see if you can use edit-method and try-again to fix the
+# code and test that your code works.
+#
 def find_capitalized(a)
   a.select do |name|
     name.chars.first == name.chars.first.upcase

data/lib/pry-rescue.rb

@@ -5,10 +5,19 @@ require 'pry'
 require File.expand_path('../pry-rescue/core_ext', __FILE__)
 require File.expand_path('../pry-rescue/commands', __FILE__)
 require File.expand_path('../pry-rescue/rack', __FILE__)
+require File.expand_path('../pry-rescue/peek.rb', __FILE__)
 
 if ENV['PRY_RESCUE_RAILS']
   require File.expand_path('../pry-rescue/rails', __FILE__)
 end
+case ENV['PRY_PEEK']
+when nil
+  PryRescue.peek_on_signal('USR2')
+when ''
+  # explicitly disable USR2.
+else
+  PryRescue.peek_on_signal(ENV['PRY_PEEK'])
+end
 
 begin
   require 'pry-stack_explorer'
@@ -94,10 +103,24 @@ class PryRescue
     # @return [Boolean]
     def user_path?(file)
       !file.start_with?(RbConfig::CONFIG['libdir']) &&
-      !Gem::Specification.any?{ |gem| file.start_with?(gem.full_gem_path) } &&
+      !gem_path?(file) &&
       !(file == '<internal:prelude>')
     end
 
+    # Is this path included in a gem?
+    #
+    # @param [String] file  the absolute path
+    # @return [Boolean]
+    def gem_path?(file)
+      # rubygems 1.8
+      if Gem::Specification.respond_to?(:any?)
+        Gem::Specification.any?{ |gem| file.start_with?(gem.full_gem_path) }
+      # rubygems 1.6
+      else
+        Gem.all_load_paths.any?{ |path| file.start_with?(path) }
+      end
+    end
+
     # Remove bindings that are part of Interception/Pry.rescue's internal
     # event handling that happens as part of the exception hooking process.
     #

data/lib/pry-rescue/peek.rb

@@ -0,0 +1,18 @@
+class PryRescue
+  def self.peek_on_signal signal
+    trap signal, &method(:peek!)
+  end
+
+  # Called when rescue --peek is used and the user hits <Ctrl+C>
+  # or sends whichever signal is configured.
+  def self.peek!(*)
+    puts 'Preparing to peek via pry!' unless ENV['NO_PEEK_STARTUP_MESSAGE']
+    require 'pry'
+    unless binding.respond_to?(:of_caller)
+      raise "pry-stack_explorer is not installed"
+    end
+    throw :raise_up, Interrupt if Pry === binding.of_caller(1).eval('self')
+    binding.of_caller(1).pry
+    # TODO pry :call_stack => binding.of_callers, :initial_frame => 1
+  end
+end

data/lib/pry-rescue/peek/exit.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__)
+PryRescue.peek_on_signal 'EXIT'

data/lib/pry-rescue/peek/int.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__)
+PryRescue.peek_on_signal 'INT'

data/lib/pry-rescue/peek/usr1.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__)
+PryRescue.peek_on_signal 'USR1'

data/lib/pry-rescue/peek/usr2.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__)
+PryRescue.peek_on_signal 'USR2'

data/pry-rescue.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'pry-rescue'
-  s.version       = '0.9.1'
+  s.version       = '0.10.pre.1'
   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/peek_spec.rb

@@ -0,0 +1,29 @@
+ENV['NO_PEEK_STARTUP_MESSAGE'] = 'true'
+
+describe "PryRescue.peek!" do
+  it "should open a pry in the binding of caller" do
+    Pry.config.input = StringIO.new("foo = 6\nexit\n")
+    Pry.config.output = StringIO.new
+    foo = 5
+
+    lambda do
+      PryRescue.peek!
+    end.should change{ foo }.from(5).to(6)
+  end
+
+  # this will fail, or not?
+  it 'should include the entire call stack' do
+    Pry.config.input = StringIO.new("up\nfoo = 6\nexit\n")
+    Pry.config.output = StringIO.new
+
+    def example_method
+      PryRescue.peek!
+    end
+
+    foo = 5
+
+    lambda do
+      PryRescue.peek!
+    end.should change{ foo }.from(5).to(6)
+  end
+end

data/spec/pry_rescue_spec.rb

@@ -41,7 +41,11 @@ describe "PryRescue.load" do
 
     it "should open above gems" do
       PryRescue.should_receive(:pry).once do |opts|
-        opts[:call_stack].first.eval("__FILE__").should start_with(Gem::Specification.detect{|x| x.name == 'coderay' }.full_gem_path)
+        coderay_path = Gem::Specification.respond_to?(:detect) ?
+                         Gem::Specification.detect{|x| x.name == 'coderay' }.full_gem_path :
+                         Gem.all_load_paths.grep(/coderay/).last
+
+        opts[:call_stack].first.eval("__FILE__").should start_with(coderay_path)
       end
       lambda{
         PryRescue.load("spec/fixtures/coderay.rb")

metadata

@@ -1,97 +1,109 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: pry-rescue
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 9
-  - 1
-  version: 0.9.1
+version: !ruby/object:Gem::Version
+  version: 0.10.pre.1
+  prerelease: 5
 platform: ruby
-authors: 
+authors:
 - Conrad Irwin
 - banisterfiend
 - epitron
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-09-30 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: pry
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: interception
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 3
-        version: "0.3"
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: interception
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.3'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: yard
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: redcarpet
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id005
-description: Allows you to wrap code in Pry::rescue{ } to open a pry session at any unhandled exceptions
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows you to wrap code in Pry::rescue{ } to open a pry session at any
+  unhandled exceptions
+email:
 - conrad.irwin@gmail.com
 - jrmair@gmail.com
 - chris@ill-logic.com
-executables: 
+executables:
 - rescue
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - LICENSE.MIT
@@ -100,11 +112,18 @@ files:
 - bin/rescue
 - examples/example.rb
 - examples/example2.rb
+- examples/loop.rb
+- examples/random-exit.rb
 - examples/rescue.rb
 - lib/pry-rescue.rb
 - lib/pry-rescue/cli.rb
 - lib/pry-rescue/commands.rb
 - lib/pry-rescue/core_ext.rb
+- lib/pry-rescue/peek.rb
+- lib/pry-rescue/peek/exit.rb
+- lib/pry-rescue/peek/int.rb
+- lib/pry-rescue/peek/usr1.rb
+- lib/pry-rescue/peek/usr2.rb
 - lib/pry-rescue/rack.rb
 - lib/pry-rescue/rails.rb
 - lib/pry/rescue.rb
@@ -118,36 +137,31 @@ files:
 - spec/fixtures/simple.rb
 - spec/fixtures/super.rb
 - spec/fixtures/uri.rb
+- spec/peek_spec.rb
 - spec/pry_rescue_spec.rb
-has_rdoc: true
 homepage: https://github.com/ConradIrwin/pry-rescue
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Open a pry session on any unhandled exceptions
 test_files: []
-
+has_rdoc: