autodie::exception

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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

СИНОПСИС

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, которые устанавливают (но не бросают) $@ при ошибке.

matches

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

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

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

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

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

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

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

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

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

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

register

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

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

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

add_file_и_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>