/ 
Math-ModInt-0.002
River stage one • 1 direct dependent • 1 total dependent
/ Math::ModInt::Event

NAME

Math::ModInt::Event - managing events triggered by Math::ModInt

VERSION

This documentation refers to version 0.001 of Math::ModInt::Event.

SYNOPSIS

# application interface:

use Math::ModInt qw(mod);
use Math::ModInt::Event qw(UndefinedResult DifferentModuli AnyEvent);

$a = mod(0, 2);
$b = mod(1, 3);

$trap = DifferentModuli->trap('warn');
$c = $a + $b;          # warns
undef $trap;
$c = $a + $b;          # remains silent

UndefinedResult->trap('die');         # define a static trap
$c = $a->inverse;      # raises exception (i.e. calls "die")

sub my_handler {
    my ($event, @details) = @_;
    # ... insert code here ...
    return 1;          # boolean, whether other handlers may be called
}

$trap = AnyEvent->trap( \&my_handler );
$c = $a + $b;         # calls my_handler(DifferentModuli, $a, $b)
$c = $a->inverse;     # calls my_handler(UndefinedResult)

# library module interface:

UndefinedResult->raise;
DifferentModuli->raise($this, $that);

DESCRIPTION

By default, Math::ModInt does not raise exceptions or issue warnings on arithmetic faults or incompatible operands. It just replaces the result of the faulty expression by a special object representing an undefined value.

Math::ModInt::Event can be used to alter this behaviour. It provides hooks to trap occurences of undefined results or incompatible operands. Applications can opt to have warning messages issued on STDERR, exceptions raised, or custom event handlers called upon these events.

Other types of errors can be trapped similarly, but will always raise exceptions if no active traps do so. The general rule is that errors are considered recoverable where a Math::ModInt object can convey the error condition, and unrecoverable where conversions to and from Math::ModInt are involved or the application interface is formally violated.

Constructors

Available event types are accessible through class methods with one of the names listed below. They form a hierarchical structure with AnyEvent at the root.

These constructors can also be imported and called like plain parameter-less subroutines.

UndefinedResult

UndefinedResult returns a Math::ModInt::Event object representing events that occur when an arithmetic expression yields an undefined result.

DifferentModuli

DifferentModuli returns a Math::ModInt::Event object representing events that occur when operands with different moduli are mixed within a single expression. Such operands are incompatible. Handlers will receive both operands as extra parameters.

Recoverable

Recoverable returns an event object representing any recoverable event, i.e. UndefinedResult and DifferentModuli.

UsageError

UsageError returns an event object representing usage error events. Events of this type are triggered if a method detects being called with incorrect parameters. Note that not any conceivable kind of wrong usage can be detected this way -- it may just as soon trigger a simple perl runtime error. Handlers will get a hint text indicating what was wrong as an extra parameter.

Nonexistent

Nonexistent returns an event object representing access to nonexistent object attributes. In particular, residue and modulus of the undefined Math::ModInt placeholder object are nonexistent. The extra handler parameter is a hint text indicating which attribute could not be accessed.

LoadingFailure

LoadingFailure returns an event object signalling problems to load an extension that had been available at the time Math::ModInt was installed, but not anymore. The extra handler parameter is the package name of the defunct extension. You probably need to re-install Math::ModInt to resolve the situation.

Unrecoverable

Unrecoverable returns an event object representing any unrecoverable event, i.e. UsageError and Nonexistent.

AnyEvent

AnyEvent returns a Math::ModInt::Event object acting as a parent for all other events. Traps for this pseudo-event will catch all events.

Object Methods

description

The object method description takes no parameters and returns a string naming the event.

is_recoverable

The object method is_recoverable takes no parameters and returns a boolean value telling whether all events of the type represented by the object are recoverable.

trap

The object method trap arranges for a given action to be performed each time an event of the type represented by the object is raised. Its argument can be a coderef to be called or one of the strings "ignore" or "warn" or "die", to ignore an event, trigger a warning message or runtime exception, respectively.

It returns a new trap object. If this object is no longer referenced, the previous behaviour is restored. Consequently, the result can be stored in a variable to keep the trap enabled, and the variable undefined to deactivate the trap.

If called in void context, however, trap declares a static handler, which is not bound to an object.

Multiple actions connected to the same event type are performed in reverse order they have been declared by trap. If an event handler calls die or exit or returns a false value, no other handlers still pending are called.

raise

The object method raise is used by library modules to trigger an event of the type represented by the object. It takes additional details as optional arguments. It returns the object it was invoked on.

isa

The object method isa can be used to inspect the event hierarchy. It takes a fully qualified type of an event object and returns a boolean value telling whether the invocant is an instance of the given type, i.e. either precisely of the same type or a in one of its subcategories.

EXPORT

By default, Math::ModInt::Event does not export anything into the caller's namespace. Each event type, though, is also the name of a constructor that can explicitly be imported.

DIAGNOSTICS

Standard warnings print "warning:" and the name of the event (like "undefined result") on stderr, followed by a caller source code location.

Standard error messages print "error:" and the name of the event (like "undefined result") on stderr, followed by a caller source code location. Unless caught in an eval block, program execution stops thereafter.

User-defined actions can issue customized messages or perform other tasks at the discretion of the programmer. If they return, program execution will either continue or be stopped with an exception, depending on whether the event was recoverable.

SEE ALSO

AUTHOR

Martin Becker, <becker-cpan-mp@cozap.com>

LICENSE AND COPYRIGHT

Copyright (c) 2010 by Martin Becker. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER OF WARRANTY

This library 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.