autodie::exception

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПС
• ОПИСАНИЕ
  • Общие методы
    • args
    • function
    • file
    • package
    • caller
    • line
    • context
    • return
    • errno
    • eval_error
    • matches
  • Расширенные методы
    • register
    • add_file_and_line
    • stringify
    • format_default
    • new
• СМОТРИТЕ ТАКЖЕ
• ЛИЦЕНЗИЯ
• АВТОР

ИМЯ

autodie::exception - Исключения из функций autodie.

СИНОПС

eval {
    use autodie;

    open(my $fh, '<', 'some_file.txt');

    ...
};

if (my $E = $@) {
    say "Ooops!  ",$E->caller," had problems: $@";
}

ОПИСАНИЕ

Когда функция с включённым autodie терпит неудачу, она генерирует объект autodie::exception. Это можно исследовать, чтобы получить дополнительную информацию об ошибке, которая произошла.

Этот документ разделен на две части; те методы, которые наиболее полезны для конечного разработчика, и те методы, для тех, кто хочет создать подкласс или подробно ознакомиться с autodie::exception.

Общие методы

Эти методы предназначены для повседневной работы с исключениями.

Ниже предполагается, что ошибка скопирована в отдельный скаляр:

if ($E = $@) {
    ...
}

Это не обязательно, но рекомендуется на случай, если будет вызван какой-либо код, который может сбросить или изменить $@.

args

my $array_ref = $E->args;

Предоставляет ссылку на аргументы, переданные подпрограмме, которая завершилась ошибкой.

function

my $sub = $E->function;

Подпрограмма (включая пакет), которая сгенерировала исключение.

file

my $file = $E->file;

Файл, в котором произошла ошибка (например, myscript.pl или MyTest.pm).

package

my $package = $E->package;

Пакет, из которого была вызвана исключительная подпрограмма.

caller

my $caller = $E->caller;

Подпрограмма, которая вызвала исключительный код.

line

my $line = $E->line;

Строка в $E->file , где был вызван исключительный код.

context

my $context = $E->context;

Контекст, в котором подпрограмма была вызвана autodie; обычно тот же, что и контекст, в котором вы вызвали подпрограмму autodie. Это может быть 'list', 'scalar' или undefined (неизвестно). Он никогда не будет 'void', так как autodie всегда захватывает возвращаемое значение одним или другим способом.

Для некоторых основных функций, которые всегда возвращают скалярное значение независимо от контекста (например, chown), это может быть 'scalar', даже если вы использовали контекст списка.

return

my $return_value = $E->return;

Возвращаемое значение(я) неудачной подпрограммой. Когда подпрограмма вызывалась в контексте списка, это всегда будет ссылка на массив, содержащий результаты. Когда подпрограмма вызывалась в скалярном контексте, это будет фактический скаляр, возвращенный.

errno

my $errno = $E->errno;

Значение $! в момент возникновения исключения.

ПРИМЕЧАНИЕ: Этот метод покинет главный класс autodie::exception и станет частью роли в будущем. Вы должны вызывать errno только для исключений, где $! разумно было бы установлено при ошибке.

eval_error

my $old_eval_error = $E->eval_error;

Содержимое $@ сразу после того, как autodie сгенерировал исключение. Это может быть полезно при работе с модулями, такими как Text::Balanced, которые устанавливают (но не генерируют) $@ при ошибке.

matches

if ( $e->matches('open') ) { ... }

if ( 'open' ~~ $e ) { ... }

matches используется для определения, соответствует ли данное исключение определенной роли.

Исключение считается соответствующим строке, если:

• Для строки, не начинающейся с двоеточия, строка точно соответствует пакету и подпрограмме, которые генерировали исключение. Например, MyModule::log. Если строка не содержит имени пакета, подразумевается CORE::.

• Для строки, начинающейся с двоеточия, если подпрограмма, генерирующая исключение, именно так себя ведет. Например, подпрограмма CORE::open выполняет :file, :io и :all.

  См. "КАТЕГОРИИ" в autodie для получения дополнительной информации.

  В Perl 5.10 и выше, использование умного сравнения (~~) с объектом autodie::exception будет использовать matches внизу. Этот модуль раньше рекомендовал использовать умное сравнение с объектом исключения слева, но в будущих версиях Perl это, вероятно, перестанет работать. Утилита умного сравнения этого класса должна использоваться только с объектом исключения справа. Использование объекта исключения справа является будущим гарантированным и портируется в более старые версии Perl, начиная с 5.10. Обратите внимание, что эта функция может быть использована только в случае, если точно известно, что объект исключения является объектом autodie::exception; он не более способен, чем явное вызов метода matches.

Расширенные методы

Следующие методы, хотя и могут использоваться из любого места, предназначены в первую очередь для разработчиков, желающих создать подкласс autodie::exception, написать код, регистрирующий пользовательские сообщения об ошибках, или иначе тесно взаимодействовать с моделью autodie::exception.

register

autodie::exception->register( 'CORE::open' => \&mysub );

Метод register позволяет зарегистрировать обработчик сообщений для заданной подпрограммы. Должно использоваться полное имя подпрограммы, включая пакет.

Зарегистрированные обработчики сообщений будут получать объект autodie::exception в качестве первого параметра.

add_file_and_line

say "Problem occurred",$@->add_file_and_line;

Возвращает строку at %s line %d, где %s заменено именем файла, а %d заменено номером строки.

Предназначен в первую очередь для использования обработчиками формата.

stringify

say "The error was: ",$@->stringify;

Форматирует ошибку в виде удобочитаемой строки. Обычно нет необходимости вызывать это напрямую, так как оно автоматически используется, если объект autodie::exception используется как строка.

Подклассы могут переопределить этот метод, чтобы изменить способ форматирования строк.

format_default

my $error_string = $E->format_default;

Это создаёт строку с ошибкой по умолчанию для данного исключения, не используя зарегистрированных обработчиков сообщений. Он предназначен в первую очередь для вызова из обработчика сообщений, когда ему был передан объект исключения, который он не хочет форматировать.

Подклассы могут переопределить этот метод, чтобы изменить способ форматирования сообщений по умолчанию.

new

my $error = autodie::exception->new(
    args => \@_,
    function => "CORE::open",
    errno => $!,
    context => 'scalar',
    return => undef,
);

Создаёт новый объект autodie::exception. Обычно вызывается напрямую из функции autodie. Аргумент function необходим, это функция, которую мы пытались вызвать, которая сгенерировала исключение. Параметр args является необязательным.

Значение errno является необязательным. В версиях autodie::exception 1.99 и ранее код пытался автоматически использовать текущее значение $!, но это было ненадежно и больше не поддерживается.

Атрибуты, такие как пакет, файл и вызывающий, определяются автоматически и не могут быть указаны.

СМОТРИТЕ ТАКЖЕ

autodie, autodie::exception::system

ЛИЦЕНЗИЯ

Copyright (C)2008 Paul Fenwick

Это свободное программное обеспечение. Вы можете изменять и/или распространять этот код на тех же условиях, что и Perl 5.10, или, по вашему выбору, любую более позднюю версию Perl 5.

АВТОР

Paul Fenwick <pjf@perltraining.com.au>