Resolve errors without unwinding the stack.

require 'cond/dsl'

def divide(x, y)
  restartable do
    restart :return_this_instead do |value|
      return value
    end
    raise ZeroDivisionError if y == 0
    x/y
  end
end

handling do
  handle ZeroDivisionError do
    invoke_restart :return_this_instead, 42
  end
  puts divide(10, 2)  # => 5
  puts divide(18, 3)  # => 6
  puts divide(4, 0)   # => 42
  puts divide(7, 0)   # => 42
end

% gem install cond

Or from inside an unpacked .tgz download, rake install / rake uninstall.

Cond allows errors to be handled near the place where they occur, before the stack unwinds. It offers several advantages over exceptions while peacefully coexisting with the standard exception behavior.

The system is divided into two parts: restarts and handlers. When raise is called and there is a matching handler for the error, the normal mechanism of unwinding the stack is suspended while the handler is called instead. At this time, the handler may invoke one of the available restarts.

(1) program start (stack begin) -->  
                                    |
                                    |
                                    |
                                    |<-- handler_a 
                                    |
   (2) handlers are set up -------> |<-- handler_b 
                                    |
                                    |<-- handler_c ----- 
                                    |       .           |
                                    |      /|\          |
                                    |       |           |
                                    |       |           | (5) handler 
                                    |       |           |     calls
                                    |       |           |     restart
                                    |       |           |
            --------->------------- | ------            |
           |                        |  (4) exception    |
           |                        |      sent to      |
           |                        |      handler      |
           |                        |                   |
           |                        |                   |
           |                        |<-- restart_x      |
           ^                        |                   |
                                    |<-- restart_y <---- 
 (3) raise called here here ------> |
                                     <-- restart_z

A handler may find a way to negate the problem and, by invoking a restart, allow execution to continue from a place proximal to where raise was called. Or a handler may choose to allow the exception to propagate in the usual unwinding fashion, as if the handler was never called.

Cond is 100% compatible with the built-in exception-handling system. We may imagine that Ruby had always had this handler restart functionality but nobody remembered to use it.

• Home: quix.github.com/cond

• Feature Requests, Bug Reports: github.com/quix/cond/issues

• Manual Download: github.com/quix/cond/archives/master

• Repository: github.com/quix/cond

Cond is stolen from the Common Lisp condition system.

Peter Seibel discusses the advantages of handlers and restarts in the following video. I have fast-forwarded to the most relevant part, though the whole talk is worthwhile.

video.google.com/videoplay?docid=448441135356213813#46m07s

The example he shows is taken from his book on Lisp,

www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html

See readmes/seibel_pcl.rb for a Ruby translation.

require 'cond/dsl'

x, y = 7, 0

handling do
  handle ZeroDivisionError do |exception|
    invoke_restart :return_this_instead, 42
  end

  result = restartable do
    restart :return_this_instead do |value|
      leave value
    end

    raise ZeroDivisionError if y == 0
    x/y
  end

  puts result  # => 42
end

leave acts like return for the current handling or restartable block. Its counterpart is again, which acts like redo for the current handling or restartable block. These blocks may be nested arbitrarily.

leave and again are for convenience only. They remove the need for repetitive catch blocks and prevent symbol collisions for nested catch labels.

A default handler is provided which runs a simple choose-a-restart input loop when raise is called.

require 'pp'
require 'cond/dsl'

class RestartableFetchError < RuntimeError
end

def read_new_value(what)
  print("Enter a new #{what}: ")
  eval($stdin.readline.chomp)
end

def restartable_fetch(hash, key, default = nil)
  restartable do
    restart :continue, "Return not having found the value." do
      return default
    end
    restart :try_again, "Try getting the key from the hash again." do
      again
    end
    restart :use_new_key, "Use a new key." do
      key = read_new_value("key")
      again
    end
    restart :use_new_hash, "Use a new hash." do
      hash = read_new_value("hash")
      again
    end
    hash.fetch(key) {
      raise RestartableFetchError,
        "Error getting #{key.inspect} from:\n#{hash.pretty_inspect}"
    }
  end
