名前¶

Carp - モジュールのための warn と die の代替

概要¶

    use Carp;

    # warn user (from perspective of caller)
    carp "string trimmed to 80 chars";

    # die of errors (from perspective of caller)
    croak "We're outta here!";

    # die of errors with stack backtrace
    confess "not implemented";

    # cluck not exported by default
    use Carp qw(cluck);
    cluck "This is how we got here!";

説明¶

Carpルーチンはモジュールで使う際に便利です。die()やwarn()と同じように 動きますが、モジュールのユーザーにより便利になります。cluck、confeess、longmess では、コールスタックの全ての呼び出しのサマリになります。 短いメッセージがよければ、carpかcroakを使えます。 モジュールが呼ばれた場所からエラーをレポートします。エラーがどこで 起きたかは保証しませんが、良い根拠のある推測になります。

出力とCarpの動作ロジックを変更することも出来ます。 Carpにあるグローバル変数を変更することで可能です。 後述の、GLOBAL VARIABLESのセクションを見てください。

以下は、carpとcroakの動作の仕方の完全な説明です。 carpとcroakがしていることは、エラーであるべきでないと教えている場所の 関数呼び出しのスタックのコールスタックの検索です。 もし、すべての呼び出しが安全とされていれば、諦めて、全てのスタックのバックトレースを 代わりに与えます。言い換えると、最初に見つかりそうな潜在的な容疑者を有罪と予想します。 呼び出しがエラーを生成すべきどうかを教えるルールは以下のように動きます:

1. Any call from a package to itself is safe.

   パッケージから、自分自信に対する、のどのような呼び出しも安全です。

2. Packages claim that there won't be errors on calls to or from packages explicitly marked as safe by inclusion in @CARP_NOT, or (if that array is empty) @ISA. The ability to override what @ISA says is new in 5.8.

   パッケージが@CARP_NOTか、(もし、配列が空の場合)@ISAに含まれていることで、 安全であると明示的にマークされたパッケージへの、または、パッケージからの呼び出しは エラーとみなさないとする。

3. The trust in item 2 is transitive. If A trusts B, and B trusts C, then A trusts C. So if you do not override @ISA with @CARP_NOT, then this trust relationship is identical to, "inherits from".

   2により、AがBを信任するならば、BはCを信任し、AもCを信任する。 @ISAを@CARP_NOTでオーバーライドしなければ、この信任の関係は、 "継承元"と同一になります。

4. Any call from an internal Perl module is safe. (Nothing keeps user modules from marking themselves as internal to Perl, but this practice is discouraged.)

   内部のPerlモジュールからのどのような呼び出しも安全です。 (Perlの内部のものとしてユーザーのモジュールをマークすると、 ユーザーのモジュールを保持しませんが、この方法は推奨されません)

5. Any call to Perl's warning system (eg Carp itself) is safe. (This rule is what keeps it from reporting the error at the point where you call carp or croak.)

   Perlの警告システム(例えば、Carp自身)のどのような呼び出しも安全です。 (このルールは、carpやcroakを呼んだ時に、エラーのレポートから保持するものです)

6. $Carp::CarpLevel can be set to skip a fixed number of additional call levels. Using this is not recommended because it is very difficult to get it to behave correctly.

   $Carp::CarpLevel 追加の呼び出しレベルの固定数をスキップするのに 使います。誠意角に動作させるのがとても難しいので、推奨されません。

スタックトレースを強制する¶

デバッグの助けとして、Carpにたいして、croak を confess として、 carp を cluckとして、すべてのモジュールにわたって、扱うことが出来ます。 言い換えると、詳細なスタックトレースを強制します。警告やエラーが生まれたのが どこからなのか、なぜなのかを理解しようとする際には、とても助かります。

この機能は、存在しないシンボルの'verbose'を'インポート'のすることで、 有効になります。典型的に、次のようにします

    perl -MCarp=verbose script.pl

または、文字列 -MCarp=verboseをPERL5OPT環境変数に含めておいても 同じです。

代わりに、グローバル変数 $Carp::Verboseを真にすることもできます。 後述のグローバル変数セクションを見てください。

グローバル変数¶

$Carp::MaxEvalLen¶

この変数は文字列evalを出力する文字数を決めます。 0の場合、全てのテキストを表示します。

デフォルトは0です。

$Carp::MaxArgLen¶

この変数は出力される関数の引数の文字数を決めます。 0にすると、引数の全てを表示します。

デフォルトは64です。

