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 г.