mulligan 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93a82e010fe6e85e2d4258e582448f6eba71aca0
-  data.tar.gz: e93698220f48079b7ed8a34889744fb84de4f657
+  metadata.gz: e62a4787a90e87a4813e17e7349f7df21e189fd5
+  data.tar.gz: 4729dca38e624e26c7d3e17c14bb5baf270641b4
 SHA512:
-  metadata.gz: 68fa8ce73ecec03457111bd4acc355b260e7fb5faccff1bb1a9195a9b62d2c761dce7406e53f3078cdf0fd94dae20829a98b90e3074017b1661331ac9cacf801
-  data.tar.gz: 172b8934dfdca12793f9931833d10d4a53aac6a831183150926ad591d7e9fbbe0261804692b25cc557a21d2948b36b485a23c07e1a4f03606c1d40a7ab54b319
+  metadata.gz: 9afd8d4695eddffa042b80bc325697b5171348551e1d8d6afe7b51b819e5da885bb73c232eb0bf84e141bf226dc7c536339e820bcbf1559fe50ccb49adff530d
+  data.tar.gz: 5f521f212960b68e60c2ed9fe87ad9100f1c44925d60e297b70e87efc3b58d865e66ab50e2bc2fec06bddf585b9eb69bbb45fc6c5462852189c2bef6421601b9

data/.travis.yml

@@ -1,6 +1,11 @@
 language: ruby
 rvm:
-  - 1.9.3-p484
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
   - 2.0.0
   - 2.1.0
   - 2.1.1
+  - jruby-19mode
+  - jruby-18mode
+  - rbx-2.1.1

data/README.md

