диагностика

СОДЕРЖАНИЕ

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

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

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, нет смысла иметь возможность включения или выключения обработки.

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

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

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

АВТОР

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