диагностика

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
  • Директива 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;

в начале (или около начала) вашей программы. (Обратите внимание, что это включает флаг -w Perl). Весь процесс компиляции затем будет подвергнут ( :-) усиленной диагностике. Сообщения по-прежнему выводятся в 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, нет смысла в возможности enable() или disable() обработки.

Выходные данные 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 г.