autodie::exception

(來源, CPAN)

版本 2.36

內容

名稱
概要
說明
- 常見方法
  - args
  - function
  - file
  - package
  - caller
  - line
  - context
  - return
  - errno
  - eval_error
  - matches
- 進階方法
另請參閱
授權
作者

#名稱

autodie::exception - 自動執行函數的例外。

#概要

eval {
    use autodie;

    open(my $fh, '<', 'some_file.txt');

    ...
};

if (my $E = $@) {
    say "Ooops!  ",$E->caller," had problems: $@";
}

#說明

當啟用 autodie 的函數失敗時，它會產生一個 autodie::exception 物件。可以查詢此物件以判斷發生錯誤的更多資訊。

此文件分為兩個部分；對最終開發人員最有用的方法，以及任何想要建立子類別或非常熟悉 autodie::exception 的人的方法。

#常見方法

這些方法旨在用於日常的例外處理。

以下假設錯誤已複製到一個獨立的標量中

if ($E = $@) {
    ...
}

這不是必需的，但建議在呼叫可能會重設或更改 $@ 的任何程式碼時使用。

#args

my $array_ref = $E->args;

提供對傳遞給已中斷子程式的參數的參考。

#function

my $sub = $E->function;

拋出例外的子程式（包括套件）。

#file

my $file = $E->file;

發生錯誤的文件（例如，myscript.pl 或 MyTest.pm）。

#package

my $package = $E->package;

呼叫異常子程式的套件。

#caller

my $caller = $E->caller;

呼叫異常程式碼的子程式。

#line

my $line = $E->line;

呼叫異常程式碼的 $E->file 中的行。

#context

my $context = $E->context;

autodie 呼叫子程式的上下文；通常與您呼叫 autodying 子程式的上下文相同。它可以是 'list'、'scalar' 或未定義（未知）。它永遠不會是 'void'，因為 autodie 總是以某種方式擷取回傳值。

對於某些核心函式，無論其上下文如何，總是回傳標量值（例如，chown），即使您使用清單上下文，這也可能是 'scalar'。

#return

my $return_value = $E->return;

失敗的子程式回傳的值。當子程式在清單上下文中呼叫時，這將永遠是對包含結果的陣列的參考。當子程式在標量上下文中呼叫時，這將是實際回傳的標量。

#errno

my $errno = $E->errno;

發生例外時 $! 的值。

注意：此方法將離開主 autodie::exception 類別，並在未來成為角色的一部分。您應該只對在失敗時合理設定 $! 的例外呼叫 errno。

#eval_error

my $old_eval_error = $E->eval_error;

autodie 觸發例外後立即 $@ 的內容。在處理會在錯誤時設定（但不拋出）$@ 的模組（例如 Text::Balanced）時，這可能很有用。

#matches

if ( $e->matches('open') ) { ... }

if ( 'open' ~~ $e ) { ... }

matches 用於確定給定的例外是否符合特定角色。

如果下列情況成立，則例外被認為與字串相符

對於不以冒號開頭的字串，字串會完全符合擲出例外狀況的套件和子常式。例如，MyModule::log。如果字串不包含套件名稱，則假設為 CORE::。
對於以冒號開頭的字串，如果擲出例外狀況的子常式會執行該行為。例如，CORE::open 子常式會執行 :file、:io 和 :all。

請參閱 "autodie 中的「CATEGORIES」" 以取得更多資訊。

在 Perl 5.10 及以上版本中，使用智慧比對 (~~) 和 autodie::exception 物件會在下方使用 matches。此模組過去建議在左手邊使用智慧比對和例外狀況物件，但在未來的 Perl 版本中，這種做法可能會停止運作。此類別的智慧比對功能只能在右手邊使用例外狀況物件。將例外狀況物件放在右手邊既能確保未來相容性，又能移植到較舊的 Perl 版本，包括 5.10。請注意，只有在確定例外狀況物件實際上是 autodie::exception 物件時，才能依賴此功能；它並不會比明確呼叫 matches 方法更有效。

#進階方法

下列方法雖然可以在任何地方使用，但主要供開發人員在 autodie::exception 的子類別中使用，撰寫註冊自訂錯誤訊息的程式碼，或以其他方式與 autodie::exception 模型密切合作。

#register

autodie::exception->register( 'CORE::open' => \&mysub );

register 方法允許為特定子常式註冊訊息處理常式。應使用包含套件的完整子常式名稱。

已註冊的訊息處理常式會收到 autodie::exception 物件作為第一個參數。

#add_file_and_line

say "Problem occurred",$@->add_file_and_line;

傳回字串 at %s line %d，其中 %s 會替換為檔案名稱，而 %d 會替換為行號。

主要供格式處理常式使用。

#stringify

say "The error was: ",$@->stringify;

將錯誤格式化為人類可讀的字串。通常不需要直接呼叫此方法，因為如果 autodie::exception 物件用作字串，它會自動使用。

子類別可以覆寫此方法，以變更字串化的方式。

#format_default

my $error_string = $E->format_default;

這會產生給定例外狀況的預設錯誤字串，而不會使用任何已註冊的訊息處理常式。它主要是用於訊息處理常式在傳遞不想要格式化的例外狀況時呼叫。

子類別可以覆寫此方法，以變更預設訊息的格式化方式。

#new

my $error = autodie::exception->new(
    args => \@_,
    function => "CORE::open",
    errno => $!,
    context => 'scalar',
    return => undef,
);

建立新的 autodie::exception 物件。通常會直接從自動終止函式呼叫。function 參數是必要的，它是要呼叫而產生例外狀況的函式。args 參數是選用的。

errno 值是選用的。在 autodie::exception 1.99 及更早的版本中，程式碼會嘗試自動使用 $! 的目前值，但這不可靠，而且不再支援。

封裝、檔案和呼叫者等屬性會自動決定，而且無法指定。

#另請參閱

autodie、autodie::exception::system

#授權

這是自由軟體。您可以在與 Perl 5.10 相同的條款下修改和/或重新散布此程式碼，或者，您可以選擇 Perl 5 的任何後續版本。

#作者

Paul Fenwick <pjf@perltraining.com.au>