Name

Bric::Util::Fault - Bricolage Exceptions

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:

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:

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