nesty 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 88bbd71a1ad275e4b375f83e911a65c82c415bca
+  data.tar.gz: 27de613cc1345753cb0373e6f680c5a663b311ab
+SHA512:
+  metadata.gz: be263019851c80453bc3b2a6432165835e07d78f1ad03c251b99e6b8448509d6276db1d9290fa8dd371bcc4208b94ecebdd54ca91f3c3939b72e7f07ed5a23fa
+  data.tar.gz: 8b290ce0bd38b5e1d32232373f204708c1f4528a389090234bbe970810179f0eec406691db98ac0e400ef38e4fc20dc4c060693f19af2dd5cb62822fea9f6b4d

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tags

data/.irbrc

@@ -0,0 +1,3 @@
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), 'lib'))
+
+require './lib/nesty'

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-19mode # JRuby in 1.9 mode
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nesty.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Alan Skorkin
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,112 @@
+# Nesty
+
+Now, when you rescue an error and then re-raise your own, you don't have to lose track of what actually occured, you can keep/nest the old error in your own and the stacktrace will reflect the cause of the original error.
+
+## Why Use It?
+
+When you use libraries that raise their own errors, it's not a good idea to allow these errors to bubble up through your app/library. Clients of your app/library should only have to deal with errors that belong to your app and not ones that come from libraries that your app is using. To achieve this without nested exception support, you would need to rescue the error that come from external libraries and then raise your own errors in their place. Of course, when you do this you lose the information from the original error. With nested exception support you no longer have to lose this information which is very handy.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nesty'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nesty
+
+## Usage
+
+Super simple, create your own error class just like normal, but include a module in it:
+
+```ruby
+class HappyError < StandardError
+  include Nesty::NestedError
+end
+```
+
+Alternatively rather than inheriting from `StandardError` do this:
+
+```ruby
+class HappyError < Nesty::NestedStandardError
+end
+```
+
+Instances of `HappyError`, will now support nesting another error inside.
+
+Here is how we can use this.
+
+```ruby
+begin
+  raise StandardError.new
+rescue => e
+  raise HappyError.new("hello", e)
+end
+```
+
+That was the explicit way, you raise another error and pass in the error you rescued, but you can also do this:
+
+```ruby
+begin
+  raise StandardError.new
+rescue => e
+  raise HappyError.new
+end
+```
+
+This is the implicit way, the `HappyError` instance will still nest the `StandardError` that was rescued.
+
+You can of course go deeper and keep rescuing and raising your own errors. As long as you raise with instances that support nesting (e.g. ones that include `Nesty::NestedError` or inherit from `Nesty::NestedStandardError`), the stack trace will include all the nested exception messages.
+
+### What The Stacktrace Will Look Like?
+
+It's probably a good idea to keep the stacktrace as close to a normal one as possible and in this case it actually will look very similar to a normal stacktrace. The only difference is that the error messages for all the nested errors will be included in the stacktrace (as opposed to just the message for the outer error).
+
+Let's illustrate with an example.
+
+We have 3 errors, A, B and C all nested in each other (A is nested in B and B is nested in C). They have the following messages and backtrace arrays:
+
+```
+A - message: 'a', backtrace: ['2', '1']
+B - message: 'b', backtrace: ['4', '3', '2', '1']
+C - message: 'c', backtrace: ['6', '5', '4', '3', '2', '1']
+```
+
+If C was not nested and we allowed it to bubble up so that it gets dumped to standard output, we would see something like the following:
+
+```
+c
+6
+5
+4
+3
+2
+1
+```
+
+But, with out nested errors we would see the following:
+
+```
+c
+6
+5
+4: b
+3
+2: a
+1
+```
+
+Since a stacktrace for a nested error is always a subset of the stacktrace of the enclosing error, all we need do is add the messages for each of our nested errors in the appropriate place in the stacktrace. Simple, but handy.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/examples/complex.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "nesty"))
+
+class MyError < StandardError
+  include Nesty::NestedError
+end
+
+#just run this to see what get spit out to the console
+
+begin
+  1/0
+rescue => e
+  begin
+    raise MyError.new("Number errors will be caught", e)
+  rescue => e
+    begin
+      raise MyError.new("Don't need to let MyError bubble up")
+    rescue => e
+      raise MyError.new("Last one for sure!")
+    end
+  end
+end

data/examples/no_nested.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "nesty"))
+
+class MyError < StandardError
+  include Nesty::NestedError
+end
+
+#just run this to see what get spit out to the console
+
+raise MyError.new("Gotta catch 'em all!")

data/examples/simple.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "nesty"))
+
+class MyError < StandardError
+  include Nesty::NestedError
+end
+
+#just run this to see what get spit out to the console
+
+begin
+  1/0
+rescue => e
+  raise MyError.new("Gotta catch 'em all!")
+end

data/lib/nesty.rb

@@ -0,0 +1,4 @@
+require "nesty/version"
+require "nesty/nested_error"
+require "nesty/nested_standard_error"
+

data/lib/nesty/nested_error.rb

@@ -0,0 +1,26 @@
+module Nesty
+  module NestedError
+    attr_reader :nested, :raw_backtrace
+
+    def initialize(msg = nil, nested = $!)
+      super(msg)
+      @nested = nested
+    end
+
+    def set_backtrace(backtrace)
+      @raw_backtrace = backtrace
+      if nested
+        backtrace = backtrace - nested_raw_backtrace
+        backtrace += ["#{nested.backtrace.first}: #{nested.message}"]
+        backtrace += nested.backtrace[1..-1] || []
+      end
+      super(backtrace)
+    end
+
+    private
+
+    def nested_raw_backtrace
+      nested.respond_to?(:raw_backtrace) ? nested.raw_backtrace : nested.backtrace
+    end
+  end
+end

