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.