Method: Kernel#raise

Defined in:

eval.c

#raise(exception, message = exception.to_s, backtrace = nil, cause: $!) ⇒ Object #raise(message = nil, cause: $!) ⇒ Object

Raises an exception; see Exceptions.

Argument exception sets the class of the new exception; it should be class Exception or one of its subclasses (most commonly, RuntimeError or StandardError), or an instance of one of those classes:

begin
  raise(StandardError)
rescue => x
  p x.class
end
# => StandardError

Argument message sets the stored message in the new exception, which may be retrieved by method Exception#message; the message must be a string-convertible object or nil:

begin
  raise(StandardError, 'Boom')
rescue => x
  p x.message
end
# => "Boom"

If argument message is not given, the message is the exception class name.

See Messages.

Argument backtrace might be used to modify the backtrace of the new exception, as reported by Exception#backtrace and Exception#backtrace_locations; the backtrace must be an array of Thread::Backtrace::Location, an array of strings, a single string, or nil.

Using the array of Thread::Backtrace::Location instances is the most consistent option and should be preferred when possible. The necessary value might be obtained from #caller_locations, or copied from Exception#backtrace_locations of another error:

begin
  do_some_work()
rescue ZeroDivisionError => ex
  raise(LogicalError, "You have an error in your math", ex.backtrace_locations)
end

The ways, both Exception#backtrace and Exception#backtrace_locations of the raised error are set to the same backtrace.

When the desired stack of locations is not available and should be constructed from scratch, an array of strings or a singular string can be used. In this case, only Exception#backtrace is set:

begin
  raise(StandardError, 'Boom', %w[dsl.rb:3 framework.rb:1])
rescue => ex
  p ex.backtrace
  # => ["dsl.rb:3", "framework.rb:1"]
  p ex.backtrace_locations
  # => nil
end

If argument backtrace is not given, the backtrace is set according to an array of Thread::Backtrace::Location objects, as derived from the call stack.

See Backtraces.

Keyword argument cause sets the stored cause in the new exception, which may be retrieved by method Exception#cause; the cause must be an exception object (Exception or one of its subclasses), or nil:

begin
  raise(StandardError, cause: RuntimeError.new)
rescue => x
  p x.cause
end
# => #<RuntimeError: RuntimeError>

If keyword argument cause is not given, the cause is the value of $!.

See Cause.

In the alternate calling sequence, where argument exception not given, raises a new exception of the class given by $!, or of class RuntimeError if $! is nil:

begin
  raise
rescue => x
  p x
end
# => RuntimeError

With argument exception not given, argument message and keyword argument cause may be given, but argument backtrace may not be given.

# File 'eval.c', line 857

static VALUE
f_raise(int c, VALUE *v, VALUE _)
{
    return rb_f_raise(c, v);
}