=pod

=head1 NAME

gerr - Eureka Error System v1.1.7

=head1 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 used

=head1 DESCRIPTION

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.

=head1 VERSION

Version 1.1.7

=head1 USAGE

To use the `gerr` module, include it in your Perl script with one of the following methods:

=head2 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.

=head2 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.

=head1 FUNCTIONS

=head2 error

    error(@messages)

The `error` function generates a formatted error message.

=head3 Arguments:

=over 4

=item * return=<value>: Set return boolean (default: 0, which will also exit the program)

=item * type=<value>: Set error type (default: "FATAL ERROR")

=item * size=<value>: Set size of formatted message (default: 78)

=item * trace=<value>: Set trace depth (default: 2)

=item * All other parts are considered as part of the error message itself.

=back

Returns the formatted error message as a string.

=head2 trace

    trace($depth)

The `trace` function generates a stack trace with the given depth.

=head3 Arguments:

=over 4

=item * $depth: Depth of the stack trace (default: 1)

=back

Returns the formatted stack trace as a string.

=head2 Warn

    Warn($message)

The `Warn` function provides a custom implementation for warnings. It formats the message and invokes the warning signal handler if defined.

=head3 Arguments:

=over 4

=item * $message: The warning message

=back

=head2 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.

=head3 Arguments:

=over 4

=item * $message: The fatal error message

=back

=head1 CUSTOM ERROR HANDLING

=head2 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.

=head2 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.

=head1 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.

=head1 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:

=over 4

=item * Ensure that all warnings and errors are formatted uniformly across your application, including messages from other modules or packages.

=item * Capture and log detailed stack traces for better debugging and problem analysis.

=item * Maintain consistent error handling behavior across different components of your application, providing a unified debugging experience.

=back

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.

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2020 OnEhIppY, Domero Software

=cut

