диагностика

СОДЕРЖАНИЕ

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

ИМЯ

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

СИНОПСИС

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

use diagnostics;
use diagnostics -verbose;

enable  diagnostics;
disable diagnostics;

Использование автономной программы-фильтра splain:

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

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

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 может генерировать более удобные последовательности escape для пейджеров.

Предупреждения, отправленные самим 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 } 

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

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

АВТОР

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