cond 0.2.0

data/cond.gemspec

@@ -0,0 +1,37 @@
+
+Gem::Specification.new { |t|
+  t.author = "James M. Lawrence"
+  t.email = "quixoticsycophant@gmail.com"
+  t.summary = "Resolve errors without unwinding the stack."
+  t.name = "cond"
+  t.rubyforge_project = t.name
+  t.homepage = "#{t.name}.rubyforge.org"
+  t.version = "0.2.0"
+  t.description = <<-EOS
+    +Cond+ allows errors to be handled at the place where they occur.
+    You decide whether or not the stack should be unwound, depending on
+    the circumstance and the error.
+  EOS
+  t.files = (
+    %W[README #{t.name}.gemspec] +
+    Dir["./**/*.rb"] +
+    Dir["./**/Rakefile"]
+  )
+  rdoc_exclude = %w[
+    spec
+    examples
+    readmes
+    support
+    lib/cond/cond_private
+  ]
+  t.has_rdoc = true
+  t.extra_rdoc_files = %w[README]
+  t.rdoc_options += [
+    "--main",
+    "README",
+    "--title",
+    "#{t.name}: #{t.summary}",
+  ] + rdoc_exclude.inject(Array.new) { |acc, pattern|
+    acc + ["--exclude", pattern]
+  }
+}

data/examples/bad_example.rb

@@ -0,0 +1,51 @@
+require File.dirname(__FILE__) + "/../spec/common"
+
+#
+# This is a bad example because a handler should re-raise if no
+# restart is provided.  All bets are off if code directly after a
+# 'raise' gets executed.  But for fun let's see what it looks like.
+#
+
+include Cond
+
+module BadExample
+  A, B = (1..2).map { Class.new RuntimeError }
+
+  memo = []
+
+  describe "bad example" do
+    it "should demonstrate how not to use Cond" do
+      handling do
+        handle A do
+          memo.push :ignore_a
+        end
+        
+        handle B do
+          memo.push :reraise_b
+          raise
+        end
+
+        raise A
+        # ... still going!
+        
+        handling do
+          handle B do
+            memo.push :ignore_b
+          end
+          raise B
+          # ... !
+        end
+
+        begin
+          raise B, "should not be ignored"
+        rescue B => e
+          if e.message == "should not be ignored"
+            memo.push :rescued_b
+          end
+        end
+      end
+      memo.should == [:ignore_a, :ignore_b, :reraise_b, :rescued_b]
+    end
+  end
+end
+

data/examples/calc_example.rb

@@ -0,0 +1,84 @@
+require File.dirname(__FILE__) + "/../spec/common"
+
+include Cond
+
+class DivergedError < StandardError
+  attr_reader :epsilon
+
+  def initialize(epsilon)
+    super()
+    @epsilon = epsilon
+  end
+
+  def message
+    "Failed to converge with epsilon #{@epsilon}"
+  end
+end
+
+def calc(x, y, epsilon)
+  restartable do
+    restart :change_epsilon do |new_epsilon|
+      epsilon = new_epsilon
+      again
+    end
+    restart :give_up do
+      leave
+    end
+    # ...
+    # ... some calculation
+    # ...
+    if epsilon < 0.01
+      raise DivergedError.new(epsilon)
+    end
+    42
+  end
+end
+
+describe "A calculation which can raise a divergent error," do
+  describe "with a handler which increases epsilon" do
+    before :all do
+      handling do
+        @memo = []
+        @result = nil
+        epsilon = 0.0005
+        handle DivergedError do
+          epsilon += 0.001
+          @memo.push :increase
+          invoke_restart :change_epsilon, epsilon
+        end
+        @result = calc(3, 4, epsilon)
+      end
+    end
+
+    it "should converge after repeated epsilon increases" do
+      @memo.should == (1..10).map { :increase }
+    end
+
+    it "should obtain a result" do
+      @result.should == 42
+    end
+  end
+
+  describe "with a give-up handler and a too-small epsilon" do
+    before :all do
+      handling do
+        @result = 9999
+        @memo = []
+        epsilon = 1e-10
+        handle DivergedError do
+          @memo.push :give_up
+          invoke_restart :give_up
+        end
+        @result = calc(3, 4, epsilon)
+      end
+    end
+
+    it "should give up" do
+      @memo.should == [:give_up]
+    end
+
+    it "should obtain a nil result" do
+      @result.should == nil
+    end
+  end
+end

data/examples/readme_example.rb

@@ -0,0 +1,27 @@
+require File.dirname(__FILE__) + "/../spec/common"
+
+require 'quix/ruby'
+
+root = Pathname(__FILE__).dirname + ".."
+file = root + "README"
+lib = root + "lib"
+
+describe file do
+  ["Synopsis",
+   "Raw Form",
+   "Synopsis 2.0",
+  ].each { |section|
+    it "#{section} should run as claimed" do
+      contents = file.read
+
+      code = %{
+        $LOAD_PATH.unshift "#{lib.expand_path}"
+        require 'cond'
+        include Cond
+      } + contents.match(%r!== #{section}.*?\n(.*?)^\S!m)[1]
+
+      expected = code.scan(%r!\# => (.*?)\n!).flatten.join("\n")
+      pipe_to_ruby(code).chomp.should == expected
+    end
+  }
+end

data/examples/restarts_example.rb

@@ -0,0 +1,26 @@
+here = File.dirname(__FILE__)
+require here + "/../spec/common"
+
+RESTARTS_FILE = here + "/../readmes/restarts.rb"
+
+def run_restarts(input_string)
+  capture(input_string) {
+    load RESTARTS_FILE
+  }
+end
+
+describe RESTARTS_FILE do
+  it "should fetch with with alternate hash" do
+    hash = { "mango" => "mangoish fruit" }
+    re = %r!#{hash.values.first}!
+    run_restarts(%{2\n#{hash.inspect}\n}).should match(re)
+  end
+
+  it "should fetch with alternate value" do
+    class Cond::Restart
+      # coverage hack
+      undef :message
+    end
+    run_restarts(%{3\n"apple"\n}).should match(%r!value: "fruit"!)
+  end
+end

data/examples/seibel_example.rb

@@ -0,0 +1,18 @@
+here = File.dirname(__FILE__)
+require here + "/../spec/common"
+
+seibel_file = here + "/../readmes/seibel_pcl.rb"
+
+include Cond
+
+if RUBY_VERSION > "1.8.6"
+  describe seibel_file do
+    it "should run" do
+      lambda {
+        capture("0\n") {
+          load seibel_file
+        }
+      }.should_not raise_error
+    end
+  end
+end

data/install.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift "./support"
+require 'quix/simple_installer'
+Quix::SimpleInstaller.new.run

data/lib/cond.rb

@@ -0,0 +1,456 @@
+
+require 'cond/cond_private/thread_local'
+require 'cond/cond_private/symbol_generator'
+require 'cond/cond_private/defaults'
+
+# 
+# Resolve errors without unwinding the stack.
+# 
+module Cond
+  module CondPrivate
+    class MessageProc < Proc
+      def initialize(message = "", &block)
+        @message = message
+      end
+      
+      def message
+        @message
+      end
+    end
+  end
+
+  #
+  # A restart.  Use of this class is optional: you could pass lambdas
+  # to Cond.with_restarts, but you'll miss the description string
+  # shown inside Cond.default_handler.
+  #
+  class Restart < CondPrivate::MessageProc
+  end
+
+  #
+  # A handler.  Use of this class is optional: you could pass lambdas
+  # to Cond.with_handlers, but you'll miss the description string
+  # shown by whichever tools might use it (currently none).
+  #
+  class Handler < CondPrivate::MessageProc
+  end
+
+  ######################################################################
+  # errors
+  
+  #
+  # Cond.invoke_restart was called with an unknown restart.
+  #
+  class NoRestartError < StandardError
+  end
+
+  #
+  # `handle', `restart', `leave', or `again' called out of context.
+  #
+  class ContextError < StandardError
+  end
+
+  ######################################################################
+  # singleton methods
+
+  class << self
+    #
+    # Register a set of handlers.  The given hash is merged with the
+    # set of current handlers.
+    #
+    # When the block exits, the previous set of handlers (if any) are
+    # restored.
+    #
+    def with_handlers(handlers)
+      # note: leave unfactored due to notable yield vs &block performance
+      handlers_stack.push(handlers_stack.last.merge(handlers))
+      begin
+        yield
+      ensure
+        handlers_stack.pop
+      end
+    end
+    
+    #
+    # Register a set of restarts.  The given hash is merged with the
+    # set of current restarts.
+    #
+    # When the block exits, the previous set of restarts (if any) are
+    # restored.
+    #
+    def with_restarts(restarts)
+      # note: leave unfactored due to notable yield vs &block performance
+      restarts_stack.push(restarts_stack.last.merge(restarts))
+      begin
+        yield
+      ensure
+        restarts_stack.pop
+      end
+    end
+      
+    #
+    # A default handler is provided which runs a simple
+    # choose-a-restart input loop when +raise+ is called.
+    #
+    def with_default_handlers
+      # note: leave unfactored due to notable yield vs &block performance
+      with_handlers(defaults.handlers) {
+        yield
+      }
+    end
+  
+    #
+    # The current set of restarts which have been registered.
+    #
+    def available_restarts
+      restarts_stack.last
+    end
+      
+    #
+    # Find the closest-matching handler for the given Exception.
+    #
+    def find_handler(target)  #:nodoc:
+      find_handler_from(handlers_stack.last, target)
+    end
+
+    def find_handler_from(handlers, target)  #:nodoc:
+      handlers.fetch(target) {
+        found = handlers.inject(Array.new) { |acc, (klass, func)|
+          index = target.ancestors.index(klass)
+          if index
+            acc << [index, func]
+          else
+            acc
+          end
+        }.sort_by { |t| t.first }.first
+        found and found[1]
+      }
+    end
+  
+    def run_code_section(klass, &block) #:nodoc:
+      section = klass.new(&block)
+      Cond.code_section_stack.push(section)
+      begin
+        section.instance_eval { run }
+      ensure
+        Cond.code_section_stack.pop
+      end
+    end
+
+    def check_context(keyword)  #:nodoc:
+      section = Cond.code_section_stack.last
+      case keyword
+      when :restart
+        unless section.is_a? CondPrivate::RestartableSection
+          Cond.original_raise(
+            ContextError,
+            "`#{keyword}' called outside of `restartable' block"
+          )
+        end
+      when :handle
+        unless section.is_a? CondPrivate::HandlingSection
+          Cond.original_raise(
+            ContextError,
+            "`#{keyword}' called outside of `handling' block"
+          )
+        end
+      when :leave, :again
+        unless section
+          Cond.original_raise(
+            ContextError,
+            "`#{keyword}' called outside of `handling' or `restartable' block"
+          )
+        end
+      end
+    end
+
+    ###############################################
+    # wrapping
+  
+    #
+    # Allow handlers to be called from C code by wrapping a method with
+    # begin/rescue.  Returns the aliased name of the original method.
+    #
+    # See the README.
+    #
+    # Example:
+    #
+    #   Cond.wrap_instance_method(Fixnum, :/)
+    #
+    def wrap_instance_method(mod, method)
+      original = "cond_original_#{mod.inspect}_#{method.inspect}"
+      # TODO: jettison 1.8.6, remove eval and use |&block|
+      # TODO: fix rcov bug -- does not see %{}
+      mod.module_eval <<-eval_end
+        alias_method :'#{original}', :'#{method}'
+        def #{method}(*args, &block)
+          begin
+            send(:'#{original}', *args, &block)
+          rescue Exception => e
+            raise e
+          end
+        end
+      eval_end
+      original
+    end
+  
+    #
+    # Allow handlers to be called from C code by wrapping a method with
+    # begin/rescue.  Returns the aliased name of the original method.
+    #
+    # See the README.
+    #
+    # Example:
+    #
+    #   Cond.wrap_singleton_method(IO, :read)
+    #
+    def wrap_singleton_method(mod, method)
+      singleton_class = class << mod ; self ; end
+      wrap_instance_method(singleton_class, method)
+    end
+  
+    ###############################################
+    # original raise
+    
+    define_method :original_raise, Kernel.instance_method(:raise)
+
+    ######################################################################
+    # data -- all data is per-thread and fetched from the singleton class
+    #
+    # Cond.defaults contains the default handlers.  To replace it,
+    # call
+    #
+    #   Cond.defaults.clear(&block)
+    #
+    # where &block creates a new instance of your class which
+    # implements the method 'handlers'.
+    #
+    # Note that &block should return a brand new instance.  Otherwise
+    # the returned object will be shared across threads.
+    #
+
+    stack_0  = lambda { Array.new }
+    stack_1  = lambda { Array.new.push(Hash.new) }
+    defaults = lambda { CondPrivate::Defaults.new }
+    {
+      :code_section_stack => stack_0,
+      :exception_stack    => stack_0,
+      :handlers_stack     => stack_1,
+      :restarts_stack     => stack_1,
+      :defaults           => defaults,
+    }.each_pair { |name, create|
+      include CondPrivate::ThreadLocal.reader_module(name) {
+        create.call
+      }
+    }
+
+    include CondPrivate::ThreadLocal.accessor_module(:reraise_count) { 0 }
+  end
+
+  ######################################################################
+  
+  module CondPrivate
+    class CodeSection  #:nodoc:
+      include SymbolGenerator
+      
+      def initialize(with, &block)
+        @with = with
+        @block = block
+        @again_args = []
+        @leave, @again = gensym, gensym
+        SymbolGenerator.track(self, [@leave, @again])
+      end
+
+      def again(*args)
+        @again_args = (
+          case args.size
+          when 0
+            []
+          when 1
+            args.first
+          else
+            args
+          end
+        )
+        throw @again
+      end
+
+      def leave(*args)
+        case args.size
+        when 0
+          throw @leave
+        when 1
+          throw @leave, args.first
+        else
+          throw @leave, args
+        end
+      end
+
+      def run
+        catch(@leave) {
+          while true
+            catch(@again) {
+              Cond.send(@with, Hash.new) {
+                throw @leave, @block.call(*@again_args)
+              }
+            }
+          end
+        }
+      end
+    end
+
+    class RestartableSection < CodeSection  #:nodoc:
+      def initialize(&block)
+        super(:with_restarts, &block)
+      end
+      
+      def restart(sym, message, &block)
+        Cond.restarts_stack.last[sym] = Restart.new(message, &block)
+      end
+    end
+
+    class HandlingSection < CodeSection  #:nodoc:
+      def initialize(&block)
+        super(:with_handlers, &block)
+      end
+      
+      def handle(sym, message, &block)
+        Cond.handlers_stack.last[sym] = Handler.new(message, &block)
+      end
+    end
+  end
+
+  ######################################################################
+  # shiny exterior
+
+  module_function
+
+  #
+  # Begin a handling block.  Inside this block, a matching handler
+  # gets called when +raise+ gets called.
+  #
+  def handling(&block)
+    Cond.run_code_section(CondPrivate::HandlingSection, &block)
+  end
+
+  #
+  # Begin a restartable block.  A handler may transfer control to one
+  # of the restarts in this block.
+  #
+  def restartable(&block)
+    Cond.run_code_section(CondPrivate::RestartableSection, &block)
+  end
+  
+  #
+  # Define a handler.
+  #
+  # The exception instance is passed to the block.
+  #
+  def handle(arg, message = "", &block)
+    Cond.check_context(:handle)
+    Cond.code_section_stack.last.handle(arg, message, &block)
+  end
+
+  #
+  # Define a restart.
+  #
+  # When a handler calls invoke_restart, it may pass additional
+  # arguments which are in turn passed to &block.
+  #
+  def restart(arg, message = "", &block)
+    Cond.check_context(:restart)
+    Cond.code_section_stack.last.restart(arg, message, &block)
+  end
+
+  #
+  # Leave the current handling or restartable block, optionally
+  # providing a value for the block.
+  #
+  # The semantics are the same as 'return'.  When given multiple
+  # arguments, it returns an array.  When given one argument, it
+  # returns only that argument (not an array).
+  #
+  def leave(*args)
+    Cond.check_context(:leave)
+    Cond.code_section_stack.last.leave(*args)
+  end
+
+  #
+  # Run the handling or restartable block again.
+  #
+  # Optionally pass arguments which are given to the block.
+  #
+  def again(*args)
+    Cond.check_context(:again)
+    Cond.code_section_stack.last.again(*args)
+  end
+
+  #
+  # Call a restart from a handler; optionally pass it some arguments.
+  #
+  def invoke_restart(name, *args, &block)
+    Cond.available_restarts.fetch(name) {
+      raise NoRestartError,
+        "Did not find `#{name.inspect}' in available restarts"
+    }.call(*args, &block)
+  end
+end
+
+module Kernel
+  remove_method :raise
+  def raise(*args)
+    if Cond.handlers_stack.last.empty?
+      # not using Cond
+      Cond.original_raise(*args)
+    else
+      last_exception, current_handler = Cond.exception_stack.last
+      exception = (
+        if last_exception and args.empty?
+          last_exception
+        else
+          begin
+            Cond.original_raise(*args)
+          rescue Exception => e
+            e
+          end
+        end
+      )
+      if current_handler
+        # inside a handler
+        handler = loop {
+          Cond.reraise_count += 1
+          handlers = Cond.handlers_stack[-1 - Cond.reraise_count]
+          if handlers.nil?
+            break nil
+          end
+          found = Cond.find_handler_from(handlers, exception.class)
+          if found and found != current_handler
+            break found
+          end
+        }
+        if handler
+          handler.call(exception)
+        else
+          Cond.reraise_count = 0
+          Cond.original_raise(exception)
+        end
+      else
+        # not inside a handler
+        Cond.reraise_count = 0
+        handler = Cond.find_handler(exception.class)
+        if handler
+          Cond.exception_stack.push([exception, handler])
+          begin
+            handler.call(exception)
+          ensure
+            Cond.exception_stack.pop
+          end
+        else
+          Cond.original_raise(exception)
+        end
+      end
+    end
+  end
+  remove_method :fail
+  alias_method :fail, :raise
+end