Reporting Errors and Warnings Like Built-ins (Perl Cookbook, 2nd Edition)

## 12.14. Reporting Errors and Warnings Like Built-ins

### 12.14.1. Problem

You want to generate errors and warnings in your modules, but when you use `warn` or `die`, the user sees your own filename and line number. You'd like your functions to act like built-ins and report messages from the perspective of the user's code, not your own.

### 12.14.2. Solution

The standard Carp module provides functions to do this. Use `carp` instead of `warn`. Use `croak` (for a short message) and `confess` (for a long message) instead of `die`.

### 12.14.3. Discussion

Like built-ins, some of your module's functions generate warnings or errors if all doesn't go well. Think about `sqrt`: when you pass it a negative number (and you haven't used the Math::Complex module), an exception is raised, producing a message such as "`Can't` `take` `sqrt` `of` `-3` `at` `/tmp/negroot` `line` `17`", where /tmp/negroot is the name of your own program. But if you write your own function that `die` s, perhaps like this:

>     sub even_only {
>         my $n = shift;
>         die "$n is not even" if $n & 1;  # one way to test
>         #....
>     }

then the message will say it's coming from the file your `even_only` function was itself compiled in, rather than from the file the user was in when they called your function. That's where the Carp module comes in handy. Instead of using `die`, use `croak` instead:

>     use Carp;
>     sub even_only {
>         my $n = shift;
>         croak "$n is not even" if $n % 2;  # here's another
>         #....
>     }

If you just want to complain about something, but have the message report where in the user's code the problem occurred, call `carp` instead of `warn`. For example:

>     use Carp;
>     sub even_only {
>         my $n = shift;
>         if ($n & 1) {         # test whether odd number
>             carp "$n is not even, continuing";
>             ++$n;
>         }
>         #....
>     }

Many built-ins emit warnings only when the -w command-line switch has been used. The `$^W` variable (which is not meant to be a control character but rather a `^` followed by a `W`) reflects whether that switch was used. You could choose to grouse only if the user asked for complaints:

>     carp "$n is not even, continuing" if $^W;

The Carp module provides a third function: `confess`. This works just like `croak`, except that it provides a full stack backtrace as it dies, reporting who called whom and with what arguments.

If you're only interested in the error message from `carp`, `croak`, and friends, the `longmess` and `shortmess` functions offer those:

>     use Carp;
>     $self->transplant_organ( ) or
>       $self->error( Carp::longmess("Unable to transplant organ") );

### 12.14.4. See Also

The `warn` and `die` functions in Chapter 29 of Programming Perl and in perlfunc(1); the documentation for the standard Carp module, also in Chapter 32 of Programming Perl; Recipe 19.2; the discussion on `_ _WARN_ _` and `_ _DIE_ _` in the `%SIG` entry of Chapter 28 of Programming Perl, in perlvar(1), and in Recipe 16.15

Copyright © 2003 O'Reilly & Associates. All rights reserved.