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

Эта переменная определяет, сколько символов строки string-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]); # не обязательно безопасно };

@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 сам.