autodie

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
• ИСКЛЮЧЕНИЯ
• КАТЕГОРИИ
• ЗАМЕЧАНИЯ ПО ФУНКЦИЯМ
  • print
  • flock
  • system/exec
• ЛОВУШКИ
• ДИАГНОСТИКА
• Советы и хитрости
  • Импортирование autodie в другой namespace, чем "caller"
• ОШИБКИ
  • autodie и строковая eval
  • СООБЩЕНИЕ ОБ ОШИБКАХ
• ОБРАТНАЯ СВЯЗЬ
• АВТОР
• ЛИЦЕНЗИЯ
• СМОТРИТЕ ТАКЖЕ
• ПРИЗНАТЕЛЬНОСТИ

ИМЯ

autodie - Замена функций на те, что либо завершаются успешно, либо аварийно завершаются с лексическим охватом

СИНТАКСИС

use autodie;            # Recommended: implies 'use autodie qw(:default)'

use autodie qw(:all);   # Recommended more: defaults and system/exec.

use autodie qw(open close);   # open/close succeed or die

open(my $fh, "<", $filename); # No need to check!

{
    no autodie qw(open);          # open failures won't die
    open(my $fh, "<", $filename); # Could fail silently!
    no autodie;                   # disable all autodies
}

print "Hello World" or die $!;    # autodie DOESN'T check print!

ОПИСАНИЕ

bIlujDI' yIchegh()Qo'; yIHegh()!

It is better to die() than to return() in failure.

        -- Klingon programming proverb.

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

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

Если system указан в качестве аргумента к autodie, тогда он использует IPC::System::Simple для выполнения тяжелой работы. См. описание этого модуля для получения дополнительной информации.

ИСКЛЮЧЕНИЯ

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

eval {
    use autodie;

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

    my @records = <$fh>;

    # Do things with @records...

    close($fh);
};

if ($@ and $@->isa('autodie::exception')) {
    if ($@->matches('open')) { print "Error from open\n";   }
    if ($@->matches(':io' )) { print "Non-open, IO error."; }
} elsif ($@) {
    # A non-autodie exception.
}

См. autodie::exception для получения дополнительной информации об использовании исключений.

КАТЕГОРИИ

Autodie использует простую систему категорий для группировки похожих встроенных функций. Запрос типа категории (начинающийся с двоеточия) включит autodie для всех встроенных функций в этой категории. Например, запрос :file включит autodie для close, fcntl, open и sysopen.

Текущие категории:

:all
    :default
        :io
            read
            seek
            sysread
            sysseek
            syswrite
            :dbm
                dbmclose
                dbmopen
            :file
                binmode
                close
                chmod
                chown
                fcntl
                flock
                ioctl
                open
                sysopen
                truncate
            :filesys
                chdir
                closedir
                opendir
                link
                mkdir
                readlink
                rename
                rmdir
                symlink
                unlink
            :ipc
                kill
                pipe
                :msg
                    msgctl
                    msgget
                    msgrcv
                    msgsnd
                :semaphore
                    semctl
                    semget
                    semop
                :shm
                    shmctl
                    shmget
                    shmread
            :socket
                accept
                bind
                connect
                getsockopt
                listen
                recv
                send
                setsockopt
                shutdown
                socketpair
        :threads
            fork
    :system
        system
        exec

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

Простой use autodie подразумевает use autodie qw(:default). Обратите внимание, что system и exec не включены по умолчанию. system требует установки необязательного модуля IPC::System::Simple, а включение system или exec аннулирует их экзотические формы. См. «ОШИБКИ» ниже для получения более подробной информации.

Синтаксис:

use autodie qw(:1.994);

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

autodie может быть включен для всех встроенных функций Perl, включая system и exec с помощью:

use autodie qw(:all);

ЗАМЕЧАНИЯ ПО ФУНКЦИЯМ

print

Предикат autodie не проверяет вызовы к print.

flock

Не считается ошибкой, если flock возвращает false из-за условия EWOULDBLOCK (или эквивалентного). Это означает, что можно по-прежнему использовать стандартную практику проверки возвращаемого значения flock при вызове с опцией LOCK_NB:

use autodie;

if ( flock($fh, LOCK_EX | LOCK_NB) ) {
    # We have a lock
}

Автоматическое применение flock сгенерирует исключение, если flock вернет false с любой другой ошибкой.

system/exec

Встроенная функция system считается завершившейся с ошибкой в следующих случаях:

• Команда не запускается.

• Команда завершается сигналом.

• Команда возвращает ненулевое выходное значение (но см. ниже).

При успешном выполнении автоматическая форма system возвращает выходное значение, а не содержимое $?.

Дополнительные разрешенные выходные значения могут быть указаны в качестве необязательного первого аргумента к автоматической форме system:

