autodie::exception

СОДЕРЖАНИЕ

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

ИМЯ

autodie::exception - Исключение из функций с автоуправлением.

СИНТАКСИС

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 и выше при использовании умного совпадения (~~) с объектом autodie::exception используется 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

ЛИЦЕНЗИЯ

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

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

АВТОР

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