smoke_signals 0.9.0

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Jonathan Tran
+
+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.textile

@@ -0,0 +1,168 @@
+h1. SmokeSignals
+
+SmokeSignals is an implementation of Lisp-style conditions and restarts as a Ruby library.  Conditions and restarts make it easy to separate policy of error recovery from implementation of error recovery.  If you're unfamiliar with the concept, check out the chapter from "Practical Common Lisp":http://www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html.
+
+SmokeSignals is different because:
+
+* conditions are not errors (although they can be)
+* signaling a condition does not unravel the stack (although it can)
+* conditions can be handled multiple times at different levels of the call stack (or not at all)
+* restarts can be established at any level in the call stack, not just where the condition is signaled
+* implementation of signaling, handling, and restarting is completely hidden. (The only possible exception to this is a design decision which allows @ensure@ blocks to work, making this usable with real side-effectful programs.)
+
+h2. Requirements
+
+Ruby 1.8.7 or 1.9.  No other gem dependencies.
+
+h2. Installation
+
+<pre><code>gem install smoke_signals</code></pre>
+
+h2. Usage
+
+<pre><code>require 'smoke_signals'</code></pre>
+
+In a low-level function, signal a condition.
+
+<pre><code>def parse_entry(line)
+  SmokeSignals::Condition.new.signal! unless satisfies_preconditions?(line)
+  # Do actual parsing...
+end
+</code></pre>
+
+In a mid-level function, implement ways to recover from the condition.  This is the mechanism of recovery that is tied to the implementation of the mid-level function.
+
+<pre><code>def parse_log_file(filename)
+  File.open(filename) do |io|
+    io.lines.map {|line|
+      SmokeSignals.with_restarts(:ignore_entry => lambda { nil },
+                                 :use_value => lambda {|v| v } ) do
+        parse_entry(line)
+      end
+    }.compact
+  end
+end
+</code></pre>
+
+In a high-level function, handle the condition.  This sets the policy of recovery without being exposed to the underlying implementation of the mid-level function.
+
+<pre><code>def analyze_log_file(filename)
+  entries = SmokeSignals.handle(lambda {|c| c.restart(:ignore_entry) }) do
+    parse_log_file(filename)
+  end
+  # Do something interesting with entries...
+end
+</code></pre>
+
+Signaling a condition does not have to be fatal.
+
+<pre><code># If no handlers are set, this will do nothing.
+SmokeSignals::Condition.new.signal
+</code></pre>
+
+The bang flavor will raise unless it is rescued or restarted.
+
+<pre><code># This is a fatal signal.
+SmokeSignals::Condition.new.signal!
+</code></pre>
+
+Since you can handle signals multiple times by different handlers at multiple levels in the call stack, simply handling a fatal signal and returning normally is not enough.  You must either rescue it or restart it.
+
+Rescuing a condition is just like rescuing an exception with a @rescue@ block.  It returns the value from the entire @handle@ block.
+
+<pre><code>x = SmokeSignals.handle(lambda {|c| c.rescue(42) }) do
+  SmokeSignals::Condition.new.signal!
+end
+# x is 42
+</code></pre>
+
+If you were using exceptions, you might've done this...
+
+<pre><code>x = begin
+  raise 'foo'
+rescue
+  42
+end
+# x is 42
+</code></pre>
+
+You can limit which kinds of conditions you handle by passing a hash to @handle@.
+
+<pre><code>class MyCondition1 < SmokeSignals::Condition; end
+class MyCondition2 < SmokeSignals::Condition; end
+
+SmokeSignals.handle(MyCondition1 => lambda {|c| c.restart(:some_restart) },
+                    MyCondition2 => lambda {|c| c.restart(:another_restart) }) do
+  MyCondition1.new.signal if some_condition?
+  MyCondition2.new.signal if another_condition?
+end
+</code></pre>
+
+By default @MyCondition1 === condition that was signaled@ is used to determine whether a handler applies or not, kind of like a @case@.  You can change the default behavior by overriding @Condition#handle_by(handler)@.  Either return a @Proc@ to handle it or @nil@.
+
+You can handle a signal multiple times by returning normally from your handler.  Doing this you can, for example, observe the fact that a condition has been signaled without otherwise having any effect on control flow.
+
+<pre><code>SmokeSignals.handle(lambda {|c| puts 'this is run 2nd' }) do
+  SmokeSignals.handle(lambda {|c| puts 'this is run 1st' }) do
+    begin
+      SmokeSignals::Condition.new.signal
+      puts 'this is run 3rd because no handlers called rescue or restart'
+    end
+  end
+end
+</code></pre>
+
+In the case of an @ensure@ block, it is executed _after_ any handlers.  It must be executed afterwards because the whole point of signal handlers is that they are run _before_ the stack is unwound.  At that point, a signal handler may choose to rescue, restart, or return normally to allow other handlers to execute.  In contrast, by the time an exception is caught, rescuing is not an option; it's a necessity.
+
+<pre><code>SmokeSignals.handle(lambda {|c| puts 'this is run 2nd' }) do
+  SmokeSignals.handle(lambda {|c| puts 'this is run 1st' }) do
+    begin
+      SmokeSignals::Condition.new.signal
+      puts 'this is run 3rd because no handlers called rescue or restart'
+    ensure
+      puts 'this is run last'
+    end
+  end
+end
+</code></pre>
+
+@ensure@ blocks are executed after handlers, but they are executed _before_ restarts.  To see why this design decision was made, consider this example.
+
+<pre><code>def parse_file(filename)
+  SmokeSignals.with_restarts(:use_new_filename => lambda {|f| parse_file(f) }) do
+    file = nil
+    begin
+      file = File.open(filename)
+      if file.lines.first == '#!/keyword'
+        # Parse file
+      else
+        SmokeSignals::Condition.new.signal!
+      end
+    ensure
+      file.close if file
+    end
+  end
+end
+</code></pre>
+
+If this function were called and restarted many times, and the stack were not unwound before each restart, then you would have many files open at once.  This is why SmokeSignals unwinds the stack before executing restarts, meaning that @ensure@ blocks are run before restarts.
+
+h3. Is SmokeSignals a replacement for Ruby exceptions?
+
+Short answer: no, they're an extension.
+
+Long answer... As shown above, you can achieve all the functionality of exceptions with SmokeSignals.
+
+However, you're probably using some code that doesn't know about SmokeSignals and raises exceptions instead.  Setting a condition handler will not handle these raised exceptions.  They couldn't because in such a case, restarting would be impossible and rescuing would be a necessity.  By the time an exception is handled, the stack has already been unwound.
+
+h2. Thread Safety
+
+This library is thread-safe because each thread has its own handlers and restarts.  You cannot signal in one thread and handle it in another thread.
+
+h2. Running Tests
+
+<pre><code>rake test</code></pre>
+
+h2. Special Thanks
+
+This was inspired in part by "dynamic_vars":https://github.com/robdimarco/dynamic_vars, an implementation of thread-local dynamic bindings in Ruby!

