Carp

Ce module permet de générer des messages d'erreurs. Il s'agit d'un modules d'alternatives pour les avertissements et les extinctions.

Synopsis

Description

Les routines Carp sont utiles dans vos propres modules car elles agissent comme die() ou warn(), mais avec un message plus susceptible d'être utile à un utilisateur de votre module. Dans le cas de cluck() et confess(), ce contexte est un résumé de chaque appel dans la pile d'appels; longmess() renvoie le contenu du message d'erreur.

Pour un message plus court, vous pouvez utiliser carp() ou croak() signalant l'erreur comme provenant de l'endroit où votre module a été appelé. shortmess() renvoie le contenu de ce message d'erreur. Il n'y a aucune garantie que l'erreur provienne de cet endroit, mais c'est une estimation raisonnable.

Carp prend soin de ne pas altérer les variables d'état $! et $^E lors de l'assemblage de ses messages d'erreur. Cela signifie qu'un gestionnaire $SIG{__DIE__} ou $SIG{__WARN__} peut capturer les informations d'erreur contenues dans ces variables, si cela est nécessaire pour compléter le message d'erreur, et si le code appelant Carp y a laissé des valeurs utiles. Bien entendu, Carp ne peut garantir ce dernier point.

Vous pouvez également modifier le fonctionnement de la sortie et de la logique de Carp en modifiant certaines variables globales de l'espace de noms Carp. Consultez la section «VARIABLES GLOBALES» ci-dessous.

Voici une description plus complète du fonctionnement de Carp et Croak. Ils recherchent dans la pile d'appels une pile d'appels de fonction où aucune erreur ne devrait se produire. Si chaque appel est marqué comme sûr, ils abandonnent et fournissent une trace de pile complète. Autrement dit, ils supposent que le premier suspect potentiel leur semblant probable est coupable. Leurs règles pour déterminer si un appel ne devrait pas générer d'erreurs fonctionnent comme suit :

