名前¶
diagnostics, splain - produce verbose warning diagnostics
diagnostics, splain - 詳細な警告診断メッセージを出力する
概要¶
Using the diagnostics pragma:
diagnostics プラグマを使う:
use diagnostics;
use diagnostics -verbose;
enable diagnostics;
disable diagnostics;Using the splain standalone filter program:
splain スタンドアロンフィルタプログラムを使う:
perl program 2>diag.out
splain [-v] [-p] diag.outUsing diagnostics to get stack traces from a misbehaving script:
diagnostics を使って正常に動作しないスクリプトのスタックトレースを取る:
perl -Mdiagnostics=-traceonly my_script.pl説明¶
The diagnostics Pragma¶
(diagnostics プラグマ)
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. Like the other pragmata, it affects the compilation phase of your program rather than merely the execution phase.
このモジュールは perl コンパイラ及び perl インタプリタ双方から (-w スイッチをつけたり use warnings を使ったりしている時に) 出力される簡潔な診断メッセージを perldiag にあるようなより説明的で より親切な説明を増やすことで拡張します。 他のプラグマと同様、実行フェーズだけでなくプログラムのコンパイルフェーズにも 効果を持ちます。
To use in your program as a pragma, merely invoke
プログラム中でプラグマとして使うには、単純に
use diagnostics;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.
とプログラムの始まり(または始まり近く)で起動します。 (これは perl の -w フラグを有効に する ことに注意して下さい。) あなたのコンパイル全体が強化された診断の支配下に 置かれるようになります。 診断は STDERR に出力されます。
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.
実行時とコンパイル時の間の相互作用によって、そしてそれは どのみちあまりよいアイデアではないために、実行時に診断メッセージを 消すために no diagnostics 使えません。 しかし、disable() 及び enable() メソッドを使って実行時にその振る舞いを 制御することは可能です。
The -verbose flag first prints out the perldiag introduction before any other diagnostics. The $diagnostics::PRETTY variable can generate nicer escape sequences for pagers.
-verbose フラグは最初に他の診断に先立って perldiag の概説を 出力します。 $diagnostics::PRETTY 変数でページャ用のよりよいエスケープシーケンスを 生成できます。
Warnings dispatched from perl itself (or more accurately, those that match descriptions found in perldiag) are only displayed once (no duplicate descriptions). User code generated warnings a la warn() are unaffected, allowing duplicate user messages to be displayed.
perl 自身から発行される警告(より正確には、perldiag で 見つけることができる説明とマッチするもの)は、一度だけ 表示されます(説明は重複しません)。 warn() のように警告を生成するユーザのコードには影響しないので、ユーザが メッセージを重複して表示させることは妨げません。
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 が die したときにエラーメッセージにスタック トレースを追加することも行います。 これは何が死因だったのかをピンポイントに探り当てるのに便利です。 -traceonly (または単に-t) フラグはスタックトレースは有効にしたまま 警告メッセージの説明を切ります。 従って、スクリプトが die するときには
perl -Mdiagnostics=-traceonly my_bad_scriptto 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.
を指定してもう一度実行することで死亡時のコールスタックを見ることが できます。 <-warntrace> (または単に -w)フラグを使うことですべての警告で スタックトレースが付与されます。
The splain Program¶
(splain プログラム)
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 は diagnostics.pod ドキュメントへのリンクと同様に(実行可能な) diagnostics.pm へのリンク以上の何者でもありません。 -v フラグは use diagnostics -verbose 指示子のようなものです。 -p フラグは $diagnostics::PRETTY 変数のようなものです。 splain で後処理をしているので処理を enable() または disable() を行う意味は ありません。
Output from splain is directed to STDOUT, unlike the pragma.
splain の出力はプラグマとは違って STDOUT に出力されます。
例¶
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.outNote 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.outBecause you just moved the existing stdout to somewhere else.
なぜなら既存の stdout をどこか別のところにやっているからです。
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?
すごいでしょ?
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 するようにします; これがないと 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";内部動作¶
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.
診断メッセージは実行時に perldiag.pod ファイルから派生します. それ以外は splain パッケージがビルドされたときにファイルに 埋め込まれています。 詳細は Makefile を見てください.
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.
既存の $SIG{__WARN__} ハンドラが見つかっても、誠実に継続しますが それは diagnostics::splainthis() 関数(このモジュールの $SIG{__WANR__} インターセプタ)が警告にその手段を持ったときだけです.
There is a $diagnostics::DEBUG variable you may set if you're desperately curious what sorts of things are being intercepted.
もしどんなものがインターセプトされているのかが猛烈に気になるのなら、 $diagnostics::DEBUG 変数を設定してみるとよいでしょう。
BEGIN { $diagnostics::DEBUG = 1 } バグ¶
Not being able to say "no diagnostics" is annoying, but may not be insurmountable.
"no diagnostics" を使えないことは悩ましいですがおそらく 乗り越えられないでしょう。
The -pretty directive is called too late to affect matters. You have to do this instead, and before you load the module.
-pretty 指示子は状況に影響を与えるには呼び出されるのが遅すぎます。 代わりにモジュールを読み込む 前に 次のことを行う必要があります。
BEGIN { $diagnostics::PRETTY = 1 } 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.
必要になるまでコンパイルを遅延させることで起動を高速にできますが、 これは Perl 5.001e においてプラグマ形式を使ったとき "panic: top_level" を発生させます。
While it's true that this documentation is somewhat subserious, if you use a program named splain, you should expect a bit of whimsy.
この文書は重要に準じるものである一方、splain という名前のプログラムを 使うのならちょっとした奇行を予測しておくべきです。
作者¶
Tom Christiansen <[email protected]>, 25 June 1995.