Bric::Util::Fault - Bricolage Exceptions $LastChangedRevision$ $LastChangedDate: 2006-09-16 02:39:13 +0200 (Sat, 16 Sep 2006) $ 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 "maketext" field, which can be passed an array reference of values suitable for passing to Bric::Util::Language's "maketext()" method.

Constructors
Creates a new Fault object for processing up the caller stack Keys of $init are: The exception message. Extra error information, e.g., from $! or $@. 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
Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Public Class Methods
None.

Public Instance Methods
Returns $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 "get_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. 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. Overrides $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 "trace_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.

Public Functions
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. 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. 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 Class Methods
NONE.

Private Instance Methods
NONE.

Private Functions
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