SYNOPSIS

  use Dancer::Exception qw(:all);

  # raise an exception
  raise E_HALTED;

  # get a list of possible exceptions
  my @exception_names = list_exceptions;

  # catch an exception
  eval { ... };
  if ( my $value = is_dancer_exception(my $exception = $@) ) {
    if ($value == ( E_HALTED | E_FOO ) ) {
        # it's a halt or foo exception...
    }
  } elsif ($exception) {
    # do something with $exception (don't use $@ as it may have been reset)
  }

DESCRIPTION

This is a lighweight exceptions module. Yes, it's not Object Oriented, that's on purpose, to keep it light and fast. Thus, you can use ref() instead of ->isa(), and exceptions have no method to call on. Simply dereference them to get their value

An exception is a blessed reference on an integer. This integer is always a power of two, so that you can test its value using the | operator. A Dancer exception is always blessed as 'Dancer::Exception'.

EXPORTS

to be able to use this module, you should use it with these options :

  # loads specific exceptions only. See list_exceptions for a list
  use Dancer::Exception qw(E_HALTED E_PLOP);

  # loads the utility functions
  use Dancer::Exception qw(raise list_exceptions is_dancer_exception register_custom_exception);

  # this does the same thing as above
  use Dancer::Exception qw(:utils);

  # loads all exception names, but not the utils
  use Dancer::Exception qw(:exceptions);

  # loads only the internal exception names
  use Dancer::Exception qw(:internal_exceptions);

  # loads only the custom exception names
  use Dancer::Exception qw(:custom_exceptions);

  # loads everything
  use Dancer::Exception qw(:all);

FUNCTIONS

raise

  raise E_HALTED;

Used to raise an exception. Takes in argument an integer (must be a power of 2). You should give it an existing Dancer exception.

list_exceptions

  my @exception_names = list_exceptions;
  my @exception_names = list_exceptions(type => 'internal');
  my @exception_names = list_exceptions(type => 'custom');

Returns a list of strings, the names of available exceptions.

Parameters are an optional list of key values. Accepted keys are for now only type, to restrict the list of exceptions on the type of the Dancer exception. type can be 'internal' or 'custom'.

is_dancer_internal_exception

  # test if it's a Dancer exception
  my $value = is_dancer_exception($@);
  # test if it's a Dancer internal exception
  my $value = is_dancer_exception($@, type => 'internal');
  # test if it's a Dancer custom exception
  my $value = is_dancer_exception($@, type => 'custom');

This function tests if an exception is a Dancer exception, and if yes get its value. If not, it returns void

First parameter is the exception to test. Other parameters are an optional list of key values. Accepted keys are for now only type, to restrict the test on the type of the Dancer exception. type can be 'internal' or 'custom'.

Returns the exception value (which is always true), or void (empty list) if the exception was not a dancer exception (of the right type if specified).

register_custom_exception

  register_custom_exception('E_FROBNICATOR');
  # now I can use this exception for raising
  raise E_FROBNICATOR;

INTERNAL EXCEPTIONS

E_GENERIC

A generic purpose exception. Not used by internal code, so this exception can be used by user code safely, without having to register a custom user exception.

E_HALTED

Internal exception, generated when halt() is called (see in Dancer POD).

CUSTOM EXCEPTIONS

In addition to internal (and the generic one) exception, users have the ability to register more Dancer exceptions for their need. To do that, see register_custom_exception.