misfit 0.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+= 0.0.1
+  * Initial Release

data/MIT-LICENSE

@@ -0,0 +1,24 @@
+Copyright 2012 Ian White
+
+This plugin was developed by Ian White (http://github.com/ianwhite)
+while working at Distinctive Doors (http://distinctivedoors.co.uk)
+who have kindly agreed to release this under the 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,130 @@
+misfit
+======
+
+Flexible approach to handling exceptions in ruby (for library writers, or consumers).  Inspired by [Avdi Grim](http://avdi.org/)'s excellent book [Exceptional Ruby](http://exceptionalruby.com/).
+
+This was developed by [Ian White](http://github.com/ianwhite) while working at [Distinctive Doors](http://distinctivedoors.co.uk) who have kindly agreed to release this under the MIT-LICENSE.
+
+Misfit allows any module to act like a ruby exception class and gives the ability to decorate any standard ruby exception, optionally adding data.
+
+Misfit also provides a mechanism to change the error handling policy from raising to something else
+
+Why?
+----
+
+For a library writer, this means your library can raise exceptions that will all be caught by 'rescue YourLib::Error',
+but also specific exceptions can be rescued (like rescuing IOErrors, for example) by client code.
+
+    # Your lib
+    module YourLib
+      module Error
+        include Misfit
+      end
+      
+      def self.do_some_work
+        Error.wrap { some_calls_that_might_raise_errors_like_io_error }
+        if no_good then raise Error, "It's no good"
+      end
+    end
+    
+    # Consumer of your lib can do this:
+    begin
+      YourLib.do_some_work
+    rescue YourLib::Error
+      log 'YourLib just errored'
+    end
+    
+    # But they can also rescue specific errors they are interested in, say an IOError
+    begin
+      YourLib.do_some_work
+    rescue IOError
+      # open some tubes and retry
+    rescue YourLib::Error => e
+      # e is some non IOError raised by YourLib
+    end
+
+For a library consumer, you can write a simple wrapper to isolate a library that raises all manner of errors (perhaps undocumented)
+
+    module ErrorByOtherLib
+      include Misfit
+    end
+    
+    def call_out_to_other_lib
+      ErrorByOtherLib.wrap { OtherLib.so_some_stuff }
+    end
+    
+`call_out_to_other_lib` will now raise errors that are `ErrorByOtherLib` as well as retaining their original identity (so an IOError can still be
+rescued, but you can now rescue all errors raised by OtherLib).
+
+Quacks like an exception
+------------------------
+
+When you create a misfit exception module, it can be used as if it was an exception class.  For example (the `YourLib:Error` example above)
+
+    raise YourLib::Error, "an error"
+    raise YourLib::Error.new("an error")
+    YourLib::Error.exception(<message>, <backtrace>)
+    
+all work as if `YourLib::Error` was a ruby Exception class.
+
+Niceties
+--------
+
+You can set the default basic Ruby exception class, and you can set up the equivalent of an inheritance hierarchy by simply including from the parent Exception:
+
+    module YourLib
+      module Error
+        include Misfit
+      end
+      
+      module NotFoundError
+        include Error
+        exception_class IndexError
+      end
+    end
+    
+`raise YourLib::NotFoundError` will be rescued by `YourLib::NotFoundError`, `YourLib::Error`, and `IndexError`
+
+You can also optionally wrap and add data to any Error:
+
+    e = YourLib::Error.wrap RuntimeError.new("Bad stuff"), {some: 'data'}
+    e.is_a?(RuntimeError)   # => true
+    e.is_a?(YourLib::Error) # => true
+    e.data                  # => {some: 'data'}
+
+`YourLib::Error.wrap &block` causes all raised exceptions to be wrapped as `YourLib::Error`
+
+Other Examples of use:
+----------------------
+
+    module MyError
+      include Misfit
+    end
+
+    raise MyError, "foo"
+    # the above will be rescued as a StandardError, and a MyError
+
+    raise MyError.wrap ArgumentError.new('Bad args')
+    # the above will be rescued as an ArgumentError, and a MyError
+
+    MyError.wrap do
+      # some stuff that might raise errors
+    end
+    # any errors raised will also be MyErrors
+  
+    Adding data to exceptions
+
+    MyError.new 'foo', {some: data}
+    # this will be a MyError with #data => {some: data}
+
+    MyError.wrap exception, {some: data}
+    # the resulting exception will be a MyError, and have #data attribute of {some: data}
+
+    # set up an error that has a different class as its base (like IOError for example)
+    module MyIOError
+      include MyError
+      exception_class IOError
+    end
+
+    # the resulting error will be an IOError, extended with MyIOError, and MyError, and will be rescued as such
+    raise MyIOError

data/Rakefile

@@ -0,0 +1,33 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Misfit'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md', 'CHANGELOG', 'MIT-LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run the specs with simplecov"
+task :simplecov => [:simplecov_env, :spec]
+task :simplecov_env do ENV['SIMPLECOV'] = '1' end
+
+task :default => :spec

data/lib/misfit.rb

@@ -0,0 +1,61 @@
+require 'active_support/concern'
+require 'active_support/core_ext'
+
+module Misfit
+  extend ActiveSupport::Concern
+  
+  included do inherit_from_misfit end
+  
+  def self.exception_class
+    StandardError
+  end
+  
+  attr_accessor :data
+  
+  module ClassMethods
+    # when called with an exception, makes the exception a <self>
+    # when called with a block, any exceptions raised in the block will be wrapped as <self>
+    def wrap *args, &block
+      if block
+        wrap_block &block
+      else
+        wrap_exception *args
+      end
+    end
+    
+    def new message, data = nil, *backtrace
+      wrap_exception exception_class.exception(message, *backtrace), data
+    end
+    
+    def exception message, *args
+      new message, nil, *args
+    end
+    
+    def exception_class klass = nil
+      @exception_class = klass if klass
+      @exception_class
+    end
+    
+  private
+    def wrap_exception exception, data = nil
+      exception.tap do |e|
+        e.extend self unless e.is_a?(self)
+        e.data = data if data
+      end
+    end
+    
+    def wrap_block
+      yield
+    rescue Exception => exception
+      raise wrap_exception(exception)
+    end
+    
+    # when an exception module is included, set up this module
+    # as an exception module itself, and 'inherit' the exception_class
+    def inherit_from_misfit
+      extend ActiveSupport::Concern
+      exception_class ancestors[1].exception_class
+      included do inherit_from_misfit end
+    end
+  end
+end

data/lib/misfit/version.rb

@@ -0,0 +1,3 @@
+module Misfit
+  VERSION = '0.0.1'
+end

data/spec/misfit_spec.rb

@@ -0,0 +1,140 @@
+require 'spec_helper'
+
+module MisfitSpec
+  #
+  #   Error
+  #   +- FooError (RuntimeError)
+  #      +- FazError (ArgumentError)
+  #         +- BarError
+  module Error
+    include Misfit
+  end
+  
+  module FooError
+    include Error
+    exception_class RuntimeError
+  end
+  
+  module FazError
+    include FooError
+    exception_class IOError
+  end
+  
+  module BarError
+    include FazError
+  end
+  
+  describe Misfit do
+    describe 'Error (includes Misfit)' do
+      subject { exception_module }
+
+      let(:exception_module) { Error }
+      let(:message)          { 'message' }
+      let(:data)             { 'exception data' }
+
+      describe 'standard idioms' do
+        describe 'raise <exception_module>, <message>' do
+          subject { raise exception_module, message }
+
+          it { expect{ subject }.to raise_error(StandardError, message) }
+          it { expect{ subject }.to raise_error(exception_module, message) }
+        end
+      
+        describe 'raise <exception_module>.new(<message>)' do
+          subject { raise exception_module.new(message) }
+
+          it { expect{ subject }.to raise_error(StandardError, message) }
+          it { expect{ subject }.to raise_error(exception_module, message) }
+        end
+      
+        describe 'raise <exception_module>.exception(<message>)' do
+          subject { raise exception_module.exception(message) }
+
+          it { expect{ subject }.to raise_error(StandardError, message) }
+          it { expect{ subject }.to raise_error(exception_module, message) }
+        end
+        
+        describe 'FooError (includes Error, exception_class RuntimeError)' do
+          let(:exception_module) { FooError }
+
+          describe 'raise <exception_module>, <message>' do
+            subject { raise exception_module, message }
+
+            it { expect{ subject }.to raise_error(Error, message) }
+            it { expect{ subject }.to raise_error(FooError, message) }
+            it { expect{ subject }.to raise_error(RuntimeError, message) }
+          end
+        end
+        
+        describe 'FazError (includes FooError, exception_class IOError)' do
+          let(:exception_module) { FazError }
+
+          describe 'raise <exception_module>, <message>' do
+            subject { raise exception_module, message }
+
+            it { expect{ subject }.to raise_error(Misfit, message) }
+            it { expect{ subject }.to raise_error(Error, message) }
+            it { expect{ subject }.to raise_error(FooError, message) }
+            it { expect{ subject }.to raise_error(FazError, message) }
+            it { expect{ subject }.to raise_error(IOError, message) }
+          end
+        end
+        
+        describe 'BarError (includes FazError)' do
+          let(:exception_module) { BarError }
+
+          describe 'raise <exception_module>, <message>' do
+            subject { raise exception_module, message }
+
+            it { expect{ subject }.to raise_error(Error, message) }
+            it { expect{ subject }.to raise_error(FooError, message) }
+            it { expect{ subject }.to raise_error(FazError, message) }
+            it { expect{ subject }.to raise_error(BarError, message) }
+            it { expect{ subject }.to raise_error(IOError, message) }
+          end
+        end
+      end
+      
+      describe 'adding data' do
+        describe 'raise <exception_module>.new <message>, <data>' do
+          subject { raise exception_module.new(message, data) }
+                  
+          it "should have data added to the exception" do
+            begin
+              subject
+            rescue => e
+              e.data.should == data
+            end
+          end
+        end
+      end
+      
+      describe '#wrap' do
+        describe 'RuntimeError.new(<message>)' do
+          subject { exception_module.wrap RuntimeError.new(message) }
+          
+          it { should be_a RuntimeError }
+          it { should be_a exception_module }
+          its(:message) { should == message }
+        end
+        
+        describe 'RuntimeError.new(<message>), <exception data>' do
+          subject { exception_module.wrap RuntimeError.new(message), data }
+          
+          it { should be_a RuntimeError }
+          it { should be_a exception_module }
+          its(:message) { should == message }
+          its(:data) { should == data }
+        end
+        
+        describe '{ some_error_ridden_code! }' do
+          subject { exception_module.wrap do some_error_ridden_code! end }
+            
+          it { expect{ subject }.to raise_error(NoMethodError, /some_error_ridden_code!/) }
+          it { expect{ subject }.to raise_error(exception_module, /some_error_ridden_code!/) }
+        end
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+if ENV['SIMPLECOV']
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter "_spec.rb"
+  end
+end
+
+require 'rspec'
+require_relative '../lib/misfit'

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: misfit
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Ian White
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70193682798820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70193682798820
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70193682798160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70193682798160
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70193682797400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: *70193682797400
+description: Flexible approach to handling exceptions in ruby (for library writers,
+  or consumers).  Ispired by Avdi Grimm's excellent book 'Exceptional Ruby'.
+email:
+- ian.w.white@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/misfit/version.rb
+- lib/misfit.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- CHANGELOG
+- spec/misfit_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/i2w/misfit
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1488499911703821850
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1488499911703821850
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Flexible approach to handling exceptions in ruby (for library writers, or
+  consumers)
+test_files:
+- spec/misfit_spec.rb
+- spec/spec_helper.rb