end

fruits_and_vegetables = Hash[*%w[
   apple fruit
   orange fruit
   lettuce vegetable
   tomato depends_on_who_you_ask
]]

Cond.with_default_handlers {
  puts("value: "   restartable_fetch(fruits_and_vegetables, "mango").inspect)
}

Run:

% ruby readmes/restarts.rb
readmes/restarts.rb:49:in `<main>'
Error getting "mango" from:
{"apple"=>"fruit",
 "orange"=>"fruit",
 "lettuce"=>"vegetable",
 "tomato"=>"depends_on_who_you_ask"}

  0: Return not having found the value. (:continue)
  1: Try getting the key from the hash again. (:try_again)
  2: Use a new hash. (:use_new_hash)
  3: Use a new key. (:use_new_key)
Choose number: 3
Enter a new key: "apple"
value: "fruit"

% ruby readmes/restarts.rb
readmes/restarts.rb:49:in `<main>'
Error getting "mango" from:
{"apple"=>"fruit",
 "orange"=>"fruit",
 "lettuce"=>"vegetable",
 "tomato"=>"depends_on_who_you_ask"}

  0: Return not having found the value. (:continue)
  1: Try getting the key from the hash again. (:try_again)
  2: Use a new hash. (:use_new_hash)
  3: Use a new key. (:use_new_key)
Choose number: 2
Enter a new hash: { "mango" => "mangoish fruit" }
value: "mangoish fruit"

Translated to Ruby from c2.com/cgi/wiki?LispRestartExample

Cond has been tested on MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2, and jruby-1.4.

Each thread keeps its own list of handlers, restarts, and other data. All operations are fully thread-safe.

Except for the redefinition raise, Cond does not silently modify any of the standard classes.

The essential implementation is small and simple: it consists of two per-thread stacks of hashes (handlers and restarts) with merge-push and pop operations.

The optional require 'cond/dsl' defines some pseudo-keywords in the global scope which comprise a DSL for the system. These methods are also available with require 'cond' through the Cond singleton (e.g. Cond.handling) or by including Cond::DSL into the class or module which uses them.

The DSL shown in the above examples is a thin layer concealing the underlying hashes. It is equivalent to the following raw form. You are free to use either form according to preference or circumstance.

require 'cond'

def divide(x, y)
  restarts = {
    :return_this_instead => lambda { |value|
      throw :leave, value
    }
  }
  catch :leave do
    Cond.with_restarts restarts do
      raise ZeroDivisionError if y == 0
      x/y
    end
  end
end

handlers = {
  ZeroDivisionError => lambda { |exception|
    Cond.invoke_restart :return_this_instead, 42
  }
}
Cond.with_handlers handlers do
  puts divide(10, 2)  # => 5
  puts divide(18, 3)  # => 6
  puts divide(4, 0)   # => 42
  puts divide(7, 0)   # => 42
end

There must be a call to raise inside Ruby code (as opposed to C code) in order for a handler to be invoked.

The above synopsis gives an example: Why is there a check for division by zero when ZeroDivisionError would be raised anyway? Because Fixnum#/ is written in C.

It is still possible for handlers to intercept these raises, but it requires redefining a wrapped version of the method in question:

Cond.wrap_instance_method(Fixnum, :/)

Once this has been called, the line

raise ZeroDivisionError if y == 0

is unnecessary.

It is possible remove this limitation by modifying the Ruby interpreter to call Kernel#raise dynamically.

• Documentation: cond.rubyforge.org

• Rubyforge home: rubyforge.org/projects/cond/

• Download: rubyforge.org/frs/?group_id=7916

• Repository: github.com/quix/cond/tree/master

• James M. Lawrence < [email protected] >

Copyright © 2009 James M. Lawrence. All rights reserved.

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.