名前¶

carp - エラーの警告 (呼び出し元の観点から)

cluck - スタックバックトレースを伴うエラーの警告 (デフォルトではエクスポートされません)

croak - エラーを出して die する (呼び出し元の観点から)

confess - スタックバックトレースを伴って die する

概要¶

    use Carp;
    croak "We're outta here!";

    use Carp qw(cluck);
    cluck "This is how we got here!";

説明¶

Carp ルーチンは die() や warn() のように振る舞いますが、 あなたのモジュールのユーザーにとってより便利なものとなりそうな メッセージを伴うため、モジュールで用いる際に便利です。 cluck, confess, logmess ではそのコンテキストは コールスタック内の全ての呼び出しに関する要約です。 より短いメッセージのためには carp または croak を 使うことによって、モジュールが呼び出された位置から エラーを報告できます。 これはエラーがどこで発生したかを保証するものではありませんが、 優れた推測機能を提供します。

また、Carp 名前空間のグローバル変数を変更することで、Carp の 出力と動作原理を変更できます。 後述する GLOBAL VARIABLES 節を参照してください。

以下は 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 に 含まれることで明らかに安全なものとしてマークされているパッケージからの、 あるいはパッケージへの呼び出しでエラーが存在しないはずであることを 主張します。 @ISA を上書きする機能は 5.8 での新機能です。

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 を信頼します。 よってもし @CARP_NOT で @ISA を上書きしなければ、この信頼関係は 「継承された」のと同じです。

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 を 設定できます。 正しく振る舞うようにこれを設定するのはとても難しいので、これを使うことは 勧めません。

スタックトレースの強制¶

デバッグを行う目的で、あなたは 全ての モジュールに渡って、 croak を confess として、carp を cluck として扱うよう Carp に 強制させることができます。 言い替えると、より詳細なスタックトレースを提供するよう強制します。 これはなぜ、あるいはどこから警告またはエラーが 生成されるのかを知ろうとする際、大きな助けとなり得ます。

この機能は存在しないシンボル 'verbose' を 'import' することで 使用可能となります。 一般的には次のように宣言することで可能になります。

    perl -MCarp=verbose script.pl

あるいは環境変数 PERL50PT に -MCarp=verbose を含めることでも 可能になります。

または、グローバル変数 $Carp::Verbose を真に設定することもできます。 後述する GLOBAL VARIABLES の節を参照してください。

グローバル変数¶

$Carp::MaxEvalLen¶

この変数は、文字列 eval を何文字分出力に含めるかを決定します。 全てを表示するには 0 を設定します。

デフォルトは 0 です。

$Carp::MaxArgLen¶

この変数は、関数のそれぞれの引数を何文字分表示するかを決定します。 引数を全て表示するには 0 を設定します。

デフォルトは 64 です。

$Carp::MaxArgNums¶

この変数は、それぞれの関数でいくつの引数を表示するかを決定します。 関数呼び出しの全ての引数を表示するには 0 を設定します。

デフォルトは 8 です。

$Carp::Verbose¶

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

デフォルトは 0 です。

%Carp::Internal¶

これは、どのパッケージが Perl 内部のものであるかを決定します。 Carp は、Perl 内部であるパッケージの中の行からのエラーを報告しません。 例えば:

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

これは、__PACKAGE__ の外側の最初の呼び出し元からの完全な スタックバックとレースを出力します。 (そのパッケージも Perl 内部のものでない限りです。)

%Carp::CarpInternal¶

これは、どのパッケージが Perl の警告システムの内部かを決定します。 完全なスタックバックトーレスを生成するとき、これは Perl 内部と同様に 扱われ、スタックバックとレースは %Carp::CarpInternal にある パッケージの内側からは開始されません。 しかし、carp や croak で生成される要約メッセージでは少し異なります。 これらのエラーは %Carp::CarpInternal にある呼び出しパッケージの行は 報告されません。

例えば、Carp 自身は %Carp::CarpInternal に入っています。 従って、confess からの完全なスタックバックとレースは Carp の 内側からは開始せず、croak を呼び出すことによる短いメッセージは croak が呼び出された行は含みません。

$Carp::CarpLevel¶

この変数は、Carp の関数の一つへの呼び出しでどこでエラーを起きたかを 報告する際、いくつの追加の呼び出しフレームを飛ばすかを決定します。 完全なスタックバックとレースを生成する、これらの呼び出しの呼び出しフレームを 数えるのは比較的容易です。 しかし、短いメッセージを生成する呼び出しのためにこれを数えるのは 遙かに難しいです。 通常人々は呼び出しフレームを多く飛ばしすぎます。 もし幸運なら、Carp がコールスタック全体を通すのに十分なだけ飛ばして、 何かがおかしいことに気付き、完全なスタックバックとレースを生成します。 もし不運なら、エラーはコールスタックのとても誤解されやすいどこかから 報告されます。

従って、$Carp::CarpLevel を避けるのが最善です。 代わりに @CARP_NOT, %Carp::Internal, %Carp::CarpInternal を 使ってください。

デフォルトは 0 です。

バグ¶

Carpルーチンは今のところexceptionオブジェクトをハンドルしていません。 もし最初の引数がリファレンスであれば、単純にdie()あるいはwarn()を 適切に呼び出します。