Bric::Util::Fault - Bricolage Exceptions

$LastChangedRevision$

$LastChangedDate: 2005-04-12 13:25:09 -0700 (Tue, 12 Apr 2005) $

  use Bric::Util::Fault qw(throw_gen);

  eval {
      # Do something that causes general mayhem.
      throw_gen(error => 'Ro-ro!');
  };

  if (my $err = $@) {
      print "Oh-oh, something faulted. Let's look at it...";
      print "Type:      ", ref $err, "\n";
      print "Message:   ", $err->get_msg, "\n";
      print "Payload:   ", $err->get_payload, "\n";
      print "Timestamp: ", $err->get_timestamp, "\n";
      print "Package:   ", $err->get_pkg, "\n";
      print "Filename:  ", $err->get_filename. "\n";
      print "Line"      ", $err->get_line, "\n";

      print "Stack:\n";
      foreach my $c (@{ $err->get_stack }) {
          print "\t", (ref $c ? join(' - ', @{$c}[1,3,2]) : $c), "\n";
      }
  }

This class does Exceptions for Bricolage. It replaces a home-grown implementation with one based on Exception::Class (which is what HTML::Mason uses). For now, we are merely emulating the previous functionality, so the above synopsis should still be valid, but this will change as we use more features of Exception::Class and try to clean exception usage throughout the Bricolage API code.

There are currently two major classes of exceptions: Bric::Util::Fault::Exception and its subclasses represent fatal, non-recoverable errors. Exceptions of this sort are unexpected, and should be reported to an administrator or to the Bricolage developers.

Bric::Util::Fault::Error and its subclasses represent non-fatal errors triggered by invalid data. These can be used to let users know that the data they've entered is invalid. To support this usage, Bric::Util::Fault::Error and its subclasses offer the CWmaketext field, which can be passed an array reference of values suitable for passing to Bric::Util::Language's CWmaketext() method.

$obj = Bric::Util::Fault->new($init);

Creates a new Fault object for processing up the caller stack Keys of CW$init are:

msg

The exception message.

payload

Extra error information, e.g., from CW$! or CW$@.

maketext

Supported by Bric::Util::Fault::Error and its subclasses. An array reference suitable for passing to Bric::Util::Language's CWmaketext() method. Throws: NONE Side Effects: NONE. Notes: This method should only be used within a CWdie context, and one of its subclasses (GEN, MNI, etc..) should be thrown instead. We want to change this so that you generally use the CWthrow method instead.

$self->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

None.

Returns CW$obj->as_string. Throws: NONE. Side Effects: NONE. Notes: Overloads the double-quoted string operator. Returns the message set by the programmer at error time. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the timestamp of the error. The timestamp is the epoch time of the error - the number of seconds since January 1, 1970. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the name of the file in which the error ocurred. Throws: NONE. Side Effects: NONE. Notes: NONE. Return the line number at which the error ocurred in the file returned by CWget_filename(). Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the name of the package in which the error ocurred. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the programmer-specified payload. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the stack trace. Throws: NONE. Side Effects: NONE. Notes: NONE.

$err->throw(error => 'This is some error we are throwing');

This overrides the CWthrow method in Exception::Class so that if we create a new exception from a Bric or HTML::Mason exception, we will just use the short error message. Otherwise, exceptions can get stringified more than once. Throws: NONE. Side Effects: NONE. Notes: NONE. Overrides CW$obj->as_string to include the payload. Throws: NONE. Side Effects: NONE. Notes: NONE. Displays the exception object as a text string. Includes the output of CWtrace_as_text(). Throws: NONE. Side Effects: NONE. Notes: NONE. Displays the exception object's stack trace as text. Throws: NONE. Side Effects: NONE. Notes: NONE.

isa_bric_exception($err, 'MNI');

This function tests whether the CW$err argument is a Bricolage exception. The optional second argument can be used to test for a specific Bricolage exception. Throws:

*

no such exception class CW$class Side Effects: NONE. Notes: This function is imported into the calling class.

isa_exception($err);

This function tests whether the CW$err argument is an Exception::Class exception. Throws:

*

no such exception class CW$class Side Effects: NONE. Notes: This function is imported into the calling class.

rethrow_exception($err);

This function rethrows the CW$err argument if it CWcan rethrow (i.e. it is a Bricolage or HTML::Mason exception). Throws: NONE. Side Effects: NONE. Notes: This function is imported into the calling class.

NONE.

NONE.

NONE.

This was muchly copied from HTML::Mason::Exceptions. This replaces the home-grown exception handling written by matthew d. p. k. strelchun-lanier <matt@lanier.org>.

Scott Lanning <lannings@who.int>

Exception::Class, Devel::StackTrace, HTML::Mason::Exceptions