диагностика

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
  • Предикат диагностики
  • Программа 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 } 

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

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

АВТОР

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