SYNOPSIS

If you want to catch an exception, whose class is YourExceptionClass, throwed by a class YourClass:

  use YourClass;
  use Message::Util::Error;
  
  my $obj = YourClass->new;
  
  try {
    $obj->method_that_throw_an_eception;
  } catch YourExceptionClass with {
    my $err = shift;
    if ($err->type eq 'NOT_SUPPORTED_ERR') {
      $err->throw; # die unless catched by upper-level |try| clause (if any)
    } else {
      warn $err;
    }
  };

If you want to build a class YourClass that throws an exception based on Message::Util::Error:

  package YourClass;
  
  sub method_that_throw_an_exception ($) {
    my $self = shift;
    report YourExceptionClass
        -object => $self,
        -type => 'EXAMPLE_ERR',
        -subtype => 'EXAMPLE_SPECIFIC_ERR';
  } # method_that_throw_an_exception
  
  ## |report| calls back this method.  If this method |throw|s
  ## the exception, then it is really thrown.
  sub ___report_error ($$) {
    my ($self, $err) = @_;
    if ($err->type_def->{level} eq 'warning') {
      warn $err;
    } else {
      $err->throw;
    }
  } # ___report_error
  
  package YourExceptionClass;
  use Message::Util::Error;
  push our @ISA, 'Message::Util::Error';
  
  sub ___error_def () {
    return {
      EXAMPLE_ERR => {
        -description => q<An example error condition>,
        -subtype => {
          EXAMPLE_SPECIFIC_ERR => {
            -description => q<A specific example error condition>,
          },
        },
        level => 'fatal',
      },
    };
  } # ___error_def

DESCRIPTION

Various manakai classes throws exceptions, in particular DOMExceptions in DOM implementation classes. In addition, it might report other kinds of errors, such as DOMError as defined in DOM Level 3 Core specification. This module, Message::Util::Error, provides an integrated framework for reporting exceptions, errors, warnings, and so on.

The Message::Util::Error exception framework is built on the top of the Perl module Error, which apply to Perl scripts the try and catch functionalities. Exceptions thrown using Message::Util::Error exception framework are also able to be catched by the catch clause as in the original Error module. For more information on usage for try, catch, and other clauses, see the documentatin for the Error module. This document describes some Message::Util::Error-specific conventions, mainly targeted for manakai module authors.

For other usages of the framework, such as DOMError, see documentation for each module.

This module is part of manakai.

ACCESSING ERROR INFORMATION

Loading `try` and `catch` Support

If you'd like to use try and catch clauses, you have to import these names by:

  use Message::Util::Error;

Note that the example above is equivalent to:

  use Error qw(:try);

except that in the former example Message::Util::Error module is also loaded if not yet.

Methods on Error Objects

Any method defined on an Error object is also available for Message::Util::Error objects with the same semantics (though some might be overridden). In addition, a few methods are added for Message::Util::Error objects.

$code = $err->code;

Returns the code of the error.

If the definition for the error type has a code associated, then it is returned. Otherwise, 0 is returned.

This method is added for DOM compatibility.

$subtype = $err->subtype;

Returns the subtype of the error, if specified when the error object is created, or undef otherwise.

$text = $err->text;

Returns the text of the error.

This method is defined in Error module but overridden. If the definition for the error subtype, if any, has a description, then it is returned. Otherwise, if the definition for the error type has a description, then it is returned. Otherwise, same as Error's definition, i.e. the text specified when the Error object is created, if any, or undef otherwise, is returned.

$text = $err->type;

Returns the type of the error specified when the error is created.

$def = $err->type_def;

Returns the definition for the error type, if any, or the definition for the UNKNOWN type, otherwise. For the content of the error type definition, see "Error Type Definitions". Applications MUST NOT modify the error type definition. If modified then the result is undefined and it might make the error handling behaviour inconsistent or incorrect.

$value = $err->value; $value = 0+$err;

Returns the value that can be associated with the error.

This method is defined in Error module but overridden. If the definition for the error type has a code associated, then it is returned. Otherwise, same as Error's definition, i.e. the value specified when the Error object is created, if any, or undef otherwise, is returned.

THROWING ERRORS

1. Define an error class.

2. Define the ___report_error method to the class whose methods will report errors. (REQUIRED if you use report.)

3. Define an error message template class. (REQUIRED if you want to extend the error message parameter set.)

4. Put report or throw where you want to report or throw an error.

5. Ensure the error class is loaded when any statement added by Step 4 is executed.

Error Classes

Error Type Definitions

Error type:

-code: Numeric error code for the type. If specified, it MUST be a number.
-description: A template that is used to create the description for an error with that type. @@ See @@ for template syntax.
-subtype: A reference to hash that contains pairs of error subtype nams and error subtype definitions. It MAY contain zero or more error subtypes.

Error subtype:

-description: A template that is used to create the description for an error with that subtype. @@ See @@ for template syntax.

Any other value starts with - is reserved for future extension and MUST NOT be used for any purpose until it is eventually defined. Values not start with - MAY be used for subclass-specific error type/subtype properties.

Throwing an Error

-def (MUST NOT be specified)

The definition for the error type.