Bric::Util::Fault(3p)

NAME
Bric::Util::Fault - Bricolage Exceptions

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2006-09-16 02:39:13 +0200 (Sat, 16 Sep 2006) $

SYNOPSIS
  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";
      }
  }

DESCRIPTION
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 "maketext" field, which can be passed an array reference of values suitable for passing to Bric::Util::Language's "maketext()" method.

INTERFACE

  Constructors

$obj = Bric::Util::Fault->new($init);
    Creates a new Fault object for processing up the caller stack

    Keys of $init are:

    msg The exception message.

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

    maketext
        Supported by Bric::Util::Fault::Error and its subclasses. An array reference suitable for passing to Bric::Util::Language's "maketext()" method.

    Throws: NONE

    Side Effects: NONE.

    Notes:

    This method should only be used within a "die" context, and one of its subclasses (GEN, MNI, etc..) should be thrown instead. We want to change this so that you generally use the "throw" method instead.

  Destructors

$self->DESTROY
    Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

  Public Class Methods
None.

  Public Instance Methods

$str = $obj->error_info;
    Returns $obj->as_string.

    Throws: NONE.

    Side Effects: NONE.

    Notes: Overloads the double-quoted string operator.

$str = $obj->get_msg;
    Returns the message set by the programmer at error time.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$id = $obj->get_timestamp;
    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.

$id = $obj->get_filename;
    Returns the name of the file in which the error ocurred.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$id = $obj->get_line;
    Return the line number at which the error ocurred in the file returned by "get_filename()".

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$id = $obj->get_pkg;
    Returns the name of the package in which the error ocurred.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$id = $obj->get_payload;
    Returns the programmer-specified payload.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$id = $obj->get_stack;
    Returns the stack trace.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$err->throw(error => 'This is some error we are throwing');
    This overrides the "throw" 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.

$str = $obj->full_message;
    Overrides $obj->as_string to include the payload.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$str = $obj->as_string;
    Displays the exception object as a text string. Includes the output of "trace_as_text()".

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$str = $obj->trace_as_text;
    Displays the exception object's stack trace as text.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

  Public Functions

isa_bric_exception($err, 'MNI');
    This function tests whether the $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 $class"

    Side Effects: NONE.

    Notes:

    This function is imported into the calling class.

isa_exception($err);
    This function tests whether the $err argument is an Exception::Class exception.

    Throws:

    *   "no such exception class $class"

    Side Effects: NONE.

    Notes:

    This function is imported into the calling class.

rethrow_exception($err);
    This function rethrows the $err argument if it "can" 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.

PRIVATE

  Private Class Methods
NONE.

  Private Instance Methods
NONE.

  Private Functions
NONE.

NOTES
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>.

AUTHOR
Scott Lanning <lannings@who.int>

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