Advanced Rescue & Raise

Much of the hidden power of Ruby's exception system is contained in the humble rescue and raise syntax. In this chapter I'm going to show you how to harness that power. If the beginning of the chapter is old-news to you, stick with it! By the end, we'll be covering new ground.

Full Rescue Syntax

Simple begin-rescue-end clauses work well for most cases. But occasionally you have a situation that requires a more sophisticated approach. Below is an example of Ruby's full rescue syntax.

begin
  ...
rescue TooHotError => too_hot
  # This code is run if a TooHotError occurs 
rescue TooColdError => too_cold
  # This code is run if a TooColdError occurs 
else
  # This code is run if no exception occurred at all
ensure
  # This code is always run, regardless of whether an exception occurred
end

As you can see we've introduced a few new keywords:

  • else - is executed when no exceptions occur at all.
  • ensure - is always executed, even if exceptions did occur. This is really useful for actions like closing files when something goes wrong.
  • rescue - you know what rescue, is, but I just wanted to point out that we're using multiple rescues to provide different behavior for different exceptions.

I find that the full rescue syntax is most useful when working with disk or network IO. For example, at Honeybadger we do uptime monitoring — requesting your web page every few minutes and letting you know when it's down. Our logic looks something like this:

begin
  request_web_page
rescue TimeoutError
  retry_request 
rescue 
  send_alert
else
  record_success
ensure
  close_network_connection
else

Here, we respond to timeout exceptions by retrying. All other exceptions trigger alerts. If no error occurred, we save the success in the database. Finally, regardless of what else occurred, we always close the network connection.

Method Rescue Syntax

If you find yourself wrapping an entire method in a rescue clause, Ruby provides an alternate syntax that is a bit prettier:

def my_method
  ...
rescue
  ...
else
  ...
ensure
  ...
end

This is particularly useful if you want to return a "fallback" value when an exception occurs. Here's an example:

def data
  JSON.parse(@input)
rescue JSON::JSONError
  {}
end

The retry Keyword

The retry keyword allows you to re-run everything between begin and rescue. This can be useful when you're working with things like flaky external APIs. The following example will try an api request three times before giving up.

counter = 0
begin
  counter += 1
  make_api_request
rescue
  retry if counter <= 3  
end

Ruby doesn't have a built-in mechanism to limit the number of retries. If you don't implement one yourself — like the counter variable in the above example — the result will be an infinite loop.

Reraising Exceptions

If you call raise with no arguments, while inside of a rescue block, Ruby will re-raise the original rescued exception.

begin
  ...
rescue => e
  raise if e.message == "Fubar"
end

To the outside world a re-raised exception is indistinguishable from the original.

Changing Exceptions

It's common to rescue one exception and raise another. For example, ActionView rescues all exceptions that occur in your ERB templates and re-raises them as ActionView::TemplateError exceptions.

begin
  render_template
rescue 
  raise ActionView::TemplateError
end

In older versions of Ruby (pre 2.1) the original exception was discarded when using this technique. Newer versions of Ruby make the original available to you via a nested exception system which we will cover in detail in Chapter 4.

Exception Matchers

In this book, you've seen several examples where we rescue a specific type of exception. Here's another one:

begin 
  ...
rescue StandardError
end   

This is good enough 99.99% of the time. But every so often you may find yourself needing to rescue exceptions based on something other than "type." Exception matchers give you this flexibility. When you define an exception matcher class, you can decide at runtime which exceptions should be rescued.

The following example shows you how to rescue all exceptions where the message begins with the string "FOOBAR".

class FoobarMatcher
  def self.===(exception)
    # rescue all exceptions with messages starting with FOOBAR 
    exception.message =~ /^FOOBAR/
  end
end

begin
  raise EOFError, "FOOBAR: there was an eof!"
rescue FoobarMatcher
  puts "rescued!"
end

The Mechanism

To understand how exception matcher classes work, you first need to understand how rescue decides which exceptions to rescue.

In the code below we've told Ruby to rescue a RuntimeError. But how does ruby know that a given exception is a RuntimeError?

begin 
  ...
rescue RuntimeError
end

You might think that Ruby simply checks the exception's class via is_a?:

exception.is_a?(RuntimeError)

But the reality is a little more interesting. Ruby uses the === operator. Ruby's triple-equals operator doesn't have anything to do with testing equality. Instead, a === b answers the question "is b inherently part of a?".

(1..100) === 3        # True
String === "hi"       # True
/abcd/ === "abcdefg"  # True

All classes come with a === method, which returns true if an object is an instance of said class.

def self.===(o)
  self.is_a?(o)
end

When we rescue RuntimeError ruby tests the exception object like so:

RuntimeError === exception

Because === is a normal method, we can implement our own version of it. This means we can easily create custom "matchers" for our rescue clauses.

Let's write a matcher that matches every exception:

class AnythingMatcher
  def self.===(exception)
    true
  end
end

begin 
  ...
rescue AnythingMatcher
end

By using === the Ruby core team has made it easy and safe to override the default behavior. If they had used is_a?, creating exception matchers would be much more difficult and dangerous.

Syntactic Sugar

This being Ruby, it's possible to create a much prettier way to dynamically catch exceptions. Instead of manually creating matcher classes, we can write a method that does it for us:

def exceptions_matching(&block)
  Class.new do
    def self.===(other)
      @block.call(other)
    end
  end.tap do |c|
    c.instance_variable_set(:@block, block)
  end
end

begin
  raise "FOOBAR: We're all doomed!"
rescue exceptions_matching { |e| e.message =~ /^FOOBAR/ }
  puts "rescued!"
end

Advanced Raise

In Chapter 1 we covered a few of the ways you can call raise. For example each of the following lines will raise a RuntimeError.

raise
raise "hello"
raise RuntimeError, "hello"
raise RuntimeError.new("hello")

If you look at the Ruby documentation for the raise method, you'll see something weird. The final variant — my personal favorite — isn't explicitly mentioned.

raise RuntimeError.new("hello")

To understand why, let's look at a few sentences of the documentation:

With a single String argument, raises a RuntimeError with the string as a message. Otherwise, the first parameter should be the name of an Exception class (or an object that returns an Exception object when sent an exception message).

The important bit is at the very end: "or an object that returns an Exception object when sent an exception message."

This means that if raise doesn't know what to do with the argument you give it, it'll try to call the exception method of that object. If it returns an exception object, then that's what will be raised.

And all exception objects have a method exception which by default returns self.

e = Exception.new
e.eql? e.exception # True

Raising Non-Exceptions

If we provide an exception method, any object can be raised as an exception.

Imagine you have a class called HTMLSafeString which contains a string of text. You might want to make it possible to pass one of these "safe" strings to raise just like a normal string. To do this we simply add an exception method that creates a new RuntimeError.

class HTMLSafeString
  def initialize(value)
    @value = value
  end

  def exception
    RuntimeError.new(@value)
  end
end

raise HTMLSafeString.new("helloworld")