目次 TABLE OF CONTENTS
diagnostics, splain - 冗舌な診断警告の生成 diagnostics, splain - produce verbose warning diagnostics
diagnostics プラグマの使い方:
Using the diagnostics pragma:
use diagnostics;
use diagnostics -verbose;
enable diagnostics;
disable diagnostics;
splain スタンドアロンフィルタプログラムの使い方:
Using the splain standalone filter program:
perl program 2>diag.out
splain [-v] [-p] diag.outdiagnostics を使って正常に動作しないスクリプトのスタックトレースを とる方法: Using diagnostics to get stack traces from a misbehaving script:
perl -Mdiagnostics=-traceonly my_script.pldiagnostics プラグマ
The diagnostics Pragma
このモジュールは perl コンパイラ及び perl インタプリタ双方から
(-w スイッチをつけたり use warnings を使ったりしている時に)
発行される簡潔な診断を, perldiag [CPAN] にあるようなより説明的で
より親切な説明を増やすことで拡張します. 他のプラグマのように
実行フェーズだけでなくプログラムのコンパイルフェーズにも
効果を持ちます.
This module extends the terse diagnostics normally emitted by both the
perl compiler and the perl interpreter (from running perl with a -w
switch or use warnings), augmenting them with the more
explicative and endearing descriptions found in perldiag [CPAN]. Like the
other pragmata, it affects the compilation phase of your program rather
than merely the execution phase.
プログラム中でプラグマとして使うには, 単純に To use in your program as a pragma, merely invoke
use diagnostics;とプログラムの始まり(若しくは始まり近く)で呼び出します. (これは perl の -w フラグを有効にすることに注意して 下さい.) あなたのコンパイル全体が強化された診断の支配下に 置かれるようになります. 診断は STDERR に出力されます. at the start (or near the start) of your program. (Note that this does enable perl's -w flag.) Your whole compilation will then be subject(ed :-) to the enhanced diagnostics. These still go out STDERR.
実行時とコンパイル時の間の相互作用によって, そしてそれは
どのみちあまりよいアイデアではないために, 実行時に診断メッセージ
を消すために no diagnostics をは使えないでしょう.
しかしながら, disable() 及び enable() メソッドを使って
実行時にその振る舞いを制御することは可能です.
Due to the interaction between runtime and compiletime issues,
and because it's probably not a very good idea anyway,
you may not use no diagnostics to turn them off at compiletime.
However, you may control their behaviour at runtime using the
disable() and enable() methods to turn them off and on respectively.
-verbose フラグははじめに他の診断に先立って perldiag [CPAN] の紹介を 出力します. $diagnostics::PRETTY 変数でページャ用のよりよい エスケープシーケンスを生成することができます. The -verbose flag first prints out the perldiag [CPAN] introduction before any other diagnostics. The $diagnostics::PRETTY variable can generate nicer escape sequences for pagers.
perl 自身から発行される警告(またはより正確には, perldiag [CPAN] で 見つけることができる説明とマッチするもの)は, 一度だけ 表示されます(説明は重複しません). warn() のように警告を生成する ユーザのコードには影響しないので, ユーザがメッセージを重複して 表示させることは妨げません. Warnings dispatched from perl itself (or more accurately, those that match descriptions found in perldiag [CPAN]) are only displayed once (no duplicate descriptions). User code generated warnings a la warn() are unaffected, allowing duplicate user messages to be displayed.
このモジュールは perl が die したときにエラーメッセージにスタック トレースを追加することも行います. これは何が死因だったのかを ピンポイントに探り当てるのに便利です. -traceonly (若しくは単に -t) フラグはスタックトレースは有効にしたまま警告メッセージの 説明を切ります. なので, スクリプトが die するときには This module also adds a stack trace to the error message when perl dies. This is useful for pinpointing what caused the death. The -traceonly (or just -t) flag turns off the explanations of warning messages leaving just the stack traces. So if your script is dieing, run it again with
perl -Mdiagnostics=-traceonly my_bad_scriptを指定してもう一度実行することで死亡時のコールスタックを見ることが できます. <-warntrace> (若しくは単に -w)フラグを使うことで すべての警告でスタックトレースが付与されます. to see the call stack at the time of death. By supplying the -warntrace (or just -w) flag, any warnings emitted will also come with a stack trace.
nuther なプログラムの全体を見てみても, 実際 splain は
diagnostics.pod ドキュメントへのリンクと同様に(実行可能な)
diagnostics.pm へのリンク以上の何者でもありません.
-v フラグは use diagnostics -verbose ディレクティブのような
ものです. -p フラグは $diagnostics::PRETTY 変数のようなものです.
splain で後処理をしているので処理を enable() 若しくは disable()
を行う意味はありません.
While apparently a whole nuther program, splain is actually nothing
more than a link to the (executable) diagnostics.pm module, as well as
a link to the diagnostics.pod documentation. The -v flag is like
the use diagnostics -verbose directive.
The -p flag is like the
$diagnostics::PRETTY variable. Since you're post-processing with
splain, there's no sense in being able to enable() or disable() processing.
splain の出力はプラグマとは違って STDOUT に出力されます. Output from splain is directed to STDOUT, unlike the pragma.
次のファイルはいくつかのエラーを実行時とコンパイル時に 発生させます: The following file is certain to trigger a few errors at both runtime and compiletime:
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;まず先にプログラムを実行して問題を見ておきたいのなら 次のようにします: If you prefer to run your program first and look at its problem afterwards, do this:
perl -w test.pl 2>test.out
./splain < test.outこれは継承のより怪しいシェルでは一般的な方法ではありませんが, 理論的には: Note that this is not in general possible in shells of more dubious heritage, as the theoretical
(perl -w test.pl >/dev/tty) >& test.out
./splain < test.outなぜなら既存の stdout をどこか別のところにやっているからです. Because you just moved the existing stdout to somewhere else.
ソースコードをいじりたくないけれど警告を on-the-fly にとりたいの であれば次のようにします: If you don't want to modify your source code, but still have on-the-fly warnings, do this:
exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-すごいでしょ？ Nifty, eh?
もし警告を on the fly に制御したいのならこのような何かを
行います. 最初に use します, これがないと enable() 及び
disable() メソッドを使えません.
If you want to control warnings on the fly, do something like this.
Make sure you do the use first, or you won't be able to get
at the enable() or disable() methods.
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 を見てください. Diagnostic messages derive from the perldiag.pod file when available at runtime. Otherwise, they may be embedded in the file itself when the splain package is built. See the Makefile for details.
既存の $SIG{__WARN__} ハンドラが見つかっても, 誠実に継続しますが それは diagnostics::splainthis() 関数(このモジュールの $SIG{__WANR__} インターセプタ)が警告にその手段を持ったときだけです. If an extant $SIG{__WARN__} handler is discovered, it will continue to be honored, but only after the diagnostics::splainthis() function (the module's $SIG{__WARN__} interceptor) has had its way with your warnings.
もし何がインターセプトされているのかを猛烈に知りたいのであれば, $diagnostics::DEBUG 変数を設定してみるとよいでしょう. There is a $diagnostics::DEBUG variable you may set if you're desperately curious what sorts of things are being intercepted.
BEGIN { $diagnostics::DEBUG = 1 }"no diagnostics" を使えないことは悩ましいですがおそらく乗り越え られないでしょう. Not being able to say "no diagnostics" is annoying, but may not be insurmountable.
-pretty ディレクティブは状況に影響を与えるには呼び出すのが
遅すぎます. 代わりにモジュールをロードする前に次のことを
行う必要があります.
The -pretty directive is called too late to affect matters.
You have to do this instead, and before you load the module.
BEGIN { $diagnostics::PRETTY = 1 }必要になるまでコンパイルを遅延させることで起動を高速にできますが, これは Perl 5.001e においてプラグマ形式を使ったとき "panic: top_level" を発生させます. I could start up faster by delaying compilation until it should be needed, but this gets a "panic: top_level" when using the pragma form in Perl 5.001e.
ドキュメントは重要に準じるものであるので, splain プログラムを 使うのならいくぶん奇抜さを予測しておくべきです. While it's true that this documentation is somewhat subserious, if you use a program named splain, you should expect a bit of whimsy.
Tom Christiansen <tchrist@mox.perl.com>, 25 June 1995.
山科 氷魚 (YAMASHINA Hio) <hio@hio.jp>原典: perl VERSION 5.8.8. 翻訳日: 2007-03-16. Origlnal distribution is perl VERSION 5.8.8. Translated at 2007-03-16.