Carp::Clan(3)

💅 Carp::Clan(3) — the perl manual page, but make it make sense

okay bestie so this is Carp::Clan, and it's giving "report errors from perspective of caller of a clan of modules". yes the manual page is literally called Carp::Clan(3), we're being fancy. and we're on version 6.08 ✨

---

🌸 NAME

Carp::Clan — report errors from the perspective of the caller of a "clan" of modules 🫶

🦋 VERSION

version 6.08 — that's the one, no cap 💜

✨ SYNOPSIS

like, here's the whole vibe in one block:

carp    - warn of errors (from perspective of caller)

cluck   - warn of errors with stack backtrace

croak   - die of errors (from perspective of caller)

confess - die of errors with stack backtrace

   use Carp::Clan qw(^MyClan::);
   croak "We're outta here!";

   use Carp::Clan;
   confess "This is how we got here!";

carp = warn about stuff but from the caller's POV. cluck = same thing but with a stack backtrace attached (the gossipy version 💀). croak = die, again from the caller's POV. confess = die with a stack backtrace. iconic quartet, honestly 👑

🎀 DESCRIPTION

so this module is based on "Carp.pm" from Perl 5.005_03, right? and it's been modified to skip all package names matching the pattern that you give it in the use statement, inside the qw() term (or argument list). periodt.

let's say you have a whole family of modules or classes named Pack::A, Pack::B, and so on, and every single one of them does "Carp::Clan qw(^Pack::);" — or at least the one where the error or warning actually gets raised. 🧚

so like, if your script tool.pl calls module Pack::A, and module Pack::A calls module Pack::B, then an exception raised inside Pack::B will appear to have come from tool.pl — you know, the place where Pack::A was called — and not from Pack::A where Pack::B was called. which is what the unmodified "Carp.pm" would totally try to make you believe :-). rude.

this works exactly the same way if Pack::B calls Pack::C where the exception gets raised, et cetera, et cetera. 🔁

in other words? it blames all errors in the "Pack::*" modules on the user of these modules. i.e., on you. ;-) 💀 no thoughts head empty

okay so why do we even need to skip a whole clan (or family) of packages by pattern-matching its members? because sometimes these modules aren't classes derived from each other — and in that case, examining @ISA (like the original "Carp.pm" module does) literally doesn't help. 🙈

and the purpose + advantage here? a "clan" of modules can work together, call each other, throw exceptions at whatever depth down the calling hierarchy they want, and still show up as a monolithic block — like they're one single module — from the caller's perspective. main character energy, honestly 👑

now. if you just wanna ward off all error messages from the module where you did "use Carp::Clan" — like, you want all your errors and warnings to look like they came from where your module was called (this is the thing you usually used "use Carp;" for ;-)), instead of from inside your module itself (which, fair, you could do with a die or warn anyway) — then you don't need to provide a pattern at all. the module will just automatically provide the correct one for you. slay. ✨

so: just do "use Carp::Clan;" with no arguments, call carp or croak as appropriate, and they will automatically defend your module against all blames! 🛡️

in other words (again, i know, but it's important), a pattern is only necessary if you want several modules — more than one — to work together and appear as though they were only one. 🫶

🔥 Forcing a Stack Trace

as a debugging aid, you can force "Carp::Clan" to treat a croak like a confess, and a carp like a cluck. in other words: force a detailed stack trace to be given. super helpful when you're trying to understand why, or from where, a warning or error is being generated. 😭

this feature gets enabled either by "importing" the non-existent symbol 'verbose', or by setting the global variable $Carp::Clan::Verbose to a true value.

you'd typically turn it on by saying:

use Carp::Clan qw(verbose);

ngl, you can specify both a "family pattern" and the string "verbose" inside the qw() term (or argument list) of the use statement — but consider that a pattern of packages to skip is pretty pointless when verbose is gonna cause a full stack trace anyway. 💅

💀 BUGS

the "Carp::Clan" routines don't handle exception objects right now. if you call them with a first argument that's a reference, they just call die() or warn(), as appropriate. it's giving "we'll deal with that later" 🙈

bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Carp-Clan> (or bug-Carp-Clan@rt.cpan.org <mailto:bug-Carp-Clan@rt.cpan.org>).

🌈 AUTHOR

Steffen Beyer <STBEY@cpan.org> — king behavior 👑

🍓 CONTRIBUTORS

• Karen Etheridge <ether@cpan.org>
• Joshua ben Jore <jjore@cpan.org>
• Kent Fredric <kentnl@cpan.org>

the whole squad showed up and we love that for them 🫶✨

💜 COPYRIGHT AND LICENSE

this software is copyright (c) 2001 by Steffen Beyer, Joshua ben Jore.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🎀

---

and that's the whole page! source + version: perl v5.42.0, dated 2025-02-06, straight from Carp::Clan(3) — mwah, go forth and blame the right caller bestie 💅🌸