nested_exceptions 1.0.0 → 1.0.1

data/README.md

@@ -0,0 +1,75 @@
+# NestedExceptions
+
+This simple library adds support for nested exceptions in Ruby.
+
+## Why?
+
+It can be really painful to debug a situation where a library rescues an
+exception and throws a different one, or when it has a bug in its
+exception handling logic. This gem goes a diving catch and recovers the
+play!
+
+The best way to learn more about this topic is to investigate the great
+source of information at the [Exceptional Ruby](http://exceptionalruby.com/) site.
+
+## How do I use it?
+
+The best way to use it is to simply add the following line of code to
+your project:
+
+  require 'nested_exceptions/global'
+
+That includes the NestedExceptions module in all of Ruby's base
+exception classes (except the Exception root class), magically enabling
+you to debug the trickiest, buggiest libraries.
+
+### I'm not sure I want to include it globally
+
+If you want to try it out without extending Ruby's exception classes,
+you can also do the following:
+
+  require 'nested_exceptions'
+
+  class MyException < StandardError
+    include NestedExceptions
+  end
+
+That will only extend your class and leave the rest of the exception
+classes untouched.
+
+## Does it change anything?
+
+Yes. A bit of extra information is added to your backtraces. In addition
+to the standard backtrace, you'll get a little bit of nesting
+information.
+
+  ruby examples/example.rb original
+
+    examples/example.rb:32:in `rescue in double_bug': oops (RuntimeError)
+      from examples/example.rb:30:in `double_bug'
+      from examples/example.rb:42:in `<main>'
+
+
+  ruby examples/example.rb nested
+
+    examples/example.rb:30:in `rescue in double_bug': oops (RuntimeError)
+      from --- cause: ErrorSpec::InternalError: problem
+      from examples/example.rb:20:in `rescue in problem'
+      from --- cause: RuntimeError: bug
+      from examples/example.rb:10:in `bug'
+      from examples/example.rb:14:in `nested_bug'
+      from examples/example.rb:18:in `problem'
+      from examples/example.rb:24:in `nested_problem'
+      from examples/example.rb:28:in `double_bug'
+      from examples/example.rb:35:in `<main>'
+
+It also adds two methods to the exception:
+
+* #root_cause: allows you to easily get the first exception
+* #cause: get the exception (if any) that may have caused this one
+
+## Gotchas
+
+Do not include the NestedExceptions module in a subclass before adding
+it to its superclass. That will cause the nested exceptions feature to
+deactivate itself to prevent a stack overflow.

data/examples/example.rb

@@ -0,0 +1,66 @@
+require 'pp'
+
+$: << './lib'
+require 'nested_exceptions'
+
+module ErrorSpec
+
+  NestedExceptions.define_standard_exception_classes_in ErrorSpec
+
+  class Example
+    def bug
+      raise 'bug'
+    end
+
+    def nested_bug
+      bug
+    end
+
+    def problem
+      nested_bug
+    rescue
+      raise InternalError, 'problem'
+    end
+
+    def nested_problem
+      problem
+    end
+
+    def double_bug
+      nested_problem
+    rescue
+      raise 'oops'
+    end
+  end
+end
+
+example = ErrorSpec::Example.new
+
+if ARGV.first == 'original'
+
+  puts "Original exception:"
+  example.double_bug
+
+elsif ARGV.first == 'nested'
+
+  require 'nested_exceptions/global'
+  begin
+    example.double_bug
+  rescue StandardError => e
+    if Object.const_defined? :RUBY_ENGINE and (RUBY_ENGINE == 'jruby' or RUBY_ENGINE == 'rbx')
+      puts "Note that JRuby and Rubinius do not display the modified backtrace:"
+      pp e.backtrace
+      puts
+    end
+    puts "Nested exception:"
+    raise
+  end
+
+else
+
+  puts "Usage:"
+  puts
+  puts "ruby #{ $0 } [original|nested]"
+
+end
+

data/lib/nested_exceptions.rb

@@ -6,18 +6,33 @@ module NestedExceptions
   attr_reader :cause
 
   def initialize(message = nil, cause = nil)
-    @cause = cause || $!
-    super(message)
+    # @cause could be defined if this module is included multiple
+    # times in a class heirarchy.
+    @illegal_nesting = defined? @cause
+    @recursing = false
+    if @illegal_nesting
+      warn "WARNING: NestedExceptions is included in the class heirarchy of #{ self.class } more than once."
+      warn "- Ensure if you require 'nested_exceptions/global' or manually add"
+      warn "  NestedExceptions to a built-in Ruby exception class, you must do it at"
+      warn "  the beginning of the program."
+    else
+      @cause = cause || $!
+      super(message)
+    end
   end
 
-  if Object.const_defined? :RUBY_ENGINE and RUBY_ENGINE == 'jruby' or RUBY_ENGINE == 'rbx'
+  if Object.const_defined? :RUBY_ENGINE and (RUBY_ENGINE == 'jruby' or RUBY_ENGINE == 'rbx')
     def backtrace
-      return @processed_backtrace if defined? @processed_backtrace and @processed_backtrace
-      @processed_backtrace = process_backtrace(super)
+      prevent_recursion do
+        return @processed_backtrace if defined? @processed_backtrace and @processed_backtrace
+        @processed_backtrace = process_backtrace(super)
+      end
     end
   else
     def set_backtrace(bt)
-      super process_backtrace(bt)
+      prevent_recursion do
+        super process_backtrace(bt)
+      end
     end
   end
 
@@ -33,18 +48,34 @@ module NestedExceptions
 
   protected
 
+  # This shouldn't be necessary anymore
+  def prevent_recursion
+    if not @recursing and not @illegal_nesting
+      begin
+        @recursing = true
+        yield
+      ensure
+        @recursing = false
+      end
+    end
+  end
+
   def process_backtrace(bt)
-    if cause
-      cause.backtrace.reverse.each do |line|
+    bt ||= []
+    if @cause and not @illegal_nesting
+      cause_backtrace = @cause.backtrace || []
+      cause_backtrace.reverse.each do |line|
         if bt.last == line
           bt.pop
         else
           break
         end
       end
-      bt << "--- cause: #{cause.class.name}: #{cause}"
-      bt.concat cause.backtrace
+      bt << "--- cause: #{@cause.class}: #{@cause}"
+      bt.concat cause_backtrace
     end
     bt
+  rescue Exception => e
+    warn "exception processing backtrace: #{ e.class }: #{ e.message }\n  #{ caller(0).join("\n  ") }"
   end
 end

data/lib/nested_exceptions/define.rb

@@ -5,9 +5,9 @@ module NestedExceptions
     #
     # I actually recommend that you just define these manually, but this may be
     # a handy shortcut in smaller projects.
-    def define_standard_exception_classes_in(target_module)
+    def define_standard_exception_classes_in(target_module, add_module = false)
       definitions = %{
-        class Error < StandardError; include NestedExceptions; end
+        class Error < StandardError; #{ add_module ? 'include NestedExceptions;' : '' } end
           class UserError < Error; end
           class LogicError < Error; end
             class ClientError < LogicError; end

data/lib/nested_exceptions/version.rb

@@ -1,5 +1,5 @@
 module NestedExceptions
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 
   def self.const_missing(name)
     if name == 'GLOBAL' or name == :GLOBAL

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: nested_exceptions
 version: !ruby/object:Gem::Version 
-  hash: 2387456872237229630
+  hash: 3005118107932468525
   prerelease: 
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Darrick Wiebe
@@ -45,7 +45,9 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- README.md
 - Rakefile
+- examples/example.rb
 - lib/nested_exceptions.rb
 - lib/nested_exceptions/define.rb
 - lib/nested_exceptions/global.rb