Bric::Util::Fault(3p) User Contributed Perl DocumentationBric::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:

           o   "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:

           o   "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



perl v5.12.2                      2006-09-15             Bric::Util::Fault(3p)
