диагностика

СОДЕРЖАНИЕ

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

в начале (или около начала) вашей программы. (Обратите внимание, что это включает флаг 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 } 

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

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

АВТОР

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