/ 
Pgreet-0.9.9
River stage zero No dependents
/ Pgreet::Error

NAME

Pgreet::Error - Error handling object for Penguin Greetings.

SYNOPSIS

# Constructor:
$Pg_error = new Pgreet::Error($Pg_default_config, 'CGIApp');

# Attach new CGIUtils object to Error obj.
$Pg_error->add_cgi_obj($Pg_cgi);


# Error reporting:
$Pg_error->report('level',
                  "any number of diagnostic message",
                  "lines"
                 );

DESCRIPTION

The module Pgreet::Error is the Penguin Greetings context-independent error handling module. This module uses the same syntax whether being called from a "faceless" daemon, a CGI application, or a command line utility. More importantly, library routines calling the error object passed as a parameter can correctly output to the appropriate venue. This module was necessary so that Penguin Greetings could use common code between: pgreetd the ecard managing daemon, pgreet.pl.cgi the CGI application, and utilities like PgTemplateTest.

The whole purpose of the module is to simplify the matter of handling errors. Once the object is constructed, calls to the error module are styled after syslog entries. Depending on the type, different methods will actually be used to output the error message. In the case of a daemon error, the errors will be logged to the Penguin Greeting log file and if the problem is serious enough the syslog facility (usually messages log file.) If the error occurs while running as a CGI application, the error will be handled using the Perl modules CGI:Carp and if severe enough, an error template will be displayed, Otherwise, the error message is simply displayed to Standard Output in a reasonable format.

CONSTRUCTING AN ERROR OBJECT

The Pgreet::Error constructor expects two parameters. The first is a Penguin Greeting configuration object. The second is descriptor of the type of application is creating the object. There are three recognized types: daemon (for a application daemon like pgreetd,) CGIApp (for a CGI application, Speedy CGI application, etc. like pgreet.pl.cgi,) and App (for a command line application like PgTemplateTest.) For example, creating an error object for a CGI application would be as follows:

$Pg_error = new Pgreet::Error($Pg_default_config, 'CGIApp');

From that point on, this error object can be used to report errors in the application that created it and passed on to other modules so that errors occurring in those modules will be handled consistently.

New to version 0.9.2 is a method to attach a Pgreet::CGIUtils object to the error object. The method to do this is simply: add_cgi_obj, and takes a single argument, a reference to the Pgreet::CGIUtils object. A sample call is provided below:

# Attach new CGIUtils object to Error obj.
$Pg_error->add_cgi_obj($Pg_cgi);

ERROR REPORTING SYNTAX

Once the object is set up, there is only one method that developers should ever use from this module - it is the report method. The report method takes a error level (from syslog) and any number of Perl expressions and outputs a string in the appropriate venue. If the error is severe enough, report will cause the program to halt in a manner appropriate to the way the program is called. If called from a CGI application, report can output an HTML template with an error message based on a supplied error number. A sample call to report is below:

# Error reporting:
$Pg_error->report('level',
                  "any number of diagnostic message",
                  "lines"
                 );

Unfortunately, the rich variation in possible error levels for syslog are nor mirrored elsewhere. Pgreet::Error maps the error levels: 'error', 'critical', 'alert', and 'emergency' to a "die" scenario and will cause the application to halt in an appropriate way. All other levels are considered a 'warning' scenario, reported, but the program is allowed to continue.

There is an additional variation for CGI applications. CGI applications interact with the users who may not speak geek or even English. Therefore the text of error messages is configurable via the template system that is used for all other user interactions. To indicate which template message to display, an error number is defined that content developers can then create their own template error messages around. So indicate that an error template should be displayed, the report function looks to see if the first error "message" is in fact a number. If so, and the error level is a die scenario, then error template is displayed corresponding to that error number and the CGI application halts. For example, should a user enter an incorrect access password the following call is made to report:

$Pg_error->report('error', 110,
                  "Attempt to login with invalid login/password pair"
                 );

Note that if the error object is called in a die scenario, the Penguin Greetings error object dies within the object itself. This is admittedly harder to debug, but is impossible to avoid in order to handle error condition correctly in code that does not "know" what sort application called it (shared libraries that are used by the daemon, CGI Application, etc.)

OTHER METHODS

There is no obvious reason why any method besides report would never need to be used within Pgreet::Error. However, the following methods are noted for completeness:

report_cgi()

Method that does the work when report is called from a CGI application.

report_daemon()

Method that does the work when report is called from a "faceless" daemon.

report_stderr()

Method that does the work when report is called from standard command-line application.

_is_error()

Convenience predicate that returns true if argument is one of the following error levels: 'error', 'critical', 'alert', or 'emergency'

error_template()

method to send an error message out via the content developers Embperl template.

_LocalChangeVars()

A "stub" routine to replace the Pgreet::CGIUtils ChangeVars method if report is called before the Pgreet::CGIUtils object has been attached to the report object. It is sufficient for the extreme cases when such a call might be made, but should basically be never used if the software if functioning correctly and configuration files are "reasonable."

COPYRIGHT

Copyright (c) 2003-2005 Edouard Lagache

This software is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html

BUGS

No known bugs at this time.

AUTHOR

Edouard Lagache <pgreetdev@canebas.org>

VERSION

0.9.9

SEE ALSO

syslog, Pgreet, Pgreet::Config, Log::Dispatch, Log::Dispatch::File, Log::Dispatch::Syslog, CGI::Carp