data/Rakefile

@@ -0,0 +1,4 @@
+desc "Run all tests"
+task :test do
+  require File.expand_path(File.join(File.dirname(__FILE__), 'test', 'smoke_signals_test'))
+end

data/lib/smoke_signals.rb

@@ -0,0 +1,224 @@
+class SmokeSignals
+
+  # This is raised by Condition#signal! if no handler rescues or
+  # restarts.
+  class UnhandledSignalError < RuntimeError
+    attr_accessor :condition
+    def initialize(condition)
+      super('condition was not rescued or restarted by any handlers')
+      self.condition = condition
+    end
+  end
+
+  # This is raised when a signal handler attempts to execute a restart
+  # that has not been established.
+  class NoRestartError < RuntimeError
+    attr_accessor :restart_name
+    def initialize(restart_name)
+      super("no established restart with name: #{restart_name}")
+      self.restart_name = restart_name
+    end
+  end
+
+  # You should never rescue this exception or any of its subclasses in
+  # normal usage.  If you do, you should re-raise it.  It is raised to
+  # unwind the stack and allow +ensure+ blocks to execute as you would
+  # expect.  Normally, you should not be rescuing Exception, anyway,
+  # without re-raising it.  A bare +rescue+ clause only rescues
+  # StandardError, a subclass of Exception, which is probably what you
+  # want.
+  class StackUnwindException < Exception
+    attr_reader :nonce
+    def initialize(nonce)
+      super("This exception is an implementation detail of SmokeSignals.  If you're seeing this, either there is a bug in SmokeSignals or you are rescuing a #{self.class} when you shouldn't be.  If you rescue this, you should re-raise it.")
+      @nonce = nonce
+    end
+  end
+
+  # You should never rescue this exception.  See StackUnwindException.
+  class RescueException < StackUnwindException
+    attr_reader :return_value
+    def initialize(nonce, return_value)
+      super(nonce)
+      @return_value = return_value
+    end
+  end
+
+  # You should never rescue this exception.  See StackUnwindException.
+  class RestartException < StackUnwindException
+    attr_reader :restart_receiver, :restart_args
+    def initialize(nonce, restart_receiver, restart_args)
+      super(nonce)
+      @restart_receiver = restart_receiver
+      @restart_args = restart_args
+    end
+  end
+
+  class Extensible #:nodoc:
+    def metaclass
+      class << self; self; end
+    end
+  end
+
+  # This is the base class for all conditions.
+  class Condition
+
+    attr_accessor :nonce
+
+    # Signals this Condition.
+    def signal
+      SmokeSignals.signal(self, false)
+    end
+
+    # Signals this Condition.  If it is not rescued or restarted by a
+    # handler, UnhandledSignalError is raised.
+    def signal!
+      SmokeSignals.signal(self, true)
+    end
+
+    # This should only be called from within a signal handler.  It
+    # unwinds the stack to the point where SmokeSignals::handle was
+    # called and returns from SmokeSignals::handle with the given
+    # return value.
+    def rescue(return_value=nil)
+      raise RescueException.new(self.nonce, return_value)
+    end
+
+    # This should only be called from within a signal handler.  It
+    # unwinds the stack up to the point where
+    # SmokeSignals::with_restarts was called establishing the given
+    # restart, calls the restart with the given arguments, and returns
+    # the restart's return value from SmokeSignals::with_restarts.
+    def restart(name, *args)
+      SmokeSignals.restart(name, *args)
+    end
+
+    # When a Condition is signaled, this method is called by the
+    # internals of SmokeSignals to determine whether it should be
+    # handled by a given handler.
+    #
+    # If you override this method in subclasses of Condition, return a
+    # Proc taking the Condition as an argument that should be run to
+    # handle the signal.  Return nil to ignore the signal.
+    def handle_by(handler)
+      if handler.is_a?(Proc)
+        # No pattern given, so handler applies to everything.
+        handler
+      else
+        applies_to, handler_fn = handler
+        applies = case applies_to
+                  when Proc
+                    applies_to.call(self)
+                  when Array
+                    applies_to.any? {|a| a === self }
+                  else
+                    applies_to === self
+                  end
+        applies ? handler_fn : nil
+      end
+    end
+
+  end
+
+  class << self
+
+    # Establishes one or more signal handlers for the given block and
+    # executes it.  Returns either the return value of the block or
+    # the value passed to Condition#rescue in a handler.
+    def handle(*new_handlers, &block)
+      orig_handlers = handlers
+      nonce = Object.new
+      if new_handlers.last.is_a?(Hash)
+        new_handlers.pop.reverse_each {|entry| new_handlers.push(entry) }
+      end
+      self.handlers = orig_handlers + new_handlers.map {|entry| [entry,nonce] }.reverse
+      begin
+        block.call
+      rescue RescueException => e
+        if nonce.equal?(e.nonce)
+          e.return_value
+        else
+          raise e
+        end
+      ensure
+        self.handlers = orig_handlers
+      end
+    end
+
+    def signal(c, raise_unless_handled)
+      # Most recently set handlers are run first.
+      handlers.reverse_each do |handler, nonce|
+        # Check if the condition being signaled applies to this
+        # handler.
+        handler_fn = c.handle_by(handler)
+        next unless handler_fn
+
+        c.nonce = nonce
+        handler_fn.call(c)
+      end
+      raise UnhandledSignalError.new(c) if raise_unless_handled
+    end
+
+    # Establishes one or more restarts for the given block and
+    # executes it.  Returns either the return value of the block or
+    # that of the restart if one was run.
+    def with_restarts(extension, &block)
+      orig_restarts = restarts
+      nonce = Object.new
+      if extension.is_a?(Proc)
+        new_restarts = Extensible.new
+        new_restarts.metaclass.instance_eval { include Module.new(&extension) }
+      else
+        new_restarts = extension
+      end
+
+      self.restarts = orig_restarts + [[new_restarts,nonce]]
+      begin
+        block.call
+      rescue RestartException => e
+        if nonce.equal?(e.nonce)
+          e.restart_receiver.send(*e.restart_args)
+        else
+          raise e
+        end
+      ensure
+        self.restarts = orig_restarts
+      end
+    end
+
+    def restart(name, *args)
+      restarts.reverse_each do |restarts_obj, nonce|
+        obj, all_args = case restarts_obj
+                        when Extensible
+                          restarts_obj.respond_to?(name) ? [restarts_obj, [name] + args] : nil
+                        else
+                          fn = restarts_obj[name]
+                          fn ? [fn, [:call] + args] : nil
+                        end
+        next unless obj
+        raise RestartException.new(nonce, obj, all_args)
+      end
+      raise NoRestartError.new(name)
+    end
+
+    private
+
+    def handlers
+      Thread.current[:SmokeSignalsHandlers] ||= []
+    end
+
+    def handlers=(arr)
+      Thread.current[:SmokeSignalsHandlers] = arr
+    end
+
+    def restarts
+      Thread.current[:SmokeSignalsRestarts] ||= []
+    end
+
+    def restarts=(arr)
+      Thread.current[:SmokeSignalsRestarts] = arr
+    end
+
+  end
+
+end