data/lib/nesty/nested_standard_error.rb

@@ -0,0 +1,5 @@
+module Nesty
+  class NestedStandardError
+    include NestedError
+  end
+end

data/lib/nesty/version.rb

@@ -0,0 +1,3 @@
+module Nesty
+  VERSION = "1.0.0"
+end

data/nesty.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'nesty/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "nesty"
+  spec.version       = Nesty::VERSION
+  spec.authors       = ["Alan Skorkin"]
+  spec.email         = ["alan@skorks.com"]
+  spec.summary       = %q{Nested exception support for Ruby}
+  spec.description   = %q{Nested exception support for Ruby}
+  spec.homepage      = "https://github.com/skorks/nesty"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'travis-lint'
+end

data/spec/lib/nesty/nested_error_spec.rb

@@ -0,0 +1,122 @@
+describe Nesty::NestedError do
+  class TestError < StandardError
+    include Nesty::NestedError
+  end
+
+  # test when no nested error and message is nil
+  # test when no nested error and message is not nil
+  # test when one level of nesting and nested error is explicitly set
+  # test when one level of nesting and nested error is implicit
+  # test when two levels of nesting and nested error are explicitly set
+  # test when two levels of nesting and all errors are implicit
+
+  let(:outer_message) {'hello'}
+  let(:outer_backtrace) {['x', 'a', 'b']}
+  let(:error) do
+    begin
+      raise TestError.new(outer_message, nested)
+    rescue => e
+      e.set_backtrace(outer_backtrace)
+      e
+    end
+  end
+
+  describe "nested error" do
+    subject { error }
+
+    context "when there is no nested error" do
+      let(:nested) {nil}
+      let(:outer_backtrace) {['a', 'b']}
+
+      context "when message is nil" do
+        let(:outer_message) {nil}
+        it {subject.message.should == TestError.name}
+        it {subject.backtrace.size.should == 2}
+        it {subject.backtrace[0].should == 'a'}
+      end
+
+      context "when message is not nil" do
+        let(:outer_message) {'hello'}
+        it {subject.message.should == 'hello'}
+        it {subject.backtrace.size.should == 2}
+        it {subject.backtrace[1].should == 'b'}
+      end
+    end
+
+    context "when there is one level of nested error" do
+      let(:nested_message) {'foo'}
+      let(:nested_backtrace) {['a', 'b']}
+      let(:nested) do
+        begin
+          raise StandardError.new(nested_message)
+        rescue => e
+          e.set_backtrace(nested_backtrace)
+          e
+        end
+      end
+
+      context "and nested error is explicitly set" do
+        it {subject.message.should == 'hello'}
+        it {subject.backtrace.size.should == 3}
+        it {subject.backtrace[0].should == 'x'}
+        it {subject.backtrace[1].should == "a: #{nested_message}"}
+        it {subject.backtrace[2].should == 'b'}
+      end
+
+      context "and nested error is implicitly set" do
+        let(:error) do
+          begin
+            begin
+              raise nested
+            rescue => e
+              error = TestError.new(outer_message)
+              error.set_backtrace(outer_backtrace)
+              raise error
+            end
+          rescue => ae
+            ae
+          end
+        end
+
+        it {subject.message.should == 'hello'}
+        it {subject.backtrace.size.should == 3}
+        it {subject.backtrace[0].should == 'x'}
+        it {subject.backtrace[1].should == "a: #{nested_message}"}
+        it {subject.backtrace[2].should == 'b'}
+      end
+    end
+
+    context "when there are multiple levels of nested error" do
+      let(:outer_message) {'hello'}
+      let(:outer_backtrace) {['w', 'x', 'y', 'z', 'a', 'b']}
+      let(:nested_message) {'foo'}
+      let(:nested_backtrace) {['y', 'z', 'a', 'b']}
+      let(:nested_nested_message) {'bar'}
+      let(:nested_nested_backtrace) {['a', 'b']}
+      let(:nested) do
+        begin
+          raise TestError.new(nested_message, nested_nested)
+        rescue => e
+          e.set_backtrace(nested_backtrace)
+          e
+        end
+      end
+      let(:nested_nested) do
+        begin
+          raise StandardError.new(nested_nested_message)
+        rescue => e
+          e.set_backtrace(nested_nested_backtrace)
+          e
+        end
+      end
+      it {subject.message.should == 'hello'}
+      it {subject.backtrace.size.should == 6}
+      it {subject.backtrace[0].should == 'w'}
+      it {subject.backtrace[1].should == 'x'}
+      it {subject.backtrace[2].should == "y: #{nested_message}"}
+      it {subject.backtrace[3].should == 'z'}
+      it {subject.backtrace[4].should == "a: #{nested_nested_message}"}
+      it {subject.backtrace[5].should == 'b'}
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+require 'nesty'
+
+Dir[File.join(File.dirname(__FILE__), 'support', '**', "*.rb").to_s].each {|file| require file }
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: nesty
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alan Skorkin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: travis-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Nested exception support for Ruby
+email:
+- alan@skorks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .irbrc
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/complex.rb
+- examples/no_nested.rb
+- examples/simple.rb
+- lib/nesty.rb
+- lib/nesty/nested_error.rb
+- lib/nesty/nested_standard_error.rb
+- lib/nesty/version.rb
+- nesty.gemspec
+- spec/lib/nesty/nested_error_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/skorks/nesty
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Nested exception support for Ruby
+test_files:
+- spec/lib/nesty/nested_error_spec.rb
+- spec/spec_helper.rb