$Carp::MaxArgNums¶

この変数は表示する引数の数を決めます。 0にすると、全ての引数を表示します。

デフォルトは0です。

$Carp::Verbose¶

この変数はcarpとcroackが、cluckとconfessのように、 スタックバックトレースを出すようにします。 use Carp 'verbose'が 内部で実装されている方法です。

デフォルトは0です。

@CARP_NOT¶

この変数は、あなたのパッケージで、どのパッケージがエラーの場所として 考えないかを述べています。carp()とcluck()関数はエラーが起きた場所を 報告する際に呼び出しをスキップします。

要注意: この変数はパッケージのシンボルテーブルになければいけません。このように:

    # These work
    our @CARP_NOT; # file scope
    use vars qw(@CARP_NOT); # package scope
    @My::Package::CARP_NOT = ... ; # explicit package variable

    # These don't work
    sub xyz { ... @CARP_NOT = ... } # w/o declarations above
    my @CARP_NOT; # even at top-level

使い方:

    package My::Carping::Package;
    use Carp;
    our @CARP_NOT;
    sub bar     { .... or _error('Wrong input') }
    sub _error  {
        # temporary control of where'ness, __PACKAGE__ is implicit
        local @CARP_NOT = qw(My::Friendly::Caller);
        carp(@_)
    }

これにより、CarpはMy::Carping::PackageでもMy::Friendly::Callerでもない 呼び出し元から来るものとしてエラーを報告します。

上述のDESCRIPTIONセクションも呼んでください。どのようにCarpが エラーがどこから来たのかを決めているかについて書いています。

@CARP_NOTを$Carp::CarpLevelの代わりに使ってください。

<Carp>が@ISAを使っているものを上書きします。

%Carp::Internal¶

Perlに、パッケージがPerlの内部のものだと伝えます。Carpは Perl内部のものであるパッケージの行から来るエラーを決して報告しません。 例えば:

    $Carp::Internal{ (__PACKAGE__) }++;
    # time passes...
    sub foo { ... or confess("whatever") };

__PACAKGE__の外の最初の呼び出しから、完全なスタックbacktraceが はじまります。(そのパッケージも同様にPerlの内部でなければ)

%Carp::CarpInternal¶

この変数はPerlの警告システムにどのパッケージが内部のものであるかを教えます。 完全なスタックバックトレースを出すために、Perlに内部のものと同じであり、 %Carp::CarpInternalにリストされているパッケージの内側で、 スタックバックトレースは開始されません。ですが、carpとcroakの サマリメッセージに弱化の違いがあります。%Carp::CarpInternalで 呼んでいるパッケージのどの行もエラーは報告されません。

例えば、Carp自身は、%Carp::CarpInternalにリストされています。 そのため、confessの完全なスタックバックトレースには、Carpの内側で 始まることはありません。croakの呼び出しによる短いメッセージは croakが呼ばれた行にはなりません。

$Carp::CarpLevel¶

この変数は、Carpの関数を呼び出すために、エラーが起きた場所を 報告する際に、通常スキップされない、フレームの呼び出しを何回 スキップするかを決めます。完全なバックトレースを生成する呼び出しで これらのコールフレームを数えるのは、かなり簡単です。 ですが、短いメッセージの呼び出しを計算するのは、大変です。 通常、多すぎるコールフレームはスキップしたいものです。 If they are lucky they skip enough that Carp goes all of the way through the call stack, realizes that something is wrong, and then generates a full stack backtrace. If they are unlucky then the error is reported from somewhere misleading very high in the call stack.

$Carp::CarpLevelは避けるのが一番良いです。代わりに @CARP_NOT、%Carp::Internal、%Carp::CarpInternalを使ってください。

デフォルトは0です。

バグ¶

Carpルーチンは例外オブジェクトを現在のところ扱いません。 最初の引数がリファレンスでも、Carpのルーチンはそれに見合った、die() か warn() を 単純に呼び出します。

SEE ALSO¶

Carp::Always, Carp::Clan

作者¶

Carpモジュールは最初に、Larry Wall の perl 5.000 ディストリビューションに登場しました。 それから、perl 5 ポーターズの数人の手で変更されています。 Andrew Main (Zefram) <zefram@fysh.org>がCarpを独立したディストリビューションに しました。

コピーライト¶

Copyright (C) 1994-2012 Larry Wall

Copyright (C) 2011, 2012 Andrew Main (Zefram) <zefram@fysh.org>

ライセンス¶

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.