диагностика

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
  • Директива diagnostics
  • Программа splain
• ПРИМЕРЫ
• ВНУТРЕННОСТИ
• ОШИБКИ
• АВТОР

ИМЯ

diagnostics, splain - вывод подробных диагностических сообщений об ошибках

СИНТАКСИС

Используя директиву diagnostics:

use diagnostics;
use diagnostics -verbose;

enable  diagnostics;
disable diagnostics;

Используя автономную программу-фильтр splain:

perl program 2>diag.out
splain [-v] [-p] diag.out

Использование diagnostics для получения стека вызовов из некорректно работающего скрипта:

perl -Mdiagnostics=-traceonly my_script.pl

ОПИСАНИЕ

Директива diagnostics

Этот модуль расширяет краткие диагностические сообщения, обычно выводимые как компилятором Perl, так и интерпретатором Perl (при запуске Perl с ключом -w или use warnings). Он дополняет их более подробными и понятными описаниями, содержащимися в perldiag. Как и другие директивы, он влияет на фазу компиляции программы, а не только на фазу выполнения.

Чтобы использовать в программе как директиву, просто вызовите

use diagnostics;

в начале (или около начала) вашей программы. (Обратите внимание, что это включает флаг Perl -w). Вся ваша компиляция будет затем подвержена улучшенной диагностике. Эти сообщения по-прежнему выводятся в STDERR.

Из-за взаимодействия проблем времени выполнения и времени компиляции, и потому что это, вероятно, не очень хорошая идея, вы не можете использовать no diagnostics для выключения диагностики на этапе компиляции. Однако вы можете контролировать их поведение во время выполнения, используя методы disable() и enable() соответственно.

Флаг -verbose сначала выводит вводную часть perldiag перед другими диагностическими сообщениями. Переменная $diagnostics::PRETTY может генерировать более приятные управляющие последовательности для просмотра страниц.

Предупреждения, исходящие от самого Perl (или, точнее, которые соответствуют описаниям, найденным в perldiag), отображаются только один раз (описания не дублируются). Предупреждения, генерируемые пользовательским кодом, например, warn(), не затрагиваются, что позволяет отображать дублируемые пользовательские сообщения.

Этот модуль также добавляет стек вызовов к сообщению об ошибке, когда Perl завершается ошибкой. Это полезно для определения причины завершения. Флаг -traceonly (или просто -t) отключает пояснения сообщений об ошибках, оставляя только стеки вызовов. Таким образом, если ваш скрипт завершается ошибкой, запустите его снова с

perl -Mdiagnostics=-traceonly my_bad_script

чтобы увидеть стек вызовов в момент завершения. С помощью флага -warntrace (или просто -w) все предупреждения, выводимые, также будут сопровождаться стеком вызовов.

Программа splain

Хотя это, по всей видимости, отдельная программа, splain на самом деле является просто ссылкой на (исполняемый) модуль diagnostics.pm, а также ссылкой на документацию diagnostics.pod. Флаг -v похож на директиву use diagnostics -verbose. Флаг -p похож на переменную $diagnostics::PRETTY. Поскольку вы выполняете пост-обработку с помощью splain, нет смысла иметь возможность включения или выключения обработки.

Вывод splain направляется в STDOUT, в отличие от директивы.

ПРИМЕРЫ

Следующий файл обязательно вызовет несколько ошибок как во время выполнения, так и во время компиляции:

use diagnostics;
print NOWHERE "nothing\n";
print STDERR "\n\tThis message should be unadorned.\n";
warn "\tThis is a user warning";
print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
my $a, $b = scalar <STDIN>;
print "\n";
print $x/$y;

Если вы предпочитаете сначала запустить свою программу, а потом посмотреть на её проблемы, сделайте так:

perl -w test.pl 2>test.out
./splain < test.out

Обратите внимание, что это не всегда возможно в оболочках сомнительного происхождения, так как теоретически

(perl -w test.pl >/dev/tty) >& test.out
./splain < test.out

Потому что вы просто перенаправили существующий stdout в другое место.

Если вы не хотите изменять исходный код, но все же хотите получать предупреждения в режиме реального времени, сделайте так:

exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&- 

Неплохо, да?

Если вы хотите управлять предупреждениями в режиме реального времени, сделайте что-то вроде этого. Убедитесь, что вы выполнили use предварительно, иначе вы не сможете получить доступ к методам enable() или disable().

use diagnostics; # checks entire compilation phase 
    print "\ntime for 1st bogus diags: SQUAWKINGS\n";
    print BOGUS1 'nada';
    print "done with 1st bogus\n";

disable diagnostics; # only turns off runtime warnings
    print "\ntime for 2nd bogus: (squelched)\n";
    print BOGUS2 'nada';
    print "done with 2nd bogus\n";

enable diagnostics; # turns back on runtime warnings
    print "\ntime for 3rd bogus: SQUAWKINGS\n";
    print BOGUS3 'nada';
    print "done with 3rd bogus\n";

disable diagnostics;
    print "\ntime for 4th bogus: (squelched)\n";
    print BOGUS4 'nada';
    print "done with 4th bogus\n";

ВНУТРЕННОСТИ

Диагностические сообщения взяты из файла perldiag.pod, если он доступен во время выполнения. В противном случае они могут быть встроены в сам файл во время сборки пакета splain. Подробности см. в файле Makefile.

Если обнаружен существующий обработчик $SIG{__WARN__}, он будет продолжать выполняться, но только после того, как функция diagnostics::splainthis() (перехватчик $SIG{__WARN__} модуля) обработает ваши предупреждения.

Есть переменная $diagnostics::DEBUG, которую вы можете установить, если вы очень хотите узнать, какие типы вещей перехватываются.

BEGIN { $diagnostics::DEBUG = 1 } 

ОШИБКИ

Невозможность сказать «нет диагностике» раздражает, но, возможно, не является непреодолимой.

Директива -pretty вызывается слишком поздно, чтобы повлиять на ситуацию. Вместо этого необходимо сделать следующее, и до загрузки модуля.

BEGIN { $diagnostics::PRETTY = 1 } 

Я мог бы запускаться быстрее, откладывая компиляцию до тех пор, пока она не потребуется, но это вызывает ошибку «panic: top_level» при использовании директивы в Perl 5.001e.

Хотя эта документация немного несерьёзна, если вы используете программу под названием splain, то вы должны ожидать немного иронии.

АВТОР

Tom Christiansen <tchrist@mox.perl.com>, 25 июня 1995.