ePages 6.11.0 - DE_EPAGES/Core/API/Warning.pm

Package DE_EPAGES::Core::API::Warning

This module provides warning handling. Warning messages are formatted using a template which is defined by ErrorDefinition function in the module that threw a warning. The template may contain placeholders for additional information, such as file name, SQL statement or other information that may be useful for tracking a warning. These parameters are passed to the Warning function. The function BlockWarnings allows to collect the appearing warnings. If a warning appears outside a warning block, the warning will be printed to the log. Please look in the log3perl.conf if the module or function prints warnings and in which appender.

Base
DE_EPAGES::Core::API::Error
Example
use DE_EPAGES::Core::API::Warning qw( BlockWarnings Warning );

# How to define error codes and message templates

sub ErrorDefinition { return {
    MissingParameter => 'Missing parameter #Parameter',
    ValueTooLong     => 'Value length #Length is larger than #MaxLength'
}}

# How to throw warnings

sub MyFunction {
    my ( $Name, $Value ) = @_;
    Warning( MissingParameter => { Parameter => 'Name' } ) unless defined $Name;
    Warning( ValueTooLong => {
        Length    => length $Value,
        MaxLength => 25
    } ) if length $Value > 25;
}
my $aWarnings = BlockWarnings( sub {
   MyFunction();
});
# print first warning
print ($aWarnings->[0]->message if scalar @$aWarnings;
@EXPORT_OK
Warning
WarnHandler
BlockWarnings

Functions

BlockWarnings
WarnHandler
Warning

BlockWarnings

The function BlockWarnings allows to collect the appearing warnings. If a warning appears outside a warning block, the warning will be printed to the log. Please look in the log3perl.conf if the module or function prints warnings and in which appender.

Syntax
my $aWarnings = BlockWarnings( $cSub, $aWarningCodes );  # collect warnings
my ($aWarnings, $TooManyWarnings) =
BlockWarnings( $cSub, $aWarningCodes, $MaxWarnings );  # collect warnings
Input
$cSub (ref.code)
code reference for execution
$aWarningCodes (ref.array)
block only this codes (optional)
$MaxWarnings (integer)
maximum number of warnings (optional)
Return
$aWarnings (ref.array)
Warnings which have occured
$TooManyWarnings (boolean)
true if more than the maximum number of warnings
occured (optional)

WarnHandler

Sets Warning function as handler for the __WARN__ signal. It converts a native "warn" into a Warning object.

Syntax
WarnHandler( $Message )
Example
$SIG{__WARN__} = \&DE_EPAGES::Core::API::Warning::WarnHandler;
Input
$Message (string)
the error message that was passed to the "warn" function.

Warning

Call this function to raise a warning. In case of a 'warn' warning, the function WarnHandler will generate the warning object automatically. The Warning function may also be called to escalate a warning. Then it gets the warning object as only parameter. It's possible to collect the warnings and prevent the loggging with BlockWarnings.

Syntax
Warning( $Code, $hVars );  # report a new warning
Warning( $Warning );       # escalating an unhandled warning
Example
Warning( MissingParameter => { Param => 'CatalogID' } ) unless $CatalogID;
Warning( 'Timeout' );
Warning( $Warning ) unless $Warning->code eq 'Timeout';
Input
$Code (string)
The $Code parameter can hold an arbitrary string as short code for
the warning. This code must be defined inside an "ErrorDefinition"
function inside the module that calls this function.
$Code can be a Warning object. In this case the warning will be
escalated to the next level of eval.
$hVars (string)
An optional hash reference that holds any additional parameters.
These values are used to replace parameters in the warning message
template.