data/smoke_signals.gemspec

@@ -0,0 +1,20 @@
+#!/usr/bin/env gem build
+require 'base64'
+
+Gem::Specification.new do |s|
+  s.name = "smoke_signals"
+  s.version = "0.9.0"
+  s.authors = ["Jonathan Tran"]
+  s.homepage = "http://github.com/jtran/smoke_signals"
+  s.summary = "Lisp-style conditions and restarts for Ruby"
+  s.description = "SmokeSignals makes it easy to separate policy of error recovery from implementation of error recovery."
+  s.email = Base64.decode64("anRyYW5AYWx1bW5pLmNtdS5lZHU=\n")
+  s.license = 'MIT'
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  # Ruby version
+  s.required_ruby_version = '>= 1.8.7'
+end

data/test/smoke_signals_test.rb

@@ -0,0 +1,212 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'test_helper'))
+
+class SmokeSignalsTest < Test::Unit::TestCase
+
+  S = SmokeSignals
+  C = SmokeSignals::Condition
+
+  def setup
+    # This prevents brokenness in one test from affecting others.
+    Thread.current[:SmokeSignalsHandlers] = nil
+    Thread.current[:SmokeSignalsRestarts] = nil
+  end
+
+  def test_unhandled_signal_is_ignored
+    C.new.signal
+  end
+
+  def test_unhandled_signal_raises_for_bang_version
+    assert_raise SmokeSignals::UnhandledSignalError do
+      C.new.signal!
+    end
+  end
+
+  def test_handle_condition
+    r = S.handle(lambda {|c| c.rescue(42) }) do
+      C.new.signal!
+    end
+    assert_equal 42, r
+    assert_equal [], S.class_eval { handlers }
+  end
+
+  def test_handle_condition_multiple_times
+    a = []
+    r = S.handle(lambda {|c| a << 8; c.rescue(42) }) do
+      S.handle(lambda {|c| a << 7 }) do
+        C.new.signal!
+      end
+    end
+    assert_equal 42, r
+    assert_equal [7, 8], a
+    assert_equal [], S.class_eval { handlers }
+  end
+
+  def test_unsignaled_handlers_do_not_run
+    a = []
+    r = S.handle(String => lambda {|c| a << 9; c.rescue(9) },
+                 C      => lambda {|c| a << 7 }) do
+      C.new.signal
+      42
+    end
+    assert_equal [7], a
+    assert_equal r, 42
+    assert_equal [], S.class_eval { handlers }
+  end
+
+  def test_unestablished_restart_raises
+    assert_raise SmokeSignals::NoRestartError do
+      S.handle(lambda {|c| c.restart(:some_restart_name) }) do
+        C.new.signal!
+      end
+    end
+  end
+
+  def test_restart_with_hash
+    r = S.handle(lambda {|c| c.restart(:use_square_of_value, 4) }) do
+      r2 = S.with_restarts(:use_square_of_value => lambda {|v| v * v }) do
+        C.new.signal!
+      end
+      assert_equal 16, r2
+      r2 + 1
+    end
+    assert_equal 17, r
+    assert_equal [], S.class_eval { handlers }
+    assert_equal [], S.class_eval { restarts }
+  end
+
+  def test_restart_with_proc
+    r = S.handle(lambda {|c| c.restart(:use_square_of_value, 4) }) do
+      r2 = S.with_restarts(proc {
+                             def use_square_of_value(v)
+                               v * v
+                             end
+
+                             def use_nil
+                               nil
+                             end
+                           }) do
+        C.new.signal!
+      end
+      assert_equal 16, r2
+      r2 + 1
+    end
+    assert_equal 17, r
+    assert_equal [], S.class_eval { handlers }
+    assert_equal [], S.class_eval { restarts }
+  end
+
+  def test_restart_multiple_times
+    a = [:use_square_of_value, :use_value]
+    b = []
+    a.each do |name|
+      S.handle(lambda {|c| c.restart(name, 4) }) do
+        r = S.with_restarts(:use_square_of_value => lambda {|v| v * v },
+                            :use_value           => lambda {|v| v }) do
+          C.new.signal!
+        end
+        b << r
+      end
+    end
+    assert_equal [16, 4], b
+    assert_equal [], S.class_eval { handlers }
+    assert_equal [], S.class_eval { restarts }
+  end
+
+  def test_rescuing_executes_ensure_block
+    a = []
+    file = nil
+    r = S.handle(lambda {|c| a << 7; c.rescue(42) }) do
+      begin
+        file = 'fake_file'
+        C.new.signal
+        fail 'should be handled with a rescue'
+      ensure
+        file = 'closed'
+      end
+    end
+    assert_equal 42, r
+    assert_equal 'closed', file
+  end
+
+  def test_restarting_executes_ensure_block
+    a = []
+    file = nil
+    r = S.handle(lambda {|c| c.restart(:use_value, 42) }) do
+      S.with_restarts(:use_value => lambda {|v| v }) do
+        begin
+          file = 'fake_file'
+          C.new.signal
+          fail 'should be handled with a restart'
+        ensure
+          file = 'closed'
+        end
+      end
+    end
+    assert_equal 42, r
+    assert_equal 'closed', file
+  end
+
+  def test_restarting_executes_ensure_block_before_restart
+    a = []
+    r = S.handle(lambda {|c| c.restart(:use_value, 42) }) do
+      S.with_restarts(:use_value => lambda {|v| a << 2; v }) do
+        begin
+          C.new.signal
+          fail 'should be handled with a restart'
+        ensure
+          a << 1
+        end
+      end
+    end
+    assert_equal 42, r
+    assert_equal [1, 2], a
+  end
+
+  def test_rescuing_from_nested_handlers
+    a = []
+    r = S.handle(C => lambda {|c| a << 3; c.rescue(42) }) do
+      S.handle(String => lambda {|c| a << 4; c.rescue(5) }) do
+        C.new.signal!
+      end
+      fail 'should be handled with a rescue'
+    end
+    assert_equal 42, r
+    assert_equal [3], a
+  end
+
+  def test_restarting_from_nested_restarts
+    a = []
+    r = S.handle(lambda {|c| a << 3; c.restart(:use_value, 42) }) do
+      r2 = S.with_restarts(:use_value => lambda {|v| a << 4; v }) do
+        S.with_restarts(:use_square_of_value => lambda {|v| a << 5; v * v }) do
+          C.new.signal!
+          fail 'should be handled with a restart'
+        end
+        fail 'should be handled with a restart'
+      end
+      assert_equal [3, 4], a
+      assert_equal 42, r2
+      a << 6
+      7
+    end
+    assert_equal [3, 4, 6], a
+    assert_equal 7, r
+  end
+
+  def test_handle_in_multiple_threads
+    S.handle(lambda {|c| 7 }) do
+      t = Thread.new { assert_equal [], S.class_eval { handlers } }
+      assert_equal 1, S.class_eval { handlers.size }
+      t.join
+    end
+  end
+
+  def test_restart_in_multiple_threads
+    S.with_restarts(:use_value => lambda {|v| v }) do
+      t = Thread.new { assert_equal [], S.class_eval { restarts } }
+      assert_equal 1, S.class_eval { restarts.size }
+      t.join
+    end
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'smoke_signals'
+require 'test/unit'

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: smoke_signals
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.9.0
+platform: ruby
+authors: 
+- Jonathan Tran
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-27 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: SmokeSignals makes it easy to separate policy of error recovery from implementation of error recovery.
+email: jtran@alumni.cmu.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE.txt
+- README.textile
+- Rakefile
+- lib/smoke_signals.rb
+- smoke_signals.gemspec
+- test/smoke_signals_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jtran/smoke_signals
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Lisp-style conditions and restarts for Ruby
+test_files: 
+- test/smoke_signals_test.rb
+- test/test_helper.rb