The documentation of that feature is too curt and the code is withstanding my attempts to understand it in a hurry. How does one employ that?

Makeshifts last the longest.

you just push there the names of the packages you want to skip when calling carp, croak, etc.

For instance:

#!/usr/bin/perl

package Foo;
sub foo { Bar::bar() }

package Bar;
use Carp;
our @CARP_NOT = qw(Foo);
sub bar { croak "hello" }

package main;
Foo::foo();
[download]

prints...

hello at /tmp/t.pl line 12
[download]

I don't get it. Can you demonstrate the problem that this solves?

my %handler; BEGIN { %handler = (
    foo => sub { ref $_[0] eq 'ARRAY' or croak "foo key takes a hashre
+f"; ... },
    bar => sub { $_[0] =~ /wibble$/ or croak "bar key must end with 'w
+ibble'"; ... },
) }

sub process_something {
    my %arg = @_;
    my @results;

    while( my ( $elem, $param ) = each %arg ) {
        push @results, $handler->{ $elem }->( $param );
    }
}
[download]

croak will say the error was in process_something, when you really want it to be thrown for the where the call to process_something was.

Makeshifts last the longest.

croak will say the error was in process_something's caller if process_something was called from another package. For example,

use strict;
use warnings;


package Module;

use Carp qw( croak );

my %handler = (
   foo => sub { ref $_[0] eq 'ARRAY' or croak "foo key takes a hashref
+";      1 },
   bar => sub { $_[0] =~ /wibble$/ or croak "bar key must end with 'wi
+bble'"; 1 },
);

sub process_something {
   my %arg = @_;
   my @results;

   while( my ( $elem, $param ) = each %arg ) {
      push @results, $handler{ $elem }( $param );
   }
}


package main;

Module::process_something( foo => 'a' );      # <-- line 27.
[download]

outputs

foo key takes a hashref at 554371.pl line 27
[download]

It's because it's not always the caller that's wrong. Sometimes it's better to see where the error appears in the module.

Btw, ruby and I think python too typically gives a full stack trace on errors. That's the best thing to do I belive, because the interperter can't decide which function really "caused" the error.

If a parameter fails to validate, then it’s the caller who is wrong. That doesn’t change, even if the parameter is only validated several internal subroutine calls deeper than where the module picked it up. If the validation code itself does happen to be at fault, you can still get a stack trace on demand by asking Carp to be verbose.

Makeshifts last the longest.