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 с ключом -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 } 

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

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

АВТОР

Том Кристиансен <tchrist@mox.perl.com>, 25 июня 1995 года.