Exception objects are instances of the Exception class or one of its subclasses. Numerous subclasses exist. These subclasses do not typically define new methods or new behavior, but they allow exceptions to be categorized by type. The class hierarchy is illustrated in Figure 5-5.

Object
 +--Exception
     +--NoMemoryError
     +--ScriptError
     |   +--LoadError
     |   +--NotImplementedError
     |   +--SyntaxError
     +--SecurityError         # Was a StandardError in 1.8
     +--SignalException
     |   +--Interrupt
     +--SystemExit
     +--SystemStackError      # Was a StandardError in 1.8
     +--StandardError
         +--ArgumentError
         +--FiberError        # New in 1.9
         +--IOError
         |   +--EOFError
         +--IndexError
         |   +--KeyError      # New in 1.9
         |   +--StopIteration # New in 1.9
         +--LocalJumpError
         +--NameError
         |   +--NoMethodError
         +--RangeError
         |   +--FloatDomainError
         +--RegexpError
         +--RuntimeError
         +--SystemCallError
         +--ThreadError
         +--TypeError
         +--ZeroDivisionError

You don’t need to be familiar with each of these exception subclasses. Their names tell you what they are used for. It is important to note that most of these subclasses extend a class known as StandardError. These are the “normal” exceptions that typical Ruby programs try to handle. The other exceptions represent lower-level, more serious, or less recoverable conditions, and normal Ruby programs do not typically attempt to handle them.

If you use ri to find documentation for these exception classes, you’ll find that most of them are undocumented. This is in part because most of them add no new methods to those defined by the base Exception class. The important thing to know about a given exception class is when it can be raised. This is typically documented by the methods that raise the exception rather than by the exception class itself.

filename : linenumber in methodname

class MyError < StandardError; end

The Kernel method raise raises an exception. fail is a synonym that is sometimes used when the expectation is that the exception will cause the program to exit. There are several ways to invoke raise:

The following code defines a simple method that raises an exception if invoked with a parameter whose value is invalid:

def factorial(n)                 # Define a factorial method with argument n
  raise "bad argument" if n < 1  # Raise an exception for bad n
  return 1 if n == 1             # factorial(1) is 1
  n * factorial(n-1)             # Compute other factorials recursively
end

This method invokes raise with a single string argument. These are some equivalent ways to raise the same exception:

raise RuntimeError, "bad argument" if n < 1
raise RuntimeError.new("bad argument") if n < 1
raise RuntimeError.exception("bad argument") if n < 1

In this example, an exception of class ArgumentError is probably more appropriate than RuntimeError:

raise ArgumentError if n < 1

And a more detailed error message would be helpful:

raise ArgumentError, "Expected argument >= 1. Got #{n}" if n < 1

The intent of the exception we’re raising here is to point out a problem with the invocation of the factorial method, not with the code inside the method. The exception raised by the code here will have a backtrace whose first element identifies where raise was called. The second element of the array will actually identify the code that called factorial with the bad argument. If we want to point directly to the problem code, we can provide a custom stack trace as the third argument to raise with the Kernel method caller:

if n < 1
  raise ArgumentError, "Expected argument >= 1. Got #{n}", caller
end

Note that the factorial method checks whether its argument is in the correct range, but it does not check whether it is of the right type. We might add more careful error-checking by adding the following as the first line of the method:

raise TypeError, "Integer argument expected" if not n.is_a? Integer

On the other hand, notice what happens if we pass a string argument to the factorial method as it is written above. Ruby compares the argument n to the integer 1 with the < operator. If the argument is a string, the comparison makes no sense, and it fails by raising a TypeError. If the argument is an instance of some class that does not define the < operator, then we get a NoMethodError instead.

The point here is that exceptions can occur even if we do not call raise in our own code. It is important, therefore, to know how to handle exceptions, even if we never raise them ourselves. Handling exceptions is covered in the next section.

raise is a Kernel method. A rescue clause, by contrast, is a fundamental part of the Ruby language. rescue is not a statement in its own right, but rather a clause that can be attached to other Ruby statements. Most commonly, a rescue clause is attached to a begin statement. The begin statement exists simply to delimit the block of code within which exceptions are to be handled. A begin statement with a rescue clause looks like this:

begin
  # Any number of Ruby statements go here.
  # Usually, they are executed without exceptions and
  # execution continues after the end statement.
rescue
  # This is the rescue clause; exception-handling code goes here.
  # If an exception is raised by the code above, or propagates up
  # from one of the methods called above, then execution jumps here.
end

require 'English'

rescue => ex

begin                                # Handle exceptions in this block
  x = factorial(-1)                  # Note illegal argument
rescue => ex                         # Store exception in variable ex
  puts "#{ex.class}: #{ex.message}"  # Handle exception by printing message
end                                  # End the begin/rescue block

rescue Exception

rescue ArgumentError => e

rescue ArgumentError, TypeError => error

begin
  x = factorial(1)
rescue ArgumentError => ex
  puts "Try again with a value >= 1"
rescue TypeError => ex
  puts "Try again with an integer"
end

def explode        # This method raises a RuntimeError 10% of the time
  raise "bam!" if rand(10) == 0
end

def risky   
  begin            # This block
    10.times do    # contains another block
      explode      # that might raise an exception.
    end            # No rescue clause here, so propagate out.
  rescue TypeError # This rescue clause cannot handle a RuntimeError..
    puts $!        # so skip it and propagate out.
  end              
  "hello"          # This is the normal return value, if no exception occurs.
end                # No rescue clause here, so propagate up to caller.