• Tout appel d'un paquet vers lui-même est sûr.
• Les paquets affirment qu'il n'y aura pas d'erreurs lors des appels vers ou depuis des paquets explicitement marqués comme sûrs par inclusion dans @CARP_NOT, ou (si ce tableau est vide) par @ISA. La possibilité de surcharger les instructions de @ISA est une nouveauté de la version 5.8.
• La confiance dans l'élément 2 est transitive. Si A fait confiance à B et que B fait confiance à C, alors A fait confiance à C. Ainsi, si vous ne remplacez pas @ISA par @CARP_NOT, cette relation de confiance est identique à «hérite de».
• Tout appel depuis un module Perl interne est sûr. (Rien n'empêche les modules utilisateur de se marquer comme internes à Perl, mais cette pratique est déconseillée.)
• Tout appel au système d'avertissement de Perl (par exemple, Carp lui-même) est sûr. (Cette règle l'empêche de signaler l'erreur au moment où vous appelez carp ou croak.)
• $Carp::CarpLevel peut être configuré pour ignorer un nombre fixe de niveaux d'appel supplémentaires. Cette option n'est pas recommandée, car son bon fonctionnement est très difficile à obtenir.

Forcer une trace de pile

Pour faciliter le débogage, vous pouvez forcer Carp à traiter un croassement comme une confession et un cri comme un gloussement dans tous les modules. Autrement dit, forcer la génération d'une trace de pile détaillée. Cela peut s'avérer très utile pour comprendre pourquoi, ou d'où, un avertissement ou une erreur est généré.

Cette fonctionnalité est activée en important le symbole inexistant «verbose». Vous l'activez généralement en disant :

ou en incluant la chaîne -MCarp=verbose dans la variable d'environnement PERL5OPT.

Vous pouvez également définir la variable globale $Carp::Verbose sur true. Consultez la section «VARIABLES GLOBALES» ci-dessous.

Formatage de la trace de pile

À chaque niveau de la pile, le nom de la sous-routine est affiché avec ses paramètres. Pour les scalaires simples, cela suffit. Pour les types de données complexes, tels que les objets et autres références, il suffit d'afficher «HASH(0x1ab36d8)».

Carp propose deux méthodes pour contrôler cela.

Pour les objets, une méthode, CARP_TRACE, est appelée si elle existe. Si cette méthode n'existe pas, ou si elle effectue une récursion dans Carp, ou si elle génère une exception, cette opération est ignorée et Carp passe à l'option suivante. Sinon, la vérification s'arrête et la chaîne renvoyée est utilisée. Il est recommandé que le type de l'objet fasse partie de la chaîne pour faciliter le débogage.

Pour tout type de référence, $Carp::RefArgFormatter est vérifié (voir ci-dessous). Cette variable est censée être une référence de code, et le paramètre actuel est transmis. Si cette fonction n'existe pas (la variable est indéfinie), si elle effectue une récursion dans Carp ou si elle génère une exception, cette opération est ignorée et Carp passe à l'option suivante. Sinon, la vérification s'arrête et la chaîne renvoyée est utilisée.

Sinon, si ni CARP_TRACE ni $Carp::RefArgFormatter ne sont disponibles, convertissez la valeur en chaîne en ignorant toute surcharge.

VARIABLES GLOBALES

$Carp::MaxEvalLen

Cette variable détermine le nombre de caractères d'une chaîne d'évaluation à afficher dans la sortie. Utilisez la valeur 0 pour afficher tout le texte.

La valeur par défaut est 0.

$Carp::MaxArgLen

Cette variable détermine le nombre de caractères à afficher pour chaque argument d'une fonction. Utilisez la valeur 0 pour afficher la longueur totale du paramètre.

La valeur par défaut est 64.

$Carp::MaxArgNums

Cette variable détermine le nombre d'arguments à afficher pour chaque fonction. Utilisez la valeur «false» pour afficher tous les paramètres d'un appel de fonction. Pour supprimer tous les arguments, utilisez -1 ou « 0 mais vrai ».

La valeur par défaut est 8.

$Carp::Verbose

Cette variable permet à carp() et croak() de générer des traces de pile, tout comme cluck() et confess(). C'est ainsi que l'utilisation de Carp 'verbose' est implémentée en interne.

La valeur par défaut est 0.

$Carp::RefArgFormatter

Cette variable définit un formateur d'arguments général pour afficher les références. Les scalaires simples et les objets implémentant CARP_TRACE ne seront pas traités par ce formateur. L'appel de Carp depuis cette fonction n'est pas pris en charge.

@CARP_NOT

Cette variable, dans votre paquet, indique quels paquets ne doivent pas être considérés comme l'emplacement d'une erreur. Les fonctions carp() et cluck() ignoreront les appelants lorsqu'elles signaleront l'emplacement d'une erreur.

Remarque : Cette variable doit figurer dans la table des symboles du paquet, donc :

Exemple d'utilisation :

Cela obligerait Carp à signaler l'erreur comme provenant d'un appelant ne figurant pas dans My::Carping::Package, ni dans My::Friendly::Caller.

Consultez également la section «DESCRIPTION» ci-dessus pour savoir comment Carp détermine l'origine du signalement de l'erreur.

Utilisez @CARP_NOT au lieu de $Carp::CarpLevel.

Remplace l'utilisation de @ISA par Carp.

%Carp::Internal

Ceci indique les paquets internes à Perl. Carp ne signalera jamais une erreur provenant d'une ligne d'un paquet interne à Perl. Par exemple :

fournirait une trace de pile complète, à partir du premier appelant hors de __PACKAGE__. (À moins que ce paquet ne soit également interne à Perl.)

%Carp::CarpInternal

Ceci indique les paquets internes au système d'avertissement de Perl. Pour générer une trace de pile complète, c'est la même chose que pour une trace interne à Perl : la trace de pile ne démarre pas dans les paquets listés dans %Carp::CarpInternal. Cependant, la situation est légèrement différente pour le message de résumé généré par carp ou croak. Ces erreurs ne sont pas signalées sur les lignes appelant des paquets dans %Carp::CarpInternal.

Par exemple, Carp lui-même est listé dans %Carp::CarpInternal. Par conséquent, la trace de pile complète de confess ne démarre pas dans Carp, et le message court appelant croak n'est pas placé sur la ligne où croak a été appelé.

$Carp::CarpLevel

Cette variable détermine le nombre de trames d'appel supplémentaires à ignorer, qui ne le seraient pas autrement, lors du signalement d'une erreur lors d'un appel à une fonction Carp. Il est relativement facile de compter ces trames d'appel pour les appels générant une trace de pile complète. En revanche, il est beaucoup plus difficile de le faire pour les appels générant un message court. En général, les utilisateurs ignorent trop de trames d'appel. Avec un peu de chance, ils en ignorent suffisamment pour que Carp parcoure toute la pile d'appels, détecte un problème et génère une trace de pile complète. Dans le cas contraire, l'erreur est signalée depuis un emplacement très haut dans la pile d'appels, ce qui peut induire en erreur.

Il est donc préférable d'éviter $Carp::CarpLevel. Utilisez plutôt @CARP_NOT, %Carp::Internal et %Carp::CarpInternal.

La valeur par défaut est 0.

Les bogues

Les routines Carp ne gèrent actuellement pas les objets d'exception. Si elles sont appelées avec un premier paramètre étant une référence, elles appellent simplement die() ou warn(), selon le cas.

Voir également

Carp::Always, Carp::Clan.