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
$long_message   = longmess( "message from cluck() or confess()" );
$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. См. раздел GLOBAL VARIABLES ниже.

Вот более подробное описание работы 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. См. раздел GLOBAL VARIABLES ниже.

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

На каждом уровне стека отображается имя подпрограммы вместе с её параметрами. Для простых скаляров этого достаточно. Для сложных типов данных, таких как объекты и другие ссылки, это может просто отобразить '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

Эта переменная определяет, сколько аргументов каждой функции будет отображено. Используйте false значение, чтобы отобразить все аргументы вызова функции. Чтобы подавить все аргументы, используйте -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 сам.