mulligan 0.4.1

data/lib/mulligan.rb

@@ -0,0 +1,16 @@
+require "mulligan/version"
+require "mulligan/condition"
+require "mulligan/kernel"
+
+class Exception
+  include Mulligan::Condition
+end
+
+class Object
+  if RUBY_VERSION < "2.0"
+    # ruby 1.9 replaces raise in the extension
+    include Mulligan::Kernel
+  else
+    prepend Mulligan::Kernel
+  end
+end

data/mulligan.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mulligan/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mulligan"
+  spec.version       = Mulligan::VERSION
+  spec.required_ruby_version='~> 2.0'
+  spec.authors       = ["michaeljbishop"]
+  spec.email         = ["mbtyke@gmail.com"]
+  spec.summary       = %q{Adds restarts to Ruby's Exception class (similar to LISP Conditions)}
+  spec.description   = <<__END__
+Allows you to decouple the code implementing a exception-handling strategy from the code which decides which strategy to use.
+
+In other words, when you handle a Mulligan::Condition in your rescue clause, you can choose from a set of strategies (called "restarts") exposed by the exception to take the stack back to where #raise was called, execute your strategy, and pretend that the exception was never raised.
+__END__
+  spec.homepage      = "http://michaeljbishop.github.io/mulligan"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.extensions    = %w[ext/mulligan/extconf.rb]
+  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.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rake-compiler"
+end

data/plan.markdown

@@ -0,0 +1,129 @@
+Features
+========
+
+Specify restart strategies for a given Exception
+------------------------------------------------
+Simply put, this adds "restarts" to the `Exception` class which allows exception raisers to specify multiple strategies for recovering from the exception. The strategies are attached to the Exception instance which travel as the stack unwinds to the enclosing `rescue` clause higher up on the stack. That rescue clause can then invoke a recovery strategy.
+
+What is special is that when the recovery strategy is invoked, the stack is recreated to the point in time where the Exception was raised and the recovery strategy is invoked in *that* context, as if the exception were never raised to begin with. This allows code higher up in abstraction to inject recovery into low-level code making the low-level code more reusable.
+
+In pseudocode:
+
+    def inner_function
+      raise
+      <specify some restarts here>
+    end
+
+    def outer_function
+      inner_function # will cause an exception with restarts
+    rescue Exception => e
+      # here we specify a recovery and we are able to repair the lower
+      # level code as if it never threw an exception to begin with
+      e.restart <strategy id>
+    end
+
+
+Restart strategies can accept parameters
+----------------------------------------
+In addition, restarts can accept parameters to affect their implementation. In this way, when a restart is invoked, some state can be passed to it, affecting its execution.
+
+Future Ideas
+============
+
+Specify restarts using a nice DSL
+---------------------------------
+We should be be able to specify restart clauses using a nice, concise language.
+
+Here are some examples:
+
+    raise Exception, "Could not do the thing!" do
+      restart :ignore do
+        # simply doing nothing ignores the error
+      end
+      restart :replace_entry do |replacement|
+        replacement
+      end
+    end
+
+
+Be able to catch an exception and add restarts to it before rethrowing it
+-------------------------------------------------------------------------
+We should be able to catch an exception from below, and add our own strategies to it
+
+Here is an example:
+
+    def rethrow
+      should_retry = false
+      inner_call
+    rescue Exception => e
+      e.add_restarts do
+        restart :retry do
+          should_retry = true
+        end
+      end
+      retry if should_retry
+    end
+
+When overriding a restart, should be able to call previous restart (super?)
+-------------------------------------------------------------------------
+
+Here is an example:
+
+    def rethrow
+      inner_call
+    rescue Exception => e
+      e.add_restarts do |super_restarts|
+        restart :fix do
+          super_restarts[:fix].call
+        end
+      end
+    end
+
+Restarts can have some metadata associated with them
+----------------------------------------------------
+Like LISP, it would be nice to be able to handle these in the debugger by default. The debugger should be able to specify a nice interface to the user by outputting messages from the metatdata associated with a restart strategy (like a description of what it does and what parameters it will take)
+
+
+`#raise` will return the strategy chosen and the return value of the strategy
+-----------------------------------------------------------------------------
+    chosen = raise "can't to the thing" do
+      restart :ignore do
+        5
+      end
+    end
+
+    puts chosen # => [:ignore, 5]
+
+
+Exceptions can carry data with them from the raise condition that the rescuers can use
+--------------------------------------------------------------------------------------
+I'm not sure if this is totally needed and think it's a separate item, *but* here's what it might look like:
+
+    class Exception
+      attr_reader :restart_data
+      def initialize(m, message = "", c = callback, options={}, &restart_block)
+        @restart_data = options[:restart_data]
+      end
+    end
+
+
+Smalltalk has some built-in strategies
+--------------------------------------
+- #exit, #resume (like ignore, it means just continue as if it hadn't been thrown)
+- #outer (reraise with the same strategy identifier except that now returns to this point)
+- #pass (reraise the exception)
+- #resignalAs:. Raise a different class of exception in place of the current exception, as if the new class of exception had been raised in the first place.
+- #retry (note: not sure how we can make this a built-in)The try-block associated with the handler (i.e. the receiver of the #on:do: to which it is the last argument) is re-evaluated. Of course it is pointless retrying if the same exception will be raised, and this is an easy way to create an infinite loop (though Ctrl+Break should
+#retryUsing: Substitute the argument as the new try block, and #retry. This has particular application for operations which have fast implementations for commonly used execution paths, and slower implementations for less common usages. get you out of trouble). - Super-interesting. Wonder if we might try it.
+
+Dylan has a way of attaching a standard set of recoveries to a given Exception class
+------------------------------------------------------------------------------------
+So a given Exception class would have a documented set of recoveries (they refer to it as a protocol)
+
+You can use a global variable to reference the last restart taken
+-----------------------------------------------------------------
+One of the difficult problems to solve is, what should #raise return? Currently, it returns the array of the restart chosen and the result of the restart block. I really like that we can get the result of the restart block, but I really don't like that methods written with raise that are ignored suddenly implicitly return an array. Yet to implement a property retry, it's important to know which restart was executed. I'd like the cleanliness of #raise returning only the return value of the block and the cleanliness of being able to know which restart was chosen.
+
+One solution is to have #raise return the value straight through and use a thread-local global variable that holds the id of the last invoked restart. So far, the only use case I've seen that requires that information is to do a retry inside a rescue clause.
+
+

data/spec/mulligan_spec.rb

@@ -0,0 +1,391 @@
+require 'spec_helper'
+
+describe Mulligan do
+  it 'should have a version number' do
+    Mulligan::VERSION.should_not be_nil
+  end
+
+  shared_examples "a Mulligan Condition" do
+    it 'should propagate errors' do
+      expect { outer_test(style) }.to raise_error
+    end
+
+    it 'should correctly report missing strategies' do
+      outer_test(style){|e|e.has_recovery?(:aaa)}.should be_false
+    end
+
+    it 'should correctly report included strategies' do
+      outer_test(style){|e|e.has_recovery?(:ignore)}.should be_true
+    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]
+    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
+
+    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 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
+    
+    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
+    
+    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 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 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
+
+      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
+
+      it "should support overriding a recovery and calling the inherited recovery"
+    end
+  end
+    
+  context Exception 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
+    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}
+        end
+      rescue Exception => e
+        expect(e.has_recovery?:ignore).to be_true
+      end
+    end
+
+    it "should properly report the line when raising with no block" do
+      begin
+        line = __LINE__ ; raise "Test"
+      rescue => e
+        expect(line_from_stack_string(e.backtrace[0])).to eq(line)
+      end
+    end
+
+    it "should properly report the line when raising WITH a block" do
+      begin
+        line = __LINE__ ; raise "Test" do |e|
+          false
+        end
+      rescue => e
+        expect(line_from_stack_string(e.backtrace[0])).to eq(line)
+      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
+          raise Exception, "test"
+        rescue Exception => e
+          expect($!).to be(e)
+          begin
+            raise
+          rescue Exception => e2
+            expect(e2).to be(e)
+          end
+        end
+      end
+      
+      it "should raise a RuntimeError when $! is nil"  do
+        expect { raise }.to raise_error(RuntimeError)
+      end
+    end
+    
+    it "should raise a RuntimeError with string message when raise is called only with a string" do
+      message = "test"
+      begin
+        raise message
+      rescue RuntimeError => e
+        expect(e.message).to eq(message)
+      end
+    end
+
+    it "should raise a TypeError when called with two strings" do
+      expect {
+        raise "hello", "world"
+      }.to raise_error(TypeError)
+    end
+    
+    it "should, when called with a Exception subclassclass, raise that subclass" do
+      expect {
+        raise CustomException
+      }.to raise_error(CustomException)
+    end
+
+    context "when called with an object instance," do
+      let(:object){CustomObjectReturner.new}
+
+      it "should raise the result of calling object.exception" do
+        expect{ raise object }.to raise_error(CustomException)
+      end
+
+      it "and a string, should raise the result of calling object.exception with a custom message" do
+        begin
+          raise object, "test"
+        rescue CustomException => e
+          expect(e.message).to eq("test")
+        end
+      end
+    end
+
+  end
+
+  describe "Kernel#raise" do
+    let(:style){:raise}
+    it_behaves_like "raising exceptions"
+  end
+end
+
+
+class CustomException < Exception
+end
+
+class CustomObjectReturner
+  def exception(*args)
+    CustomException.new(*args)
+  end
+end
+
+
+#=======================
+#    HELPER METHODS
+#=======================
+
+def scope_test
+  result = 5
+  raise do |e|
+    e.set_recovery :change do |arg|
+      result = 7
+    end
+  end
+  result
+end
+
+
+
+
+
+#=======================
+#    HELPER METHODS
+#=======================
+
+# returns the line given a string from Exception#backtrace
+def line_from_stack_string(s)
+  s.match(/[^:]+:(\d+)/)[1].to_i
+end
+
+def core_test(style)
+  t =  "Test Exception"
+  t = Exception.new("Test Exception") if style == :manual
+  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_all_params){|*p|next *p}
+    e.set_recovery(:return_param2){|p|p}
+  end
+end
+
+
+def inner_test(style = :manual)
+  core_test(style)
+rescue Exception => e
+  result = raise(e) do |e|
+    e.set_recovery(:retry){}
+  # here we add 10 so we can ensure we are in fact, overriding
+  # the behavior for the same recovery as defined in core_test
+    e.set_recovery(:return_param2){|p|p+10}
+  end
+  retry if last_recovery == :retry
+  # here we add 10 so we can differentiate retries in `inner_test` from `core_test`
+  # we know we are in inner_test if our result is plus 10
+  result + 10
+end
+
+
+def outer_test(style = :manual, &handler)
+  inner_test(style)
+rescue Exception => e
+  handler.call(e)
+end
+
+
+
+#===========================
+#   SIMULATE LOGIN EXPIRE
+#===========================
+
+# simple method that logs the user in
+
+@credentials = "password"
+def login
+  @credentials = "password"
+  @count_of_calls_before_failure = 2
+end
+
+
+class CredentialsExpiredException < Exception ; end
+
+# at a low level, we will just raise a CredentialsExpiredException if that's
+# the response we get from the server
+def rest_get(url)
+  # simulate that the credentials expire after a certain period
+  @credentials = nil if @count_of_calls_before_failure <= 0
+  @count_of_calls_before_failure = @count_of_calls_before_failure - 1
+
+  # Simulate getting a response from the server indicating our credentials
+  # have expired.
+  raise(CredentialsExpiredException, "Credentials expired") if @credentials != "password"
+
+  # Canned data to return
+  "json_data"
+end
+
+# this takes a resource, makes an URL for that and returns the raw data provided
+# from rest_get.
+# It also specifies a "retry" recovery in case the credentials can be restored by
+# code at a higher level
+def request_resource(name)
+  url = "http://site.com/#{name}"
+  rest_get(url)
+  
+rescue CredentialsExpiredException => e
+  # re-raise the exception but add a recovery so if they fix the credentials
+  # we can try again
+  raise (e) do |e|
+    e.set_recovery(:retry){true}
+  end
+  retry if last_recovery == :retry
+  result
+end
+
+# This is the method that demonstrates how it all comes together.
+# We can handle all credential failures from a very high-level.
+# Because #request_resource offers a retry recovery, any code that calls
+# #request_resource doesn't have to worry about the state of the user's credentials.
+# Those exceptions will be thrown and the handling of them will at a very high-level
+# of abstraction, yet, after they are handled, the program will continue as if the
+# exception hadn't been thrown to begin with.
+def do_network_task
+  {
+    :users    => request_resource("users"),   # This one should work
+    :posts    => request_resource("posts"),   # This one should work
+    :comments => request_resource("comments") # This one should fail
+  }
+  
+  # Here, we handle any requests where credentials fail and we re-login
+  # then we ask to retry the same query
+rescue CredentialsExpiredException => e
+  login
+  e.recover :retry
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'mulligan'

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: mulligan
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- michaeljbishop
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-12 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: |
+  Allows you to decouple the code implementing a exception-handling strategy from the code which decides which strategy to use.
+
+  In other words, when you handle a Mulligan::Condition in your rescue clause, you can choose from a set of strategies (called "restarts") exposed by the exception to take the stack back to where #raise was called, execute your strategy, and pretend that the exception was never raised.
+email:
+- mbtyke@gmail.com
+executables: []
+extensions:
+- ext/mulligan/extconf.rb
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- ext/mulligan/extconf.rb
+- ext/mulligan/mulligan.c
+- lib/mulligan.rb
+- lib/mulligan/condition.rb
+- lib/mulligan/kernel.rb
+- lib/mulligan/kernel_common.rb
+- lib/mulligan/kernel_pure.rb
+- lib/mulligan/version.rb
+- mulligan.gemspec
+- plan.markdown
+- spec/mulligan_spec.rb
+- spec/spec_helper.rb
+homepage: http://michaeljbishop.github.io/mulligan
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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
+signing_key: 
+specification_version: 4
+summary: Adds restarts to Ruby's Exception class (similar to LISP Conditions)
+test_files:
+- spec/mulligan_spec.rb
+- spec/spec_helper.rb