Exception: Exception
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
ArgumentError, ClosedQueueError, EOFError, EncodingError, FiberError, FloatDomainError, IOError, IndexError, Interrupt, KeyError, LoadError, LocalJumpError, NameError, NoMemoryError, NoMethodError, NotImplementedError, RangeError, RegexpError, RuntimeError, ScriptError, SecurityError, SignalException, StandardError, StopIteration, SyntaxError, SystemCallError, SystemExit, SystemStackError, ThreadError, TypeError, UncaughtThrowError, ZeroDivisionError, fatal, Encoding::CompatibilityError, Encoding::ConverterNotFoundError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError, Math::DomainError
|
|
Inherits: | Object |
Defined in: | error.c |
Overview
Descendants of class Exception
are used to communicate between Kernel.raise and rescue
statements in begin ... end
blocks. Exception
objects carry information about the exception – its type (the exception's class name), an optional descriptive string, and optional traceback information. Exception
subclasses may add additional information like NameError#name.
Programs may make subclasses of Exception
, typically of ::StandardError or ::RuntimeError, to provide custom classes and add additional information. See the subclass list below for defaults for raise
and rescue
.
When an exception has been raised but not yet handled (in rescue
, ensure
, at_exit
and END
blocks) the global variable $!
will contain the current exception and $@
contains the current exception's backtrace.
It is recommended that a library should have one subclass of ::StandardError or ::RuntimeError and have specific exception types inherit from it. This allows the user to rescue a generic exception type to catch all exceptions the library may raise even if future versions of the library add new exception subclasses.
For example:
class MyLibrary
class Error < RuntimeError
end
class WidgetError < Error
end
class FrobError < Error
end
end
To handle both WidgetError and FrobError the library user can rescue MyLibrary::Error
.
The built-in subclasses of Exception
are:
-
-
LoadError
-
NotImplementedError
-
SyntaxError
-
-
-
Interrupt
-
-
::StandardError – default for
rescue
-
ArgumentError
-
UncaughtThrowError
-
-
EncodingError
-
FiberError
-
IOError
-
EOFError
-
-
IndexError
-
KeyError
-
StopIteration
-
-
LocalJumpError
-
NameError
-
NoMethodError
-
-
RangeError
-
FloatDomainError
-
-
RegexpError
-
RuntimeError – default for
raise
-
SystemCallError
-
Errno::*
-
-
ThreadError
-
TypeError
-
ZeroDivisionError
-
-
fatal – impossible to rescue
Class Method Summary
-
.exception(string) ⇒ Exception
With no argument, or if the argument is the same as the receiver, return the receiver.
-
.new(msg = nil) ⇒ Exception
constructor
Construct a new
Exception
object, optionally passing in a message.
Instance Method Summary
-
#==(obj) ⇒ Boolean
Equality—If obj is not an
Exception
, returnsfalse
. -
#backtrace ⇒ Array
Returns any backtrace associated with the exception.
-
#backtrace_locations ⇒ Array
Returns any backtrace associated with the exception.
-
#cause ⇒ Exception?
Returns the previous exception ($!) at the time this exception was raised.
-
#exception(string) ⇒ Exception
With no argument, or if the argument is the same as the receiver, return the receiver.
-
#inspect ⇒ String
Return this exception's class name and message.
-
#message ⇒ String
Returns the result of invoking
exception.to_s
. -
#set_backtrace(backtrace) ⇒ Array
Sets the backtrace information associated with
exc
. -
#to_s ⇒ String
Returns exception's message (or the name of the exception if no message is set).
Constructor Details
.new(msg = nil) ⇒ Exception
Construct a new Exception
object, optionally passing in a message.
Class Method Details
.exception(string) ⇒ Exception
With no argument, or if the argument is the same as the receiver, return the receiver. Otherwise, create a new exception object of the same class as the receiver, but with a message equal to string.to_str
.
Instance Method Details
#==(obj) ⇒ Boolean
Equality—If obj is not an Exception
, returns false
. Otherwise, returns true
if exc and obj share same class, messages, and backtrace.
#backtrace ⇒ Array
Returns any backtrace associated with the exception. The backtrace is an array of strings, each containing either “filename:lineNo: in `method''' or “filename:lineNo.''
def a
raise "boom"
end
def b
a()
end
begin
b()
rescue => detail
print detail.backtrace.join("\n")
end
produces:
prog.rb:2:in `a'
prog.rb:6:in `b'
prog.rb:10
#backtrace_locations ⇒ Array
Returns any backtrace associated with the exception. This method is similar to #backtrace, but the backtrace is an array of
Thread::Backtrace::Location.
Now, this method is not affected by Exception#set_backtrace().
#cause ⇒ Exception
?
Returns the previous exception ($!) at the time this exception was raised. This is useful for wrapping exceptions and retaining the original exception information.
#exception(string) ⇒ Exception
With no argument, or if the argument is the same as the receiver, return the receiver. Otherwise, create a new exception object of the same class as the receiver, but with a message equal to string.to_str
.
#inspect ⇒ String
Return this exception's class name and message
#message ⇒ String
Returns the result of invoking exception.to_s
. Normally this returns the exception's message or name. By supplying a to_str method, exceptions are agreeing to be used where Strings are expected.
#set_backtrace(backtrace) ⇒ Array
Sets the backtrace information associated with exc
. The #backtrace must be an array of ::String objects or a single ::String in the format described in #backtrace.
#to_s ⇒ String
Returns exception's message (or the name of the exception if no message is set).