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 года.