Yes, I meant to put this in my comment above.

He can read through Error-handling-and-messages in the perlmodstyle page.

Specifically:

croak() only when your module absolutely cannot figure out what to do. (croak() is a better version of die() for use within modules, which reports its errors from the perspective of the caller. See Carp for details of croak(), carp() and other useful routines.)/p>

Anyway, usually, talking directly to the end user about some internals of the program is not a good idea... well, for scripts it is ok, specially if you are both the user and the programmer but for modules it's a bad idea, it doesn't escalate.

For most errors, the best think to do is to croak() and let the module user wrap the call in eval if he wants to handle the error in some way or just ignore it.

Sometimes, returning false and passing more information about the error in $! also makes sense.

Yeah, you're right, looks like I got them the wrong way around . As for talking to the end-user from a module, I think using carp for that is an elegant solution, especially when it's something that can be toggled on and off using a flag. For example:

package Foo;

use strict;
use warnings;

sub new
  {
  my($class, $debug) = @_;
  my $self = {};
  bless($self, $class);
  if($debug)
    { $self->{'Debug'} = 1; }
  return $self;
  }

sub bar
  {
  my($self, $hashref, @arguments) = @_;
  unless(ref($hashref) eq 'HASH')
    {
    if($debug)
      { carp "ERROR: first argument to \'bar\' must be a hashref"; }
    return;
    }
  #insert code here
  return $result;
  }
[download]

I find carp most useful for these cases. Personally I feel a module should never die on its own, that's my decision...

---

Remember rule one...

to allow your module users to activate/deactivate warnings you can use warnings::register and warnings::enabled() instead of a custom aproach.