class Exception (Ruby 3.0 リファレンスマニュアル)

要約

全ての例外の祖先のクラスです。

特異メソッド

new(error_message = nil) -> Exception[permalink][rdoc][edit]

exception(error_message = nil) -> Exception

例外オブジェクトを生成して返します。

[PARAM] error_message:: エラーメッセージを表す文字列を指定します。このメッセージは属性 Exception#message の値になり、デフォルトの例外ハンドラで表示されます。

例:

e = Exception.new("some message")
p e         # => #<Exception: some message>
p e.message # => "some message"

例:

e = Exception.exception("some message")
p e         # => #<Exception: some message>
p e.message # => "some message"

to_tty? -> bool[permalink][rdoc][edit]

$stderr が変更されておらず、$stderr.tty? が真の場合は true を返します。

[SEE_ALSO] Exception#full_message

インスタンスメソッド

self == other -> bool[permalink][rdoc][edit]

自身と指定された other のクラスが同じであり、 message と backtrace が == メソッドで比較して等しい場合に true を返します。そうでない場合に false を返します。

[PARAM] other:: 自身と比較したいオブジェクトを指定します。自身と異なるクラスのオブジェクトを指定した場合は Exception#exception を実行して変換を試みます。

例:

require "date"
def check_long_month(month)
  return if Date.new(2000, month, -1).day == 31
  raise "#{month} is not long month"
end

def get_exception
  return begin
    yield
  rescue => e
    e
  end
end

results = [2, 2, 4].map { |e | get_exception { check_long_month(e) } }
p results.map { |e| e.class }
# => [RuntimeError, RuntimeError, RuntimeError]
p results.map { |e| e.message }
# => ["2 is not long month", "2 is not long month", "4 is not long month"]

# class, message, backtrace が同一のため true になる
p results[0] == results[1]    # => true

# class, backtrace が同一だが、message がことなるため false になる
p results[0] == results[2]    # => false

backtrace -> [String][permalink][rdoc][edit]

バックトレース情報を返します。

デフォルトでは

"#{sourcefile}:#{sourceline}:in `#{method}'" (メソッド内の場合)
"#{sourcefile}:#{sourceline}" (トップレベルの場合)

という形式の String の配列です。

def methd
  raise
end

begin
  methd
rescue => e
  p e.backtrace
end

#=> ["filename.rb:2:in `methd'", "filename.rb:6"]

[SEE_ALSO] Exception#backtrace_locations

backtrace_locations -> [Thread::Backtrace::Location][permalink][rdoc][edit]

バックトレース情報を返します。Exception#backtraceに似ていますが、 Thread::Backtrace::Location の配列を返す点が異なります。

現状では Exception#set_backtrace によって戻り値が変化する事はありません。

例: test.rb

require "date"
def check_long_month(month)
  return if Date.new(2000, month, -1).day == 31
  raise "#{month} is not long month"
end

def get_exception
  return begin
    yield
  rescue => e
    e
  end
end

e = get_exception { check_long_month(2) }
p e.backtrace_locations
# => ["test.rb:4:in `check_long_month'", "test.rb:15:in `block in <main>'", "test.rb:9:in `get_exception'", "test.rb:15:in `<main>'"]

[SEE_ALSO] Exception#backtrace

cause -> Exception | nil[permalink][rdoc][edit]

self の前の例外(self が rescue 節や ensure 節の中で発生した例外の場合、その前に発生していた元々の例外)を返します。存在しない場合は nil を返します。

例:

begin
  begin
    raise "inner"
  rescue
    raise "outer"
  end
rescue
  p $!       # => #<RuntimeError: outer>
  p $!.cause # => #<RuntimeError: inner>
end

exception -> self[permalink][rdoc][edit]

exception(error_message) -> Exception

引数を指定しない場合は self を返します。引数を指定した場合自身のコピーを生成し Exception#message 属性を error_message にして返します。

Kernel.#raise は、実質的に、例外オブジェクトの exception メソッドの呼び出しです。

[PARAM] error_message:: エラーメッセージを表す文字列を指定します。

begin
 ...        # 何か処理
rescue => e
 raise e.exception("an error occurs during hogehoge process")  # 詳しいエラーメッセージ
end

full_message(highlight: true, order: :bottom) -> String[permalink][rdoc][edit]

例外の整形された文字列を返します。

返される文字列は Ruby が捕捉されなかった例外を標準エラー出力に出力するときと同じ形式です。そのため、メソッド呼び出し時に $stderr が変更されておらず、$stderr.tty? が真の場合はエスケープシーケンスによる文字装飾がついています。

[PARAM] highlight:: エスケープシーケンスによる文字装飾をつけるかどうかを指定します。デフォルト値は Exception.to_tty? の返り値と同じです。
[PARAM] order:: :top か :bottom で指定する必要があります。バックトレースの一番奥がエラーメッセージの上(top)か下(bottom)かを指定します。デフォルト値は Exception.to_tty? が真なら :bottom で偽なら :top です。

例

begin
  raise "test"
rescue => e
  p e.full_message   # => "\e[1mTraceback \e[m(most recent call last):\ntest.rb:2:in `<main>': \e[1mtest (\e[4;1mRuntimeError\e[m\e[1m)\n\e[m"
  $stderr = $stdout
  p e.full_message   # => "test.rb:2:in `<main>': test (RuntimeError)\n"
  $stderr = STDERR
  p e.full_message   # => "\e[1mTraceback \e[m(most recent call last):\ntest.rb:2:in `<main>': \e[1mtest (\e[4;1mRuntimeError\e[m\e[1m)\n\e[m"
end

[SEE_ALSO] Exception.to_tty?

inspect -> String[permalink][rdoc][edit]

self のクラス名と message を文字列にして返します。

例:

begin
  raise "exception"
rescue
  p $!.inspect # => "#<RuntimeError: exception>"
end

message -> String[permalink][rdoc][edit]

to_s -> String

エラーメッセージをあらわす文字列を返します。

begin
  1 + nil
rescue => e
  p e.message   #=>  "nil can't be coerced into Fixnum"
end

set_backtrace(errinfo) -> nil | String | [String][permalink][rdoc][edit]

バックトレース情報に errinfo を設定し、設定されたバックトレース情報を返します。

[PARAM] errinfo:: nil、String あるいは String の配列のいずれかを指定します。

例:

begin
  begin
    raise "inner"
  rescue
    raise "outer"
  end
rescue
  $!.backtrace # => ["/path/to/test.rb:5:in `rescue in <main>'", "/path/to/test.rb:2:in `<main>'"]
  $!.set_backtrace(["dummy1", "dummy2"])
  $!.backtrace # => ["dummy1", "dummy2"]
end

要約

目次

特異メソッド

インスタンスメソッド