@@ -1,5 +1,6 @@
 [![Build Status](https://travis-ci.org/michaeljbishop/mulligan.png?branch=master)](https://travis-ci.org/michaeljbishop/mulligan)
-# Mulligan
+
+<img src="http://michaeljbishop.github.io/mulligan/images/mulligan-logo.png" height="155" width="440" alt="Mulligan">
 
 "In golf,...a stroke that is replayed from the spot of the previous stroke without penalty, due to an errant shot made on the previous stroke. The result is, as the hole is played and scored, as if the first errant shot had never been made." -- [Wikipedia](http://en.wikipedia.org/wiki/Mulligan_(games)#Mulligan_in_golf)
 
@@ -118,9 +119,8 @@ BTW, Here's your second chance to read [Beyond Exception Handling: Conditions an
 
 You've always known he (or she) knew Lisp and now you have something to ask him about.
 
-## Some Notes About the Ruby Implementation
-### Methods
-#### Kernel#raise
+## API
+### Kernel#raise
 1. `Kernel#raise` now has a return value! It is the value returned from the recovery block.
 2. `Kernel#raise` also yields the exception to a block. It does this since it's pretty common to have `Kernel#raise` create an exception for you and without this, you couldn't otherwise attach recoveries.
 
@@ -143,7 +143,7 @@ returns
  => "hello" 
 ```
 
-#### You can pass parameters to Exception#recover
+### You can pass parameters to Exception#recover
 The first parameter is always the id of the recovery. The rest will be passed directly to the recovery block. Building on the above example:
 
 ```ruby
@@ -165,7 +165,7 @@ returns
  => 5
 ```
 
-#### Your recovery can attach data to be read by the rescue clause
+### Your recovery can attach data to be read by the rescue clause
 You can pass an options hash to the `rescue` clause that is attached to your recovery. This is handy if you want to attach extra data about the recovery or the circumstances in which it is being raised. Pass them as the second parameter in `Exception#set_recovery`. You can retrieve them with `Exception#recovery_options`. Reserved keys are `:summary`, and `:discussion`
 ```ruby
 raise "Test" do |e|
@@ -185,7 +185,7 @@ rescue MisparsedEntryException => e
   ... read choice and execute ...
 ```
 
-#### Kernel#last_recovery
+### Kernel#last_recovery
 There is a new method: `Kernel#last_recovery` which will return the id of the last recovery invoked for the current thread. So you can do things like this:
 
 ```ruby
@@ -197,16 +197,25 @@ rescue Exception => e
 end
 ```
 
-### Mulliigan uses #callcc
+## Supported Rubies
 
-There is more than one way to do this. In the end, I wanted something that would fit very naturally into Ruby's existing Exception mechanism, yet offer as much of the benefits of Lisp's "restart" as I could.
+[![Build Status](https://travis-ci.org/michaeljbishop/mulligan.png?branch=master)](https://travis-ci.org/michaeljbishop/mulligan)
+Mulligan fully supports MRI versions 1.9.3 -> 2.1.1
 
-However, to make that happen, I had to use the `#callcc` method. I'm not completely sure how supported this is across different Ruby implementations. Additionally, I've read that it can be a rather slow method. It's important to note that if an exception is raised but does not have any attached recoveries, `#callcc` will not be called and the standard exception mechanism is used.
+Mulligan will gracefully degrade to standard exception handling on other platforms.
 
-### Ruby Support
+### Compatibility Notes
 
-[![Build Status](https://travis-ci.org/michaeljbishop/mulligan.png?branch=master)](https://travis-ci.org/michaeljbishop/mulligan)
- Mulligan supports MRI versions 1.9.3 -> 2.1.1
+- Code that ***raises*** exceptions and adds recoveries can always remain the same, regardless of the Ruby version.
+
+- Code that ***rescues*** exceptions will need to either:
+
+    - Call `Exception#recovery_exist?` before calling `Exception#recover`, which is good defensive programming.
+    - Conditionally execute recoveries based on `Mulligan.supported?`
+
+- If `Exception#recover` is called in a Ruby that doesn't fully support Mulligan, a `Mulligan::UnsupportedException` will be raised. This is to alert the author that execution is not going to jump back into the context where the exception was raised and the code will instead have to behave as if there were no mulligans (standard exception handling).
+
+## FAQ
 
 ### "Recovery"? What's wrong with "Restart"?
 
@@ -214,6 +223,10 @@ I had to make a hard choice about naming the thing that allows an exception to b
 
 Changing the name to a noun subtracts that confusion (though arguably adds some back for those coming from languages where the "restart" name is entrenched).
 
+### Will Mulligan let me resume from all exceptions?
+
+No. If an exception didn't have recoveries attached when it was raised, you will not be able to call them. It is incumbent on the code that raises the exception to add the recoveries so they can control the error-handling flow.
+
 ## Influences
 - [Beyond Exception Handling: Conditions and Restarts](http://www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html) -- (from [Practical Common Lisp](http://www.gigamonkeys.com/book/))
 - [Things You Didn't Know About Exceptions](http://avdi.org/talks/rockymtnruby-2011/things-you-didnt-know-about-exceptions.html) (Avdi Grimm)

data/Rakefile

@@ -1,12 +1,18 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-require "rake/extensiontask"
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
 
-Rake::ExtensionTask.new "mulligan" do |ext|
-  ext.lib_dir = "lib/mulligan"
+def supports_mulligan?
+  defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && RUBY_VERSION >= "1.9.3"
 end
 
-RSpec::Core::RakeTask.new(:spec => :compile)
+if supports_mulligan?
+  require "rake/extensiontask"
 
-task :default => :spec
+  Rake::ExtensionTask.new "mulligan" do |ext|
+    ext.lib_dir = "lib/mulligan"
+  end
+  task :spec => :compile
+end

data/lib/mulligan.rb

@@ -1,3 +1,17 @@
+module Mulligan
+
+  def self.supported?
+    !!(defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && RUBY_VERSION >= "1.9.3")
+  end
+
+  def self.using_extension?
+    supported?
+  end
+
+  class UnsupportedException < Exception
+  end
+end
+
 require "mulligan/version"
 require "mulligan/condition"
 require "mulligan/kernel"

data/lib/mulligan/condition.rb

@@ -17,10 +17,16 @@ module Mulligan
     #                 :discussion - The complete documentation of this recovery. Please include a
     #                               description of the behavior, the return parameter, and any parameters
     #                               the recovery can take
-    def set_recovery(id, options={}, &block)
-      return if block.nil?
-      recoveries[id.to_sym] = options.merge(:block => block)
-      nil
+    if Mulligan.supported?
+      def set_recovery(id, options={}, &block)
+        return if block.nil?
+        recoveries[id.to_sym] = options.merge(:block => block)
+        nil
+      end
+    else
+      def set_recovery(id, options={}, &block)
+        nil
+      end
     end
     
     # Checks for the presence of a recovery
@@ -56,6 +62,8 @@ module Mulligan
     # @param params any additional parameters you want to pass to the recovery block
     # @return This doesn't actually matter because you can't retrieve it
     def recover(id, *params)
+      raise Mulligan::UnsupportedException unless Mulligan.supported?
+
       Thread.current[:__last_recovery__] = nil
       raise ControlException unless has_recovery?(id.to_sym)
       data = recoveries[id.to_sym]
@@ -65,6 +73,7 @@ module Mulligan
       end
       Thread.current[:__last_recovery__] = id
       data[:continuation].call(*data[:block].call(*params))
+      true
     end
   
   private

data/lib/mulligan/kernel.rb

@@ -1,4 +1,5 @@
-require "mulligan/mulligan"
-require_relative 'kernel_common'
+if Mulligan.using_extension?
+  require "mulligan/mulligan"
+end
 
-# raise is implemented by the c-extension
+require "mulligan/kernel_common"

data/lib/mulligan/kernel_common.rb

@@ -1,4 +1,4 @@
-require 'continuation'
+require 'continuation' if Mulligan.supported?
 
 module Mulligan
   module Kernel

data/lib/mulligan/kernel_pure.rb

@@ -1,4 +1,4 @@
-require_relative 'kernel_common'
+require "mulligan/kernel_common"
 
 module Mulligan
   module Kernel
@@ -14,7 +14,8 @@ module Mulligan
       super
     rescue Exception => e
       yield e if block_given?
-
+      super(e) unless Mulligan.supported?
+      
       # only use callcc if there are restarts otherwise re-raise it
       super(e) if e.send(:recoveries).empty?
       should_raise = true
@@ -27,5 +28,6 @@ module Mulligan
       super(e) if should_raise
       result
     end
+    
   end
 end

data/lib/mulligan/version.rb

@@ -1,3 +1,3 @@
 module Mulligan
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/spec/mulligan_spec.rb

@@ -15,117 +15,158 @@ describe Mulligan do
     end
 
     it 'should correctly report included strategies' do
-      outer_test(style){|e|e.has_recovery?(:ignore)}.should be_true
+      outer_test(style){|e|e.has_recovery?(:ignore)}.should eq Mulligan.supported?
     end
 
     it 'should correctly report the list of recoveries' do
-      outer_test(style){|e|e.recovery_identifiers}.should == [:ignore, :return_param, :return_all_params, :return_param2, :retry]
+      outer_test(style){|e|e.recovery_identifiers}.should
+      Mulligan.supported? ?
+        [:ignore, :return_param, :return_all_params, :return_param2, :retry] :
+        be_empty
     end
 
-    it 'should raise a control exception when invoking a non-existent recovery' do
-      expect { outer_test(style){|e|e.recover :aaa} }.to raise_error(Mulligan::ControlException)
-    end
+    if Mulligan.supported?
+      context "when Mulligan is supported" do
+        it 'should raise a control exception when invoking a non-existent recovery' do
+          expect { outer_test(style){|e|e.recover :aaa} }.to raise_error(Mulligan::ControlException)
+        end
 
-    it 'should not raise an exception when invoking the ignore recovery' do
-      expect { outer_test(style){|e|e.recover :ignore} }.to_not raise_exception
-    end
+        it 'should not raise an exception when invoking the ignore recovery' do
+          expect { outer_test(style){|e|e.recover :ignore} }.to_not raise_exception
+        end
 
-    it 'should return the parameter sent when invoking the return_param recovery' do
-      result = outer_test(style){|e|e.recover(:return_param, 5)}
-      result.should be(5)
-    end
+        it 'should return the parameter sent when invoking the return_param recovery' do
+          result = outer_test(style){|e|e.recover(:return_param, 5)}
+          result.should be(5)
+        end
 
-    it 'should return all parameters sent when invoking the return_all_params recovery' do
-      result1, result2 = outer_test(style){|e|e.recover(:return_all_params, 5, 6)}
-      result1.should eq(5)
-      result2.should eq(6)
-    end
+        it 'should return all parameters sent when invoking the return_all_params recovery' do
+          result1, result2 = outer_test(style){|e|e.recover(:return_all_params, 5, 6)}
+          result1.should eq(5)
+          result2.should eq(6)
+        end
 
-    context "and follows the continutation to the correct raise" do
-      it 'should return the parameter sent when invoking the return_param recovery' do
-        result = outer_test(style){|e|e.recover(:return_param2, 5)}
-        result.should be(25)
-      end
-    end
-    
-    it "should ignore setting a recovery when passed no block" do
-      expect { outer_test(style){|e|e.recover :no_block} }.to raise_error(Mulligan::ControlException)
-    end
+        context "and follows the continutation to the correct raise" do
+          it 'should return the parameter sent when invoking the return_param recovery' do
+            result = outer_test(style){|e|e.recover(:return_param2, 5)}
+            result.should be(25)
+          end
+        end
     
-    it "should retrieve the network request without an exception" do
-      @count_of_calls_before_failure = 2
-
-      result = nil
-      expect { result = do_network_task }.to_not raise_error
-      expect(result).to eq(
-        {
-          :users    => "json_data",
-          :posts    => "json_data",
-          :comments => "json_data"
-        }
-      )
-    end
+        it "should ignore setting a recovery when passed no block" do
+          expect { outer_test(style){|e|e.recover :no_block} }.to raise_error(Mulligan::ControlException)
+        end
     
-    describe "recovery options" do
-      it "should not return the block" do
-        data = nil
-        outer_test(style) do |e|
-          data = e.recovery_options(:return_param)[:block]
-          e.recover(:return_param)
+        it "should retrieve the network request without an exception" do
+          @count_of_calls_before_failure = 2
+
+          result = nil
+          expect { result = do_network_task }.to_not raise_error
+          expect(result).to eq(
+            {
+              :users    => "json_data",
+              :posts    => "json_data",
+              :comments => "json_data"
+            }
+          )
         end
-        expect(data).to be_nil
-      end
+    
+        describe "recovery options" do
+          it "should not return the block" do
+            data = nil
+            outer_test(style) do |e|
+              data = e.recovery_options(:return_param)[:block]
+              e.recover(:return_param)
+            end
+            expect(data).to be_nil
+          end
 
-      it "should not return the continuation" do
-        data = nil
-        outer_test(style) do |e|
-          data = e.recovery_options(:return_param)[:continuation]
-          e.recover(:return_param)
-        end
-        expect(data).to be_nil
-      end
+          it "should not return the continuation" do
+            data = nil
+            outer_test(style) do |e|
+              data = e.recovery_options(:return_param)[:continuation]
+              e.recover(:return_param)
+            end
+            expect(data).to be_nil
+          end
+
+          it "should pass data created in set_recovery" do
+            data = nil
+            outer_test(style) do |e|
+              data = e.recovery_options(:return_param)[:data]
+              e.recover(:return_param)
+            end
+            expect(data).to be(5)
+          end
+
+          it "should pass summary created in set_recovery" do
+            data = nil
+            outer_test(style) do |e|
+              data = e.recovery_options(:return_param)[:summary]
+              e.recover(:return_param)
+            end
+            expect(data).to eq("Passes the parameter sent in as the value of the block.")
+          end
 
-      it "should pass data created in set_recovery" do
-        data = nil
-        outer_test(style) do |e|
-          data = e.recovery_options(:return_param)[:data]
-          e.recover(:return_param)
+          it "should be read-only" do
+            result = outer_test(style) do |e|
+              e.recovery_options(:return_param)[:new_entry] = 5
+              e.recover(:return_param, e)
+            end
+            expect(result.recovery_options(:return_param)[:new_entry]).to be_nil
+          end
         end
-        expect(data).to be(5)
-      end
 
-      it "should pass summary created in set_recovery" do
-        data = nil
-        outer_test(style) do |e|
-          data = e.recovery_options(:return_param)[:summary]
-          e.recover(:return_param)
+        if Exception.method_defined?(:cause)
+          it "should support the `#cause` method in the native extension" do
+            begin
+              raise "test"
+            rescue => e
+              begin
+                raise "test2"
+              rescue =>e
+               expect(e.cause.message).to eq "test"
+              end
+            end
+          end
         end
-        expect(data).to eq("Passes the parameter sent in as the value of the block.")
+
+        it "should support overriding a recovery and calling the inherited recovery"
       end
+    else
+      context "when Mulligan is unsupported" do
+        it "should raise an unsupported Exception when invoking a recovery" do
+          expect{Exception.new.recover(:ignore)}.to raise_error(Mulligan::UnsupportedException)
+        end
 
-      it "should be read-only" do
-        result = outer_test(style) do |e|
-          e.recovery_options(:return_param)[:new_entry] = 5
-          e.recover(:return_param, e)
+        it "should not raise an exception when setting a recovery" do
+          expect{Exception.new.set_recovery(:ignore){|p|p}}.to_not raise_error
         end
-        expect(result.recovery_options(:return_param)[:new_entry]).to be_nil
-      end
 
-      if Exception.method_defined?(:cause)
-        it "should support the `#cause` method in the native extension" do
+        it "should not set a recovery" do
+          e = Exception.new
+          e.set_recovery(:ignore){|p|p}
+          expect(e.has_recovery?(:ignore)).to be_false
+        end
+        
+        it "should not execute the block yielded to raise" do
           begin
-            raise "test"
-          rescue => e
-            begin
-              raise "test2"
-            rescue =>e
-             expect(e.cause.message).to eq "test"
+            test = true
+            raise "test" do
+              test = false
             end
+          rescue
+          ensure
+            expect(test).to be_true
           end
         end
+        
+        it "should list 0 recoveries" do
+          e = Exception.new
+          e.set_recovery(:ignore){|p|p}
+          expect(e.recovery_identifiers).to be_empty
+        end
       end
-
-      it "should support overriding a recovery and calling the inherited recovery"
     end
   end
     
@@ -133,25 +174,38 @@ describe Mulligan do
     let(:style){:manual}
     it_behaves_like "a Mulligan Condition"
 
-    it "shouldn't fail when recovering before raising" do
-      t = Exception.new("Test Exception")
-      t.set_recovery(:ignore) {|p|}
-      expect{t.recover(:ignore)}.to_not raise_error
+    if Mulligan.supported?
+      it "shouldn't fail when recovering before raising" do
+        t = Exception.new("Test Exception")
+        t.set_recovery(:ignore) {|p|p}
+        expect{t.recover(:ignore)}.to_not raise_error
+      end
     end
   end
 
   shared_examples "raising exceptions" do
     it_behaves_like "a Mulligan Condition"
 
-    it "should propgate recoveries when raising a pre-existing exception" do
-      t = Exception.new("Test Exception")
-      t.set_recovery(:ignore) {|p|}
-      begin
-        raise t do |e|
-          e.set_recovery(:return_param){|p|p}
+    if Mulligan.supported?
+      it "should propgate recoveries when raising a pre-existing exception" do
+        t = Exception.new("Test Exception")
+        t.set_recovery(:ignore) {|p|p}
+        begin
+          raise t do |e|
+            e.set_recovery(:return_param){|p|p}
+          end
+        rescue Exception => e
+          expect(e.has_recovery?:ignore).to be_true
+        end
+      end
+
+      it "should modify variables in the binding of the raiser" do
+        begin
+          result = scope_test
+        rescue => e
+          e.recover :change
         end
-      rescue Exception => e
-        expect(e.has_recovery?:ignore).to be_true
+        expect(result).to eq(7)
       end
     end
 
@@ -173,15 +227,6 @@ describe Mulligan do
       end
     end
 
-    it "should modify variables in the binding of the raiser" do
-      begin
-        result = scope_test
-      rescue => e
-        e.recover :change
-      end
-      expect(result).to eq(7)
-    end
-
     context "when raise is called with no arguments" do
       it "should raise $! when $! is not nil" do
         begin
@@ -210,10 +255,10 @@ describe Mulligan do
       end
     end
 
-    it "should raise a TypeError when called with two strings" do
-      expect {
-        raise "hello", "world"
-      }.to raise_error(TypeError)
+    it "should raise an error when called with two strings" do
+      expect do
+        raise("hello", "world")
+      end.to raise_error
     end
     
     it "should, when called with a Exception subclassclass, raise that subclass" do
@@ -290,7 +335,7 @@ def core_test(style)
   raise t do |e|
     e.set_recovery(:ignore){|p|p}
     e.set_recovery(:no_block)
-    e.set_recovery(:return_param, data: 5, summary: "Passes the parameter sent in as the value of the block."){|p|p}
+    e.set_recovery(:return_param, :data => 5, :summary => "Passes the parameter sent in as the value of the block."){|p|p}
     e.set_recovery(:return_all_params){|*p|next *p}
     e.set_recovery(:return_param2){|p|p}
   end

metadata

@@ -1,69 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: mulligan
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - michaeljbishop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-12 00:00:00.000000000 Z
+date: 2014-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
 - !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: rake-compiler
   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: |
@@ -77,9 +77,9 @@ extensions:
 - ext/mulligan/extconf.rb
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -106,17 +106,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ~>
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Adds restarts to Ruby's Exception class (similar to LISP Conditions)