класс Exception

Родитель:: Объект

Потомки класса Исключение используются для обмена сообщениями между Kernel#raise и rescue операторами в begin ... end блоках. Объекты Исключение содержат информацию об исключении — его тип (имя класса исключения), необязательную описательную строку и необязательную информацию о стеке вызовов. Подклассы Исключение могут добавлять дополнительную информацию, например NameError#name.

Программы могут создавать подклассы Исключение, обычно StandardError или RuntimeError, чтобы предоставить пользовательские классы и добавить дополнительную информацию. См. список подклассов ниже для значений по умолчанию для raise и rescue.

Когда исключение было вызвано, но еще не обработано (в rescue, ensure, at_exit и END блоках), глобальная переменная $! будет содержать текущее исключение, а $@ содержит трассировку текущего исключения.

Рекомендуется, чтобы библиотека имела один подкласс StandardError или RuntimeError и имела специфические типы исключений, наследующиеся от него. Это позволяет пользователю перехватывать общий тип исключения, чтобы поймать все исключения, которые может генерировать библиотека, даже если будущие версии библиотеки добавят новые подклассы исключений.

Например:

class MyLibrary
  class Error < RuntimeError
  end

  class WidgetError < Error
  end

  class FrobError < Error
  end

end

Для обработки как WidgetError, так и FrobError пользователь библиотеки может перехватить MyLibrary::Error.

Встроенные подклассы Исключение:

NoMemoryError
ScriptError
SecurityError
SignalException
- Interrupt
StandardError — значение по умолчанию для rescue
- ArgumentError
  - UncaughtThrowError
- EncodingError
- FiberError
- IOError
  - EOFError
- IndexError
  - KeyError
  - StopIteration
- LocalJumpError
- NameError
  - NoMethodError
- RangeError
  - FloatDomainError
- RegexpError
- RuntimeError — значение по умолчанию для raise
- SystemCallError
  - Errno::*
- ThreadError
- TypeError
- ZeroDivisionError
SystemExit
SystemStackError
fatal — невозможно перехватить

Публичные методы класса

exception(string) → an_exception or exc

Без аргумента или если аргумент совпадает с получателем, вернуть получателя. В противном случае создать новый объект исключения того же класса, что и получатель, но с сообщением равным string.to_str.

json_create(object) Показать исходный код

# File ext/json/lib/json/add/exception.rb, line 9
def self.json_create(object)
  result = new(object['m'])
  result.set_backtrace object['b']
  result
end

Десериализует строку JSON, создавая новый объект Исключение с сообщением m и трассировкой b, сериализованной с помощью to_json

new(msg = nil) → exception Показать исходный код

static VALUE
exc_initialize(int argc, VALUE *argv, VALUE exc)
{
    VALUE arg;

    rb_scan_args(argc, argv, "01", &arg);
    rb_iv_set(exc, "mesg", arg);
    rb_iv_set(exc, "bt", Qnil);

    return exc;
}

Создать новый объект Исключение, необязательно передав сообщение.

Методы публичного экземпляра

exc == obj → true или false Показать исходный код

static VALUE
exc_equal(VALUE exc, VALUE obj)
{
    VALUE mesg, backtrace;
    const ID id_mesg = idMesg;

    if (exc == obj) return Qtrue;

    if (rb_obj_class(exc) != rb_obj_class(obj)) {
        int status = 0;
        ID id_message, id_backtrace;
        CONST_ID(id_message, "message");
        CONST_ID(id_backtrace, "backtrace");

        obj = rb_protect(try_convert_to_exception, obj, &status);
        if (status || obj == Qundef) {
            rb_set_errinfo(Qnil);
            return Qfalse;
        }
        if (rb_obj_class(exc) != rb_obj_class(obj)) return Qfalse;
        mesg = rb_check_funcall(obj, id_message, 0, 0);
        if (mesg == Qundef) return Qfalse;
        backtrace = rb_check_funcall(obj, id_backtrace, 0, 0);
        if (backtrace == Qundef) return Qfalse;
    }
    else {
        mesg = rb_attr_get(obj, id_mesg);
        backtrace = exc_backtrace(obj);
    }

    if (!rb_equal(rb_attr_get(exc, id_mesg), mesg))
        return Qfalse;
    if (!rb_equal(exc_backtrace(exc), backtrace))
        return Qfalse;
    return Qtrue;
}

Равенство — Если obj не является Exception, возвращает false. В противном случае возвращает true, если exc и obj имеют одинаковый класс, сообщения и стек вызовов.

as_json(*) Показать исходный код

