NAME

Merror - OOP errorhandling with stacktracing ability

VERSION

1.4

SYNOPSIS

use Merror;

function create_error {
		my $obj = Merror->new(stackdepth => 16);
		#indicate that an error happened
		$obj->error(1);
		#set an error code
		$obj->ec(-1);
		#set an error description
		$obj->et("This is an error message");
		return($obj);
}

my $error_obj = create_error();
#check if an error occured
if($error_obj->error()) {
		#print out the errorcode (-1)
		print("Errorcode: " . $obj->ec() ."\n");
		#print out the error description (This is an error message)
		print("Error description: " . $obj->et() . "\n");
		#print out the captured stacktrace
		$obj->stacktrace();
} else {
		print("No error occured\n");
}

DESCRIPTION

Merror gives you the ability to throw and catch errors in an OOP way. That means if you dont catch errors probably your code will continue running. One big feature of Merror is that it captures a stacktrace when an error occured that you can print out.

METHODS

new(option => value, ...)

Constructor.

Example:
my $obj = Merror->new( stackdepth => 64 );

the following options are available:

stackdepth

Number defining the maximum tracing depth of a stacktrace.

# example: define tracingdepth of 64
stackdepth => 64

errorfile

Name of a file containing you errormapping, See section ERRORFILE for more information about the syntax of the file.

# example: define errorfile C</etc/merror/testerrors>
errorfile => C</etc/merror/testerrors>

ramusage

If set to an value other than undef or false the complete mapping of a given errorfile will be held in RAM instead of parsing it new every time you call an errorcode or error descrption.

# example: define ramusage
ramusage => 1

error(indicate)

Call this method with 1 as parameter indicate to indicate that an error happened. You can fetch the error state by calling this method without any paramter. It returns 1 if an error occured or 0 if not.

Example:
my $obj = Merror->new(stackdepth => 10, errorfile => C</etc/merror/errorfile>, ramusage=>0);

...

#if you formerly called $obj->error(1) than this query whill return 1
if($obj->error()( {
		...
}

ec(errorCode)

If you call this method with a number this will set the errorcode. Call it without any parameter to get the last errorcode back.

Example:
# set error code -255
$obj->ec(-255);
# print out the last errorcode
print($obj->ec()."\n");

et(errorDescription)

Call this method with a string paramter and this string will be set as the error description. Call it without any parameter to get back the last error description.

Example:
# set error description
$obj->et("Fatal unresolvable error occured");
# print out the last error description
print($obj->et()."\n");

mappedError(errorCode)

This method searches the errorfile for errorCode and sets the errorcode and error description from the mapping

Example:
# we got the following mapping in our errorfile: 24: Could not connect to given host
# set error code and description depending on the mapping
$obj->mappedError(24);
# print out the errorcode: 24
print($obj->ec()."\n");
# print out the error description: Could not connect to given host
print($obj->et()."\n");

stacktrace

Prints out the caputed stacktrace.

return_stacktrace

Returns the captured stacktrace as an array where every element is one level ov the stacktrace

Example:
my @st = $obj->return_stacktrace();
foreach (@st) {
		print("$_\n");
}

merror_copy(destinationStructure)

You can treat this method as an copy-operator for Merror structures. It will copy the complete internal state ob the calling object into an hash reference indicated by destionationStructure

Example:
use Merror;
my $obj = Merror->new();
$obj->ec(13);
$obj->et("Test error");

# will print out: 13
print($obj->ec()."\n");
# will print out: Test error
print($obj->et()."\n");

# now copy the internal state
my $obj2 = {};
$obj->merror_copy($obj2);

# will print out: 13
print($obj2->ec()."\n");
# will print out: Test error
print($obj2->et()."\n");

ERRORFILE

By defining a file in the constructor parameter errorfile you have the ability to use this file for your error descriptions. The syntax of every line of the file is:

[Errorcode]: [Errordescription]
-255: Unknown Error occurred

Lines starting with a # will be ignored. Every line will be parsed through this regular expression:

/^(\d{1,})\s{0,}:\s{0,}(.*)/

BUGS

None known

ACKNOWLEDGEMENTS

If you find any bugs or got some feature you wish to have implemented please register at mantis.markus-mazurczak.de.

COPYRIGHT

See README.

AVAILABILITY

You can allways get the latest version from CPAN.

AUTHOR

Markus Mazurczak <coding@markus-mazurczak.de>