system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values

autodie использует модуль IPC::System::Simple для изменения system. См. его документацию для получения дополнительной информации.

Применение autodie к system или exec приводит к тому, что экзотические формы system { $cmd } @args или exec { $cmd } @args рассматриваются как синтаксическая ошибка до конца лексического пространства. Если вам действительно нужно использовать экзотическую форму, вы можете вызвать CORE::system или CORE::exec вместо этого или использовать no autodie qw(system exec) перед вызовом экзотической формы.

ЛОВУШКИ

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

Некоторые встроенные функции (например, chdir или truncate) имеют сигнатуру вызова, которую нельзя полностью представить с помощью шаблона Perl. Это означает, что некоторые допустимые коды Perl будут недопустимы в autodie. Например:

chdir(BAREWORD);

Без autodie (и предполагая, что BAREWORD — открытый дескриптор файла/каталога) это допустимый вызов chdir. Но в autodie, chdir будет вести себя так, как будто у него был шаблон ";$", и поэтому BAREWORD будет синтаксической ошибкой (при "use strict". Без strict он будет интерпретироваться как имя файла).

ДИАГНОСТИКА

:void не может использоваться с лексическим охватом

Опция :void поддерживается в Fatal, но не в autodie. Чтобы обойти эту проблему, autodie может быть явно отключен до конца текущего блока с помощью no autodie. Чтобы отключить autodie только для одной функции (например, open), используйте no autodie qw(open).

autodie не выполняет проверки вызываемого контекста, чтобы определить, следует ли выбросить исключение; явность обработки ошибок с autodie — это целенаправленная функция.

Нет пользовательских подсказок для %s

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

См. также "ДИАГНОСТИКА" в Fatal.

Советы и хитрости

Импортирование autodie в другой namespace, чем "caller"

Возможно импортировать autodie в другой namespace, используя Import::Into. Однако вам нужно передать «глубину вызова» (а не имя пакета), чтобы это работало правильно.

ОШИБКИ

Предупреждения «использовалось только один раз» могут генерироваться при использовании autodie или Fatal с пакетными дескрипторами файлов (например, FILE). Рекомендуется использовать скалярные дескрипторы файлов.

При использовании autodie или Fatal с пользовательскими подпрограммами объявление этих подпрограмм должно появиться до первого использования Fatal или autodie, или они должны быть экспортированы из модуля. Попытка использовать Fatal или autodie с другими пользовательскими подпрограммами приведет к ошибке компиляции.

Из-за ошибки в Perl autodie может «потерять» любой формат с тем же именем, что и встроенная или функция autodie.

autodie может не работать правильно, если используется внутри файла с именем, похожим на строковую eval, например, eval (3).

autodie и строковая eval

Из-за текущей реализации autodie, могут наблюдаться непредсказуемые результаты при использовании рядом или вместе со строковой версией eval. Ни одна из этих ошибок не возникает при использовании блочного eval.

Только в Perl 5.8, autodie не распространяется на строковые eval операторы, хотя его можно явно включить внутри строкового eval.

Только в Perl 5.10 использование строковой eval, когда autodie активно, может привести к утечке поведения autodie в окружающую область. Это можно обойти, используя no autodie в конце области, чтобы явно удалить влияние autodie, или избегая использования строковой eval.

Ни одна из этих ошибок не возникает при использовании блочного eval. Использование autodie с блочным eval считается хорошей практикой.

СООБЩЕНИЕ ОБ ОШИБКАХ

Пожалуйста, сообщайте об ошибках через GitHub Issue Tracker по адресу https://github.com/pjf/autodie/issues.

ОБРАТНАЯ СВЯЗЬ

Если вы считаете этот модуль полезным, пожалуйста, оцените его на сайте CPAN Ratings по адресу http://cpanratings.perl.org/rate?distribution=autodie .

Автор модуля с удовольствием узнает, как autodie улучшил (или ухудшил) вашу жизнь. Отзывы можно отправлять по адресу <pjf@perltraining.com.au>.

АВТОР

Авторские права 2008-2009, Пол Фенвик <pjf@perltraining.com.au>

ЛИЦЕНЗИЯ

Этот модуль является свободным программным обеспечением. Вы можете распространять его на тех же условиях, что и сам Perl.

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

Fatal, autodie::exception, autodie::hints, IPC::System::Simple

Perl советы, autodie по адресу http://perltraining.com.au/tips/2008-08-20.html

ПРИЗНАТЕЛЬНОСТИ

Марк Рид и Роланд Гирзиг — переводчики клингонского языка.

См. файл AUTHORS для полного списка авторов. Последнюю версию этого файла можно найти по адресу https://github.com/pjf/autodie/tree/master/AUTHORS .