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

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

COPYRIGHT

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

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

LICENSE

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