YaBB3::Error - The error log.


Name

YaBB3::Error - The error log.


Synopsis

use YaBB3::Error;

# Setup the error object. $error = new YaBB3::Error({ 'debug' => 1, 'caller_offset' => 1, 'prefix' => ``YaBB3'', 'display_method' => sub {\&YaBB3::Display::DisplayError(@_);}, # Method to send error content to be displayed 'generic_display_method' => sub {\&YaBB3::Display::DisplayGenericError(@_);}, # Method to send GENERIC error content to be displayed });


return $error->errorDisplay( 'There has been an error')
        if $error->isError();


Overview

Generic extended error class for YaBB3. An error log of messages and associated actions. An error log is created and shared by a top-level script. Methods that encounter an error can log a message, an event type, and a set of actions to the error log. When control propogates back up to the top-level script, it can display the error log and run the actions. This can be used to display a user-friendly generic message to the user, log a detailed call stack to a text or server log, and even send critical error messages to a list of email or SMS addresses, all at the same time from the same error log.


Description

When a subroutine in a package encounters an error, it can log that error with text and associated actions using a reference to an error log object. This reference might be made available through an imported global variable, a class or object field, passed as a method argument, or in some other way.

The top-level script creates the error log object. The method that encounters an error logs it with some message text, an event type, and a set of associated actions. The event type, the source script filename, line number, sub-routine, package, and caller call frame information will automatically be included with the message text. The undef result is then returned to the caller, which indicates that an error was logged. The caller can then log any additional imformation and return the undef result to the next caller. This continues up the stack until, when we return to the top-level script, we have a complete stack of the method call frames. The top-level script can then return a composed error log report back to the user, and run the actions associated with the errors.

Creation and Configuration

An error log object is created with the new method. It takes a hash of the following configuration parameters as an argument that are saved in the PARAM hash field:

$PREFIX
A string of text that is prefixed to all error messages in this error log, like an application or thread name.

\&DISPLAY_METHOD
A reference to a subroutine/method that composes the given error text into a report that is displayed to the user. For example: a web page that is returned from a server to a client.

\&GENERIC_DISPLAY_METHOD
A reference to a subroutine/method that composes a configured GENERIC_MSG into a report that is displayed to the user. For example: a web page that is returned from a server to a client.

$GENERIC_MSG
A generic error message that can be used by the configured GENERIC_DISPLAY_METHOD.

$CALLER_OFFSET
The count of call frames up the stack to the failed subroutine (normally 1). This is where the error object will obtain the call frame information, like the source script line number and filename.

\@STACK
An initial set of logged error objects.

$LOG_CUSTOM
True if there is a configured custom log.

$LOGFILE
Host pathname of the custom log file.

\@EMAILS
An array of email addresses to be used by the email action. Critical errors can be emailed to the admin or maintenance addresses.

\@SMS_ADDRESSES
An array of SMS addresses to be used by the sms action. Critical errors can be messaged to the admin or maintenance addresses.

$DEBUG
True if the entire stack of logged errors should be displayed.

Error Logging

When a method encounters an error, it can use the error method to log the event along with a number of associated properties.

Error Display

A top-level script can display the current state of the error log in two ways:

  1. The errorDisplay method displays the highest main-display message in the call frame stack or a given message if there is none. This is used to provide error specific information to those knowledgable in the maintenance of the forum. The configured DISPLAY_METHOD is used to display the composed HTML text.

  2. The errorGenericDisplay method displays the configured GENERIC_MSG for any error. This is used to provide forum users with a more user-friendly error response. If a GENERIC_DISPLAY_METHOD is configured, it is used to display the composed HTML text, else the configured DISPLAY_METHOD is used.

After the composed text is displayed, the stack of actions is run. The entire stack of error messages is displayed if the configured DEBUG parameter is true.


Reference

Object Super Classes

  YaBB3::Base

Use Packages

  YaBB3::Error::Error

Package Fields

  $VERSION       The package version number as a float.

Instance Variables


=item \@stack

The stack of logged error objects. get_stack

\%last_error
The last error object logged.

$last_generic
The last error message logged.

