Pgreet::Error - Error handling object for Penguin Greetings.
# 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"
);
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.
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);
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.)
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()report is
called from a CGI application.report_daemon()report is
called from a ``faceless'' daemon.report_stderr()report is
called from standard command-line application._is_error()error_template()_LocalChangeVars()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 (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
No known bugs at this time.
Edouard Lagache <pgreetdev@canebas.org>
1.0.0
syslog, Pgreet, the Pgreet::Config manpage, the Log::Dispatch manpage, the Log::Dispatch::File manpage, the Log::Dispatch::Syslog manpage, the CGI::Carp manpage