Carp

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
  • Принудительное отображение стека вызовов
  • Форматирование стека вызовов
• ГЛОБАЛЬНЫЕ ПЕРЕМЕННЫЕ
  • $Carp::MaxEvalLen
  • $Carp::MaxArgLen
  • $Carp::MaxArgNums
  • $Carp::Verbose
  • $Carp::RefArgFormatter
  • @CARP_NOT
  • %Carp::Internal
  • %Carp::CarpInternal
  • $Carp::CarpLevel
• ОШИБКИ
• СМОТРИТЕ ТАКЖЕ
• СОТРУДНИЧЕСТВО
• АВТОР
• АВТОРСКИЕ ПРАВА
• ЛИЦЕНЗИЯ

ИМЯ

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, longmess and shortmess not exported by default
use Carp qw(cluck longmess shortmess);
cluck "This is how we got here!"; # warn with stack backtrace
my $long_message   = longmess( "message from cluck() or confess()" );
my $short_message  = shortmess( "message from carp() or croak()" );

ОПИСАНИЕ

Функции Carp полезны в собственных модулях, так как они ведут себя как die() или warn(), но с сообщением, которое скорее всего будет полезно пользователю вашего модуля. В случае cluck() и confess(), этот контекст представляет собой сводку всех вызовов в стеке вызовов; longmess() возвращает содержимое сообщения об ошибке.

Для более короткого сообщения можно использовать carp() или croak(), которые сообщают об ошибке как о происходящей из места вызова вашего модуля. shortmess() возвращает содержимое этого сообщения об ошибке. Нет гарантии, что это место возникновения ошибки, но это хорошее предположение.

Carp заботится о том, чтобы не перезаписывать переменные состояния $! и $^E при формировании сообщений об ошибках. Это означает, что обработчик $SIG{__DIE__} или $SIG{__WARN__} может получить информацию об ошибке, хранящуюся в этих переменных, если необходимо дополнить сообщение об ошибке, и если вызывающий код Carp оставил там полезные значения. Конечно, Carp не может гарантировать последнее.

Вы также можете изменить способ работы вывода и логики Carp, изменив некоторые глобальные переменные в пространстве имен Carp. См. раздел «ГЛОБАЛЬНЫЕ ПЕРЕМЕННЫЕ» ниже.

Вот более полное описание работы carp и croak. Они выполняют поиск в стеке вызовов функции вызова стека, где им не было сказано, что ошибки быть не должно. Если все вызовы отмечены как безопасные, они отказываются и возвращают полный стек отслеживания вместо этого. Другими словами, они предполагают, что первый вероятный потенциальный подозреваемый виновен. Их правила для определения того, вызов не должен генерировать ошибки, работают следующим образом:

1. Любой вызов из пакета в сам себя безопасен.

2. Пакеты заявляют, что ошибок при вызовах в или из пакетов, явно помеченных как безопасные включением в @CARP_NOT, или (если этот массив пуст) @ISA, не будет. Возможность переопределения того, что говорит @ISA, нова в 5.8.

3. Доверие в пункте 2 транзитивно. Если A доверяет B, а B доверяет C, то A доверяет C. Таким образом, если вы не переопределите @ISA с помощью @CARP_NOT, то это отношение доверия идентично «наследованию».

4. Любой вызов из внутреннего модуля Perl безопасен. (Ничто не мешает пользовательским модулям помечать себя как внутренние для Perl, но такая практика не рекомендуется.)

5. Любой вызов Perl-системы предупреждений (например, сам Carp) безопасен. (Это правило не дает ему сообщать об ошибке в момент вызова carp или croak.)

6. $Carp::CarpLevel может быть задан для пропуска фиксированного количества дополнительных уровней вызовов. Не рекомендуется использовать это, так как очень сложно добиться правильного поведения.

Принудительное отображение стека вызовов

В качестве средства отладки можно принудительно заставить Carp обрабатывать croak как confess, а carp как cluck во всех модулях. Другими словами, принудительно вывести подробный стек вызовов. Это может быть очень полезно при попытке понять, почему или откуда генерируется предупреждение или ошибка.

Эта функция включается с помощью «импорта» несуществующего символа «verbose». Обычно ее включают следующим образом:

perl -MCarp=verbose script.pl