$isError
True if an error has been logged. isError

$prefix
The string prefixed to all error messages. get_prefix

$caller_offset
The count of call frames up to the failed subroutine.

\@emails
An array of email addresses. sub get_emails

\@sms_adresses
An array of SMS addresses. get_sms_addresses

$log_custom
True if there is a custom log. get_log_custom

$logfile
Server path to the custom log file. get_logfile

\$display_method
The subroutine that displays errors.

\$generic_display_method
The subroutine that desplays generic errors.

\$generic_msg
A generic error message used by the GENERIC_DISPLAY_METHOD.

$debug
True if the entire stack of logged errors should be displayed.

Object Methods

new

  \%params  Configuration parameters:
              \@STACK                  An initial error log.
               $PREFIX                 The string prefixed to all error messages.
               $CALLER_OFFSET          The count of call frames up to the failed subroutine.
              \@EMAILS                 An array of email addresses.
              \@SMS_ADDRESSES          An array of SMS addresses.
               $LOG_CUSTOM             True if there is a custom log.
               $LOGFILE                Server path to the custom log file.
              \&DISPLAY_METHOD         The subroutine that displays errors.
              \&GENERIC_DISPLAY_METHOD The subroutine that desplays generic errors.
               $GENERIC_MSG            A generic error message used by the GENERIC_DISPLAY_METHOD.
               $DEBUG                  True if the entire stack of logged errors should be displayed.
  Returns
  \%        The new object reference.

Create a new error log object with the given configuration parameters.

error

  $error     Error message.
  $type      [Opt] Error type from YaBB3::Error::errorTypes.
  /%actions  [Opt] Actions with keys from YaBB3::Error::actionTypes.
  $runstack  [Opt] True if the stack of actions should be run.
  Returns
  undef      Indicates to the caller that an error was logged.

Log an error to this object's error stack. The given error message is combined along with source script call frame information into the logged error message. The stack of actions is run if the given $runstack is true.

It is intended that the failing subroutine return the returned undef value of this method to the caller, indicating that an error was logged.

errorDisplay

  $msg            [Opt] The error message.
  $force_display  [Opt] True if the given message should override any logged 'main-display' message.
  \%config        [Opt] Display configuration parameters.
  Returns
  undef      Indicates to the caller that an error was logged.

Compose as HTML and display the first logged 'main-display' message, or the given message using the configured DISPLAY_METHOD subroutine. The given message is used if there is no 'main-display' message, or if $force_display is true.

If the DEBUG configuration parameter is true, the entire stack of error messages will be included.

The given hash of display parameters is passed directly to any configured DISPLAY_METHOD display subroutine.

It is intended that the failing subroutine return the returned undef value of this method to the caller, indicating that an error was logged.

errorGenericDisplay

  $error     The error message.
  $type      [Opt] Error type from YaBB3::Error::errorTypes.
  /%actions  [Opt] Actions with keys from YaBB3::Error::actionTypes.
  Returns
  undef      Indicates to the caller that an error was logged.

Compose as HTML and display the first logged 'main-display' message, or a generic message using either the configured DISPLAY_GENERIC_METHOD subroutine or the configured DISPLAY_METHOD subroutine.

If the DEBUG configuration parameter is true, the entire stack of error messages will be included.

It is intended that the failing subroutine return the returned undef value of this method to the caller, indicating that an error was logged.

subError

  $msg     [Opt] The error text.
  Returns
  undef    Indicates a logged error to the caller.

Logs the given error message and runs the stack of actions. This is intended to log errors generated internally by the error log or error objects.

UBBCParse

  $msg     The text to be parsed.
  Returns
  $        The converted text.

Converts each UBB Code to an HTML equivalent.

UBBCParseOut

  $msg     The text to be parsed.
  Returns
  $        The converted text.

Removes all UBB Codes from the given text.


Author

Brian Hann (c0bra@users.sourceforge.net) Torsten Mrotz (tmrotz@yabbforum.com)

Copyright ©2000-2005, YaBB 3 Development Team. All Rights Reserved.
You may distribute this module under the terms of YaBB 3.
 YaBB3::Error - The error log.