diagnostics, splain - 詳細な警告診断メッセージを出力する
diagnostics プラグマを使う:
use diagnostics;
use diagnostics -verbose;
enable diagnostics;
disable diagnostics;
splain スタンドアロンフィルタプログラムを使う:
perl program 2>diag.out
splain [-v] [-p] diag.out
diagnostics を使って正常に動作しないスクリプトのスタックトレースを取る:
perl -Mdiagnostics=-traceonly my_script.pl
diagnostics プラグマこのモジュールは perl コンパイラ及び perl インタプリタ双方から
(-w スイッチをつけたり use warnings を使ったりしている時に)
出力される簡潔な診断メッセージを perldiag にあるようなより説明的で
より親切な説明を増やすことで拡張します。
他のプラグマと同様、実行フェーズだけでなくプログラムのコンパイルフェーズにも
効果を持ちます。
プログラム中でプラグマとして使うには, 単純に
use diagnostics;
とプログラムの始まり(または始まり近く)で起動します。 (これは perl の -w フラグを有効に する ことに注意して下さい。) あなたのコンパイル全体が強化された診断の支配下に 置かれるようになります。 診断は STDERR に出力されます。
実行時とコンパイル時の間の相互作用によって、そしてそれは
どのみちあまりよいアイデアではないために、実行時に診断メッセージを
消すために no diagnostics 使えません。
しかし、disable() 及び enable() メソッドを使って実行時にその振る舞いを
制御することは可能です.
-verbose フラグは最初に他の診断に先立って perldiag の概説を 出力します。 $diagnostics::PRETTY 変数でページャ用のよりよいエスケープシーケンスを 生成できます。
perl 自身から発行される警告(より正確には、perldiag で
見つけることができる説明とマッチするもの)は、一度だけ
表示されます(説明は重複しません)。
warn() のように警告を生成するユーザのコードには影響しないので、ユーザが
メッセージを重複して表示させることは妨げません。
このモジュールは perl が die したときにエラーメッセージにスタック トレースを追加することも行います。 これは何が死因だったのかをピンポイントに探り当てるのに便利です。 -traceonly (または単に-t) フラグはスタックトレースは有効にしたまま 警告メッセージの説明を切ります。 従って、スクリプトが die するときには
perl -Mdiagnostics=-traceonly my_bad_script
を指定してもう一度実行することで死亡時のコールスタックを見ることが できます。 <-warntrace> (または単に -w)フラグを使うことですべての警告で スタックトレースが付与されます。
一見したところ全く別のプログラムのように見えますが、実際 splain は
diagnostics.pod ドキュメントへのリンクと同様に(実行可能な)
diagnostics.pm へのリンク以上の何者でもありません。
-v フラグは use diagnostics -verbose 指示子のようなものです。
-p フラグは $diagnostics::PRETTY 変数のようなものです。
splain で後処理をしているので処理を enable() または disable() を行う意味は
ありません。
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>&-
すごいでしょ?
at the enable() or disable() methods.
もし警告をその場で制御したいのならこのようなことを行います。
最初に 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{__WANR__} インターセプタ)が警告にその手段を持ったときだけです.
もしどんなものがインターセプトされているのかが猛烈に気になるのなら、 $diagnostics::DEBUG 変数を設定してみるとよいでしょう。
BEGIN { $diagnostics::DEBUG = 1 }
"no diagnostics" を使えないことは悩ましいですがおそらく 乗り越えられないでしょう。
-pretty 指示子は状況に影響を与えるには呼び出されるのが遅すぎます。
代わりにモジュールを読み込む 前に 次のことを行う必要があります。
BEGIN { $diagnostics::PRETTY = 1 }
必要になるまでコンパイルを遅延させることで起動を高速にできますが、 これは Perl 5.001e においてプラグマ形式を使ったとき "panic: top_level" を発生させます。
この文書は重要に準じるものである一方、splain という名前のプログラムを 使うのならちょっとした奇行を予測しておくべきです。
Tom Christiansen <tchrist@mox.perl.com>, 25 June 1995.