# File ext/json/lib/json/add/exception.rb, line 17
def as_json(*)
  {
    JSON.create_id => self.class.name,
    'm'            => message,
    'b'            => backtrace,
  }
end

Возвращает хеш, который будет преобразован в объект JSON и представит этот объект.

backtrace → массив Показать исходный код

static VALUE
exc_backtrace(VALUE exc)
{
    ID bt;
    VALUE obj;

    CONST_ID(bt, "bt");
    obj = rb_attr_get(exc, bt);

    if (rb_backtrace_p(obj)) {
        obj = rb_backtrace_to_str_ary(obj);
        /* rb_iv_set(exc, "bt", obj); */
    }

    return obj;
}

Возвращает любой стек вызовов, связанный с исключением. Стек вызовов — это массив строк, каждая из которых содержит либо «имя_файла:номер_строки: в `метод''' или «имя_файла:номер_строки.'»

def a
  raise "boom"
end

def b
  a()
end

begin
  b()
rescue => detail
  print detail.backtrace.join("\n")
end

возвращает:

prog.rb:2:in `a'
prog.rb:6:in `b'
prog.rb:10

backtrace_locations → массив Показать исходный код

static VALUE
exc_backtrace_locations(VALUE exc)
{
    ID bt_locations;
    VALUE obj;

    CONST_ID(bt_locations, "bt_locations");
    obj = rb_attr_get(exc, bt_locations);
    if (!NIL_P(obj)) {
        obj = rb_backtrace_to_location_ary(obj);
    }
    return obj;
}

Возвращает любой стек вызовов, связанный с исключением. Этот метод похож на #backtrace, но стек вызовов является массивом

Thread::Backtrace::Location.

Теперь этот метод не зависит от #set_backtrace.

cause → исключение или nil Показать исходный код

VALUE
exc_cause(VALUE exc)
{
    ID id_cause;
    CONST_ID(id_cause, "cause");
    return rb_attr_get(exc, id_cause);
}

Возвращает предыдущее исключение ($!) в момент возникновения данного исключения. Это полезно для обертывания исключений и сохранения информации об исходном исключении.

exception(строка) → исключение или exc Показать исходный код

static VALUE
exc_exception(int argc, VALUE *argv, VALUE self)
{
    VALUE exc;

    if (argc == 0) return self;
    if (argc == 1 && self == argv[0]) return self;
    exc = rb_obj_clone(self);
    exc_initialize(argc, argv, exc);

    return exc;
}

Без аргумента или если аргумент совпадает с получателем, возвращает получатель. В противном случае создаёт новый объект исключения того же класса, что и получатель, но с сообщением, равным string.to_str.

inspect → строка Показать исходный код

static VALUE
exc_inspect(VALUE exc)
{
    VALUE str, klass;

    klass = CLASS_OF(exc);
    exc = rb_obj_as_string(exc);
    if (RSTRING_LEN(exc) == 0) {
        return rb_str_dup(rb_class_name(klass));
    }

    str = rb_str_buf_new2("#<");
    klass = rb_class_name(klass);
    rb_str_buf_append(str, klass);
    rb_str_buf_cat(str, ": ", 2);
    rb_str_buf_append(str, exc);
    rb_str_buf_cat(str, ">", 1);

    return str;
}

Возвращает имя класса и сообщение об этом исключении

message → строка Показать исходный код

static VALUE
exc_message(VALUE exc)
{
    return rb_funcall(exc, rb_intern("to_s"), 0, 0);
}

Возвращает результат вызова exception.to_s. Обычно это возвращает сообщение или имя исключения. Предоставление метода to_str означает, что исключения могут быть использованы там, где ожидаются строки.

set_backtrace(стек_вызовов) → массив Показать исходный код

static VALUE
exc_set_backtrace(VALUE exc, VALUE bt)
{
    return rb_iv_set(exc, "bt", rb_check_backtrace(bt));
}

Устанавливает информацию о стеке вызовов, связанную с exc. Стек вызовов должен быть массивом объектов String или одной строкой в формате, описанном в #backtrace.

to_json(*args) Показать исходный код

# File ext/json/lib/json/add/exception.rb, line 27
def to_json(*args)
  as_json.to_json(*args)
end

Сохраняет имя класса (Исключение) с сообщением m и массивом стека вызовов b в виде строки JSON

to_s → строка Показать исходный код

static VALUE
exc_to_s(VALUE exc)
{
    VALUE mesg = rb_attr_get(exc, rb_intern("mesg"));

    if (NIL_P(mesg)) return rb_class_name(CLASS_OF(exc));
    return rb_String(mesg);
}

Возвращает сообщение об исключении (или имя исключения, если сообщение не задано).

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.