splain

СОДЕРЖАНИЕ

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

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

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

АВТОР

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