или путем включения строки -MCarp=verbose в переменной среды PERL5OPT.

В качестве альтернативы, можно установить глобальную переменную $Carp::Verbose в значение true. См. раздел «ГЛОБАЛЬНЫЕ ПЕРЕМЕННЫЕ» ниже.

Форматирование стека вызовов

На каждом уровне стека отображается имя подпрограммы вместе с ее параметрами. Для простых скалярных значений этого достаточно. Для сложных типов данных, таких как объекты и другие ссылки, это может просто отобразить 'HASH(0x1ab36d8)'.

Carp предлагает два способа управления этим.

1. Для объектов будет вызван метод CARP_TRACE, если он существует. Если этот метод не существует, или он рекурсивно возвращается в Carp, или он иначе генерирует исключение, это пропускается, и Carp переходит к следующему варианту. В противном случае проверка останавливается, и возвращенная строка используется. Рекомендуется, чтобы тип объекта был частью строки для упрощения отладки.

2. Для любого типа ссылки проверяется $Carp::RefArgFormatter. Ожидается, что эта переменная будет ссылкой на код, и текущий параметр передается в него. Если эта функция не существует (переменная undef), или она рекурсивно возвращается в Carp, или она иначе генерирует исключение, это пропускается, и Carp переходит к следующему варианту. В противном случае проверка останавливается, и возвращенная строка используется.

3. В противном случае, если ни CARP_TRACE, ни $Carp::RefArgFormatter недоступны, значение преобразуется в строку, игнорируя любое переопределение.

ГЛОБАЛЬНЫЕ ПЕРЕМЕННЫЕ

$Carp::MaxEvalLen

Эта переменная определяет, сколько символов строки-eval будет показано в выводе. Используйте значение 0 для отображения всего текста.

По умолчанию 0.

$Carp::MaxArgLen

Эта переменная определяет, сколько символов каждого аргумента функции будет напечатано. Используйте значение 0 для отображения полной длины аргумента.

По умолчанию 64.

$Carp::MaxArgNums

Эта переменная определяет, сколько аргументов каждой функции отображать. Используйте ложное значение, чтобы отобразить все аргументы вызова функции. Для подавления всех аргументов используйте -1 или '0 but true'.

По умолчанию 8.

$Carp::Verbose

Эта переменная заставляет carp() и croak() генерировать стеки вызовов так же, как cluck() и confess(). Таким образом реализован use Carp 'verbose'.

По умолчанию 0.

$Carp::RefArgFormatter

Эта переменная устанавливает общий формат аргументов для отображения ссылок. Простые скаляры и объекты, которые реализуют CARP_TRACE не будут обрабатываться этим форматом. Вызов Carp внутри этой функции не поддерживается.

local $Carp::RefArgFormatter = sub {
    require Data::Dumper;
    Data::Dumper->Dump($_[0]); # not necessarily safe
};

@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.

Также обратитесь к разделу «ОПИСАНИЕ» выше, о том, как Carp определяет, откуда сообщается об ошибке.

Используйте @CARP_NOT, вместо $Carp::CarpLevel.

Переопределяет использование Carp @ISA.

%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 в настоящее время не обрабатывают объекты исключений. Если они вызываются с первым аргументом, являющимся ссылкой, они просто вызывают die() или warn(), соответственно.

СМОТРИТЕ ТАКЖЕ

Carp::Always, Carp::Clan

СОТРУДНИЧЕСТВО

Carp поддерживается разработчиками perl 5 в рамках основного репозитория контроля версий perl 5. Пожалуйста, см. perlhack perldoc, чтобы узнать, как отправлять исправления и вносить свой вклад.

АВТОР

Модуль Carp впервые появился в дистрибутиве perl 5.000 Ларри Уолла. С тех пор он был изменён несколькими разработчиками perl 5. Эндрю Мейн (Zefram) <zefram@fysh.org> выделил Carp в отдельный дистрибутив.

АВТОРСКИЕ ПРАВА

Авторские права (C) 1994-2013 Ларри Уолл

Авторские права (C) 2011, 2012, 2013 Эндрю Мейн (Zefram) <zefram@fysh.org>

ЛИЦЕНЗИЯ

Этот модуль является свободным программным обеспечением; вы можете перераспределять его и/или изменять его в соответствии с теми же условиями, что и сам Perl.