autodie

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• СИНТАКСИС
• ОПИСАНИЕ
• ИСКЛЮЧЕНИЯ
• КАТЕГОРИИ
• ЗАМЕЧАНИЯ, СВЯЗАННЫЕ С ФУНКЦИЯМИ
  • print
  • flock
  • system/exec
• ТРУДНОСТИ
• ДИАГНОСТИКА
• Советы и хитрости
  • Импорт autodie в другое пространство имён, отличное от «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 предоставляет удобный способ заменить функции, которые обычно возвращают ложь при ошибке, на эквиваленты, выбрасывающие исключение при ошибке.

Предикат 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 возвращает ложь из-за состояния EWOULDBLOCK (или эквивалентного) условия. Это означает, что можно по-прежнему использовать общепринятую конвенцию проверки возвращаемого значения flock при вызове с опцией LOCK_NB:

use autodie;

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

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

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 в другое пространство имён, отличное от «caller»

Возможно импортировать autodie в другое пространство имён, используя 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 Request Tracker по адресу https://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie.

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

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

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

АВТОР

Copyright 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 .