NAME
gerr - Eureka Error System v1.1.7
SYNOPSIS
use gerr; # Standard usage
use gerr qw(:control); # Use to override warn and die
my $error_message = error("error message");
warn "This is a warning."; # Calls custom Warn function if :control is used
die "This is a fatal error."; # Calls custom Die function if :control is usedDESCRIPTION
The `gerr` module is designed to enhance error and debugging management in Perl scripts by providing custom error messages, stack traces, and handlers for warnings and fatal errors. It offers a consistent approach to handle errors and warnings, making debugging more manageable and informative.
The module includes functionalities to format error messages, capture and format stack traces, and replace default Perl warning and die functions with custom implementations when needed. This allows developers to gain deeper insights into issues within their scripts, including those that involve other modules and packages.
VERSION
Version 1.1.7
USAGE
To use the `gerr` module, include it in your Perl script with one of the following methods:
Standard Usage
use gerr;
# Generate a formatted error message
my $error_message = error("Something went wrong", "type=Error", "trace=3", "return=1");
# Output the error message
warn "This is a warning message.";
die "This is a fatal error message.";In this case, the `error` function will return a formatted error message but will not print or exit unless explicitly configured. `warn` and `die` will be handled by Perl's default warning and die handlers.
Using :control to Override warn and die
use gerr qw(:control);
# Generate a warning
warn "This is a warning message.";
# Generate a fatal error
die "This is a fatal error message.";When using the `:control` tag, the `warn` and `die` functions are overridden with custom implementations that format messages using the `error` function. This enables a consistent approach to error handling across your script, providing additional context such as stack traces for better debugging.
FUNCTIONS
error
error(@messages)The `error` function generates a formatted error message.
Arguments:
return=<value>: Set return boolean (default: 0, which will also exit the program)
type=<value>: Set error type (default: "FATAL ERROR")
size=<value>: Set size of formatted message (default: 78)
trace=<value>: Set trace depth (default: 2)
All other parts are considered as part of the error message itself.
Returns the formatted error message as a string.
trace
trace($depth)The `trace` function generates a stack trace with the given depth.
Arguments:
$depth: Depth of the stack trace (default: 1)
Returns the formatted stack trace as a string.
Warn
Warn($message)The `Warn` function provides a custom implementation for warnings. It formats the message and invokes the warning signal handler if defined.
Arguments:
$message: The warning message
Die
Die($message)The `Die` function provides a custom implementation for fatal errors. It formats the message and invokes the die signal handler if defined, and exits the program if not in an eval block.
Arguments:
$message: The fatal error message
CUSTOM ERROR HANDLING
Warn
The `Warn` function formats the warning message, includes the call location, and either invokes a custom warning handler if defined or prints the message to STDERR. This is useful when you want consistent formatting for warnings across your entire application, even when other modules are in use.
Die
The `Die` function formats the fatal error message, includes the call location, and either invokes a custom die handler if defined or prints the message to STDERR and exits the program if not in an eval block. By replacing `CORE::GLOBAL::die`, you ensure that all fatal errors, even those triggered by other modules or packages, are handled consistently.
EXPORT
By default, only the `error`, `Die` and `Warn` functions are exported. If you want to use custom warning and die handlers, use the `:control` tag.
ADVANCED USAGE
The `:control` tag enables overriding Perl's built-in `warn` and `die` functions with `Warn` and `Die` methods from `gerr`. This capability is particularly useful for debugging large applications or systems where you want to ensure that all warnings and errors, regardless of their origin, are handled consistently.
By leveraging `:control`, you can:
Ensure that all warnings and errors are formatted uniformly across your application, including messages from other modules or packages.
Capture and log detailed stack traces for better debugging and problem analysis.
Maintain consistent error handling behavior across different components of your application, providing a unified debugging experience.
Using the `:control` tag effectively allows you to centralize and standardize error and warning management, making it easier to diagnose and address issues across complex Perl applications.
COPYRIGHT AND LICENSE
Copyright (C) 2020 OnEhIppY, Domero Software