NAME

Unix::Conf::Err - This module is an internal module for error handling purposes.

SYNOPSIS

Refer to the documentation of Unix::Conf for creating error objects. Accessing the class constructor for Unix::Conf::Err is not preferred as the location of the class and consequently its namespace might change. The preferred way is

   use Unix::Conf;
   sub foo ()
   {
      return (Unix::Conf::->_err ('chdir')) 
      unless (chdir ('/etc'));
   }

   # or 

   sub foo ()
   {
      return (
         Unix::Conf::->_err (
            'object_method', 
            'argument not an object of class BLAH'
         )
      ) unless (ref ($obj) eq 'BLAH');
   }

In the calling function, save the return value, test it for truth, print error message on STDERR and continue.

   $ret->warn ("Error executing foo ()") 
   unless (($ret = foo ()));

Increase debugging information to print the cause of error and a full stacktrace and die.

   unless (($ret = foo ())) {
      $ret->debuglevel (2);
      $ret->die ("Error executing foo");
   }

Get state information from the error object and use it to print error ourselves instead of using the provided 'warn' and 'die' methods.

   use CGI;
   my $q = new CGI;
   # do stuff
   unless (($ret = foo ())) {
      my $stacktrace = $ret->stacktrace ();
      $stacktrace =~ s/\n/<BR>/g;
      print     $q->header ('text/html'),
      $q->start_html ( "Error" ),
      $q->h1 ( "Error" ),
      $q->p ( "Could not execute foo ()<BR>"),
      $q->p ( "because<BR>" ),
      $q->p ( $ret->errmsg () ),
      $q->p ("at<BR>"),
      $q->p ( $ret->where () ),
      $q->p ($stacktrace);
      $q->end_html;
      exit;
   }
        

DESCRIPTION

A Unix::Conf::Err object saves the state of the call stack at the time its creation. The idea behind a Unix::Conf::Err object style error handling is allowing the caller to decide how to handle the error without using eval blocks around all Unix::Conf::* library calls. The error object can be used to throw exceptions too, as the string operator is overloaded to return the error string, depending on the debuglevel.

new ()

 Arguments
 PREFIX,
 ERRMSG,

Unix::Conf::Err class constructor. If ERRMSG is not specified, a stringified version of "$!" is used. Using Unix::Conf::Err->new is deprecated. The preferred way to create a Unix::Conf::Err object is to use the Unix::Conf->_err method. Call Unix::Conf->_err () at the point of error so that it will store error data/stack at the time of error to be used later.

debuglevel ()

 Arguments 
 DEBUGLEVEL,

This method can be invoked through both a class and object. When invoked through Unix::Conf, it sets the class wide debuglevel to the argument. When invoked through an object, it sets only the object private debuglevel to the argument. In case both debuglevels are set, error message is printed at the maximum of the class wide debuglevel and object specific debuglevel. Valid values for DEBUGLEVEL are 0, 1, and 2. At level 0 only only the string passed to warn ()/die () methods are printed. At 1, the output of errmsg () and where () is added. At level 2, the output of stacktrace () is added to the output.

where ()

Prints information about the stack frame in which the error occured along with the line number and file.

why ()

Prints "PREFIX: ERRMSG".

stacktrace ()

Prints the complete stacktrace information at the time of creation of the object.

warn ()

 Arguments 
 ERRMSG,

Prints ERRMSG to STDERR.

die ()

 Arguments 
 ERRMSG,

Prints ERRMSG to STDERR and die's.

BUGS

None that I know of.

LICENCE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc. :

59 Temple Place, Suite 330, Boston, MA 02111-1307

COPYRIGHT

Copyright (c) 2002, Karthik Krishnamurthy <karthik.k@extremix.net>.