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' 或 undefined（未知）。它永远不会是 '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 <[email protected]>