autodie::исключение

СОДЕРЖАНИЕ

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

ИМЯ

autodie::исключение - Исключение из функций 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' или неопределённым (неизвестным). Никогда не будет '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 и выше при использовании умного сопоставления (~~) с объектом autodie::exception будет использоваться matches в качестве основы. Этот модуль раньше рекомендовал использовать умное сопоставление с объектом исключения в левой части, но в будущих версиях Perl это, вероятно, перестанет работать. Функция smart-match этого класса должна использоваться только с объектом исключения в правой части. Использование объекта исключения справа обеспечивает будущую устойчивость и совместимость со старыми версиями 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

ЛИЦЕНЗИЯ

Авторские права (C)2008 Пол Фенвик

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

АВТОР

Пол Фенвик <pjf@perltraining.com.au>