autodie::exception

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
  • Общие методы
    • args
    • функция
    • файл
    • пакет
    • вызывающая функция
    • строка
    • контекст
    • возврат
    • errno
    • ошибка_eval
    • соответствия
  • Расширенные методы
    • зарегистрировать
    • добавить_файл_и_строку
    • преобразовать_в_строку
    • формат_по_умолчанию
    • новый
• СМОТРИТЕ ТАКЖЕ
• ЛИЦЕНЗИЯ
• АВТОР

ИМЯ

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;

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

функция

my $sub = $E->function;

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

файл

my $file = $E->file;

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

пакет

my $package = $E->package;

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

вызывающая функция

my $caller = $E->caller;

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

строка

my $line = $E->line;

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

контекст

my $context = $E->context;

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

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

возврат

my $return_value = $E->return;

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

errno

my $errno = $E->errno;

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

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

ошибка_eval

my $old_eval_error = $E->eval_error;

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

соответствия

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

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

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

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

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

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

  Дополнительную информацию см. в "КАТЕГОРИИ" в autodie.

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

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

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

зарегистрировать

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

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

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

добавить_файл_и_строку

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

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

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

преобразовать_в_строку

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

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

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

формат_по_умолчанию

my $error_string = $E->format_default;

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

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

новый

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>