def defuse
  begin                     # The following code may fail with an exception.
    puts risky              # Try to invoke and print the return value.
  rescue RuntimeError => e  # If we get an exception
    puts e.message          # print the error message instead.
  end                       
end

defuse

require 'open-uri'

tries = 0       # How many times have we tried to read the URL
begin           # This is where a retry begins
  tries += 1    # Try to print out the contents of a URL
  open('http://www.example.com/') {|f| puts f.readlines }
rescue OpenURI::HTTPError => e  # If we get an HTTP error
  puts e.message                # Print the error message
  if (tries < 4)                # If we haven't tried 4 times yet...
    sleep(2**tries)             # Wait for 2, 4, or 8 seconds
    retry                       # And then try again!
  end
end

A begin statement may include an else clause after its rescue clauses. You might guess that the else clause is a catch-all rescue: that it handles any exception that does not match a previous rescue clause. This is not what else is for. The else clause is an alternative to the rescue clauses; it is used if none of the rescue clauses are needed. That is, the code in an else clause is executed if the code in the body of the begin statement runs to completion without exceptions.

Putting code in an else clause is a lot like simply tacking it on to the end of the begin clause. The only difference is that when you use an else clause, any exceptions raised by that clause are not handled by the rescue statements.

The use of an else clause is not particularly common in Ruby, but they can be stylistically useful to emphasize the difference between normal completion of a block of code and exceptional completion of a block of code.

Note that it does not make sense to use an else clause without one or more rescue clauses. The Ruby interpreter allows it but issues a warning. No rescue clause may appear after an else clause.

Finally, note that the code in an else clause is only executed if the code in the begin clause runs to completion and “falls off” the end. If an exception occurs, then the else clause will obviously not be executed. But break, return, next, and similar statements in the begin clause may also prevent the execution of the else clause.

A begin statement may have one final clause. The optional ensure clause, if it appears, must come after all rescue and else clauses. It may also be used by itself without any rescue or else clauses.

The ensure clause contains code that always runs, no matter what happens with the code following begin:

The purpose of the ensure clause is to ensure that housekeeping details such as closing files, disconnecting database connections, and committing or aborting transactions get taken care of. It is a powerful control structure, and you should use it whenever you allocate a resource (such as a file handle or database connection) to ensure that proper deallocation or cleanup occurs.

Note that ensure clauses complicate the propagation of exceptions. In our earlier explanation, we omitted any discussion of ensure clauses. When an exception propagates, it does not simply jump magically from the point where it is raised to the point where it is handled. There really is a propagation process. The Ruby interpreter searches out through containing blocks and up through the call stack. At each begin statement, it looks for a rescue clause that can handle the exception. And it looks for associated ensure clauses, and executes all of them that it passes through.

An ensure clause can cancel the propagation of an exception by initiating some other transfer of control. If an ensure clause raises a new exception, then that new exception propagates in place of the original. If an ensure clause includes a return statement, then exception propagation stops, and the containing method returns. Control statements such as break and next have similar effects: exception propagation is abandoned, and the specified control transfer takes place.

An ensure clause also complicates the idea of a method return value. Although ensure clauses are usually used to ensure that code will run even if an exception occurs, they also work to ensure that code will be run before a method returns. If the body of a begin statement includes a return statement, the code in the ensure clause will be run before the method can actually return to its caller. Furthermore, if an ensure clause contains a return statement of its own, it will change the return value of the method. The following code, for example, returns the value 2:

begin
  return 1     # Skip to the ensure clause before returning to caller
ensure
  return 2     # Replace the return value with this new value
end

Note that an ensure clause does not alter the return value of a method unless it explicitly uses a return statement. The following method, for example, returns 1, not 2:

def test
  begin return 1 ensure 2 end
end

If a begin statement does not propagate an exception, then the value of the statement is the value of the last expression evaluated in the begin, rescue, or else clauses. The code in the ensure clause is guaranteed to run, but it does not affect the value of the begin statement.

Throughout this discussion of exception handling, we have described the rescue, else, and ensure keywords as clauses of a begin statement. In fact, they can also be used as clauses of the def statement (defines a method), the class statement (defines a class), and the module statement (defines a module). Method definitions are covered in Chapter 6; class and module definitions are covered in Chapter 7.

The following code is a sketch of a method definition with rescue, else, and ensure clauses:

def method_name(x)
  # The body of the method goes here.
  # Usually, the method body runs to completion without exceptions
  # and returns to its caller normally.
rescue 
  # Exception-handling code goes here.
  # If an exception is raised within the body of the method, or if
  # one of the methods it calls raises an exception, then control
  # jumps to this block.
else
  # If no exceptions occur in the body of the method
  # then the code in this clause is executed.
ensure
  # The code in this clause is executed no matter what happens in the
  # body of the method. It is run if the method runs to completion, if 
  # it throws an exception, or if it executes a return statement.
end

In addition to its use as a clause, rescue can also be used as a statement modifier. Any statement can be followed by the keyword rescue and another statement. If the first statement raises an exception, the second statement is executed instead. For example:

# Compute factorial of x, or use 0 if the method raises an exception
y = factorial(x) rescue 0

This is equivalent to:

y = begin
      factorial(x)
    rescue
      0
    end

The advantage of the statement modifier syntax is that the begin and end keywords are not required. When used in this way, rescue must be used alone, with no exception class names and no variable name. A rescue modifier handles any StandardError exception but does not handle exceptions of other types. Unlike if and while modifiers, the rescue modifier has higher precedence (see Table 4-2 in the previous chapter) than assignment operators. This means that it applies only to the righthand side of an assignment (like the example above) rather than to the assignment expression as a whole.