NAME

Bric::Util::Fault - base class for all Exceptions

VERSION

$Revision: 1.8 $

DATE

$Date: 2002/08/30 22:13:41 $

SYNOPSIS

eval {
    # Do something that causes general mayhem.
    die Bric::Util::Fault::Subclass->new({ msg => '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";
    }

    print "Environment:\n";
    while (my ($k, $v) = each %{ $err->get_env }) {
        print "\t$k => $v\n";
    }
}

DESCRIPTION

Bric::Util::Fault is the base class for all Bricolage Exceptions. Do not use this class directly if you are looking for an exception to throw. Rather, look at Bric::Util::Fault::Exception.

Whereas earlier perl versions could only die ('string'), perl 5.005 and beyond can die ($obj). This object can contain rich state information which enables the calling eval {} to perform more varied object introspection. This also avoids the proliferation of error strings, and makes catching errors very simple.

INTERFACE

Constructors

$obj = new Bric::Util::Fault($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 $@.

Throws:

Um, this can't really throw itself. or can it? i dunno.

Side Effects: NONE.

Notes:

This method should only be used within a 'die' context, and one of its subclasses should be thrown instead.

Destructors

$self->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Public Class Methods

Public Instance Methods

$string = $obj->error_info;

Returns error string of type "pkg -- filename -- line -- msg". Also called when the exception object is used in a string context.

Throws: NONE.

Side Effects: NONE.

Notes: Overloads the double-quoted string operator.

$id = $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_env;

Returns a hash reference of the contents of %ENV at time of error.

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.

#------------------------------------------------------------------------------#

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

NONE.

NOTES

This is the only class file that should use the die operator. Everyone else should use the interface specified above.

AUTHOR

matthew d. p. k. strelchun-lanier - matt@lanier.org

SEE ALSO

Bric, Bric::Util::Fault::Exception

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 179:

You forgot a '=back' before '=head2'

Around line 181:

'=item' outside of any '=over'

Around line 194:

You forgot a '=back' before '=head2'

Around line 205:

'=item